Skip to content
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
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

asullivan-blze
Copy link
Contributor

@asullivan-blze asullivan-blze commented Nov 8, 2024

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 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.

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?

  • Primary testing was done using Sphinx's Makefile at docs/Makefile, via make html.
  • Another test phase was when the primary Makefile in the repository root had make docs added into it as a target (which just chains to the Sphinx Makefile).

Checklist

  • Have you updated the version in the [tool.poetry] section of
    the pyproject.toml file (if applicable)?
    • Though this technically isn't a version-worthy bump, but I'll bump it regardless, since this is a decently-sized change.

Closes internal ticket SVRENG-619.

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 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
@asullivan-blze asullivan-blze marked this pull request as ready for review November 8, 2024 21:23
@asullivan-blze
Copy link
Contributor Author

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 asullivan-blze force-pushed the asullivan-svreng-619-sphinx-documentation branch from 9523bfc to 7d61040 Compare November 13, 2024 01:14
Copy link

@agouldingbb agouldingbb left a 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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants