This is a Github action that looks for Sphinx documentation folders in your project. It builds the documentation using Sphinx and any errors in the build process are bubbled up as Github status checks.
The main purposes of this action are:
-
Run a CI test to ensure your documentation still builds.
-
Allow contributors to get build errors on simple doc changes inline on Github without having to install Sphinx and build locally.
Create a workflow for the action, for example:
name: "Pull Request Docs Check"
on:
- pull_request
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: usnistgov/sphinx-action@master
with:
docs-folder: "docs/"
-
If you have any Python dependencies that your project needs (themes, build tools, etc) then place them in a requirements.txt file inside your docs folder.
-
If you have multiple sphinx documentation folders, please use multiple
uses
blocks.
For a full example repo using this action including advanced usage, take a look at https://github.com/ammaraskar/sphinx-action-test
Some really good actions that work well with this one are
actions/upload-artifact
and usnistgov/NISTtheDocs2Death
.
You can use these to make built HTML and PDFs available as artifacts:
- uses: actions/upload-artifact@3
with:
name: DocumentationHTML
path: docs/_build/html/
Or to push docs changes automatically to a nist-pages
branch:
- uses: usnistgov/NISTtheDocs2Death@main
with:
docs-folder: docs/
For a full fledged example of an older version of this in action take a look at: https://github.com/ammaraskar/sphinx-action-test
If you wish to customize the command used to build the docs (defaults to
make html
), you can provide a build-command
in the with
block. For
example, to invoke sphinx-build directly you can use:
- uses: usnistgov/sphinx-action@master
with:
docs-folder: "docs/"
build-command: "sphinx-build -b html . _build"
If there's system level dependencies that need to be installed for your
build, you can use the pre-build-command
argument like so:
- uses: usnistgov/sphinx-action@master
with:
docs-folder: "docs2/"
pre-build-command: "apt-get update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
build-command: "make latexpdf"
although a more expedient way to build LaTeX documentation is to use
usnistgov/sphinx-action@latexpdf
- uses: usnistgov/sphinx-action@latexpdf
with:
docs-folder: "docs2/"
python -m unittest
Please use black for formatting:
black entrypoint.py sphinx_action tests