Docs4NIST Action¶
This GitHub action uses the Sphinx tool to build documentation in https://github.com/usnistgov projects and then host on https://pages.nist.gov as an approximation of ReadTheDocs.
Usage¶
This action is invoked by adding a workflow file to your repository, such
as .github/workflows/Docs4NIST.yml:
name: "Build Documentation"
on: [push, pull_request, delete]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: usnistgov/Docs4NIST@0.4
with:
docs-folder: docs/
pages-branch: 'nist-pages'
pages-url: 'https://pages.nist.gov'
formats: ''
build-html-command: make html
build-epub-command: make epub
build-pdf-command: make latexpdf
pre-build-command: ''
apt-packages: ''
pip-requirements: ''
conda-environment: ''
push-pulls-pages: false
include-header-footer: true
Inputs¶
docs-folder¶
The folder containing your Sphinx configuration.
pages-branch¶
The branch linked to your documentation server.
pages-url¶
URL of the web server for served documentation.
formats¶
Type(s) of output desired in addition to html (pdf, and/or epub).
Note
GitHub Actions’ YAML implementation does not support list or array elements, so use a multiline string to declare formats, e.g.,
formats: |-
epub
pdf
build-html-command¶
The command used by usnistgov/sphinx-action to build your html documentation.
build-epub-command¶
The command used by usnistgov/sphinx-action to build your ePUB documentation.
build-pdf-command¶
The command used by usnistgov/sphinx-action to build your PDF documentation.
pre-build-command¶
Run by usnistgov/sphinx-action before the build command. You can use this to install
system level dependencies, for example, with “apt-get update -y && apt-get
install -y perl”, although those are better installed with
apt-packages.
apt-packages¶
List of any APT packages that should be installed.
pip-requirements¶
The path to the pip requirements file, relative to the root of the project.
conda-environment¶
The path to the Conda environment file, relative to the root of the project.
push-pulls-pages¶
Whether the results of pull requests should be pushed to pages-branch. For security reasons, this is impossible for pull requests from repository forks, but it is generally undesirable in any case (they appear with cryptic names like merge_1234 and are redundant to the branch the pull is from). As long as this action is set to run on: push, then any build products from branches in the same repository will appear at pages-url.
Implementation¶
This action implements a composite workflow with the following major steps: