-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
documentation: Use Sphinx for building HTML documentation #87
Open
asullivan-blze
wants to merge
6
commits into
main
Choose a base branch
from
asullivan-svreng-619-sphinx-documentation
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements Sphinx to have some HTML-based documentation, so referencing documentation that is not directly in Python source code files is possible. While this branch is not intended to fully document all available functions, this _does_ provide the necessary framework which allows future documentation of the code -- within the code itself by way of docstrings -- to auto-generate updated documentation. Additionally, while not strictly needed -- and I'll probably look into making this a change that's available in boardwalk/boardwalkd themselves by default -- I built some tooling to make pretty HTML output of the `--help` documentation for commands using rich-click. Right now this isn't baked into the existing documentation build process, though I _might_ look into seeing if it can be in the future. (I made an attempt, at least, but the Bash script which does this was the 'good enough' compromise, since it felt like I was fighting with Python for an excessive length of time to get it to do what I wanted it to do. Changes that would be needed on the main Backblaze/boardwalk repository are the usual ones when enabling GitHub Pages; for my fork, this was -- after the first run of the workflow to build and populate the `gh-pages` branch -- set the Repository's GitHub Pages settings to deploy from a branch, using the `gh-pages` branch, and from the root. Aside from that, the Sphinx documentation will auto-publish on push to the main branch, or on a version tag being pushed/created.
This was an issue caused by the fact that my local development environment is running, surprise surprise, Python 3.12, and the Actions workflows are running 3.11. PEP 701, implemented in Python 3.12, makes it so the following pattern would function as expected. ```python release = f"{lib_version("boardwalk")}" ``` https://docs.python.org/3/whatsnew/3.12.html#pep-701-syntactic-formalization-of-f-strings As a note discovered while researching this issue, Python 3.13 is now released; as such, eventually -- not in this PR, which is effectively just documentation -- the minimum Python version will be shifted to 3.12.
- Cleans up code bits used during development - Removes the Git SHA from the generated page footer; we still have the short SHA and the version in the page heading, so nothing is really missing by not including this.
asullivan-blze
added
documentation
Improvements or additions to documentation
enhancement
New feature or request
CI/CD
Items affecting GitHub Actions CI/CD
labels
Nov 8, 2024
I've opted to narrow the scope to just adding the ability to build documentation via Sphinx; if a developer needs the documentation, it's easy enough to build, so let's not add complexity to the GitHub workflow process. |
There's little reason to include the files that would get built and/or rebuilt by Sphinx. Avoids bloated diffs.
asullivan-blze
force-pushed
the
asullivan-svreng-619-sphinx-documentation
branch
from
November 13, 2024 01:14
9523bfc
to
7d61040
Compare
agouldingbb
approved these changes
Nov 13, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
CI/CD
Items affecting GitHub Actions CI/CD
documentation
Improvements or additions to documentation
enhancement
New feature or request
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What and why?
Implements Sphinx to have some HTML-based documentation, so referencing documentation that is
not directly in Python source code files is possible. While this branch is not intended to
fully document all available functions, this does provide the necessary framework which
allows future documentation of the code -- within the code itself by way of docstrings -- to
auto-generate updated documentation.
Additionally, while not strictly needed -- and I'll probably look into making this a
change that's available in boardwalk/boardwalkd themselves by default -- I built some
tooling to make pretty HTML output of the
--help
documentation for commands usingrich-click. Right now this isn't baked into the existing documentation build process,
though I might look into seeing if it can be in the future. (I made an attempt, at
least, but the Bash script which does this was the 'good enough' compromise, since
it felt like I was fighting with Python for an excessive length of time to get it to
do what I wanted it to do.
Dependabot updates
As a bit of an enhancement I found while looking into how to use workflows to publish pages,
.github/dependabot.yml
was created to allow monitoring of not only the Python dependencies, but also the versions of the GitHub Actions.How was this tested?
docs/Makefile
, viamake html
.make docs
added into it as a target (which just chains to the Sphinx Makefile).Checklist
version
in the[tool.poetry]
section ofthe
pyproject.toml
file (if applicable)?Closes internal ticket SVRENG-619.