ntd2d
Sub-Action¶
This GitHub action is invoked by the main NISTtheDocs2Death Action to move built documentation into your designated pages-branch.
Usage¶
This action is invoked as a step of the composite workflow of the NISTtheDocs2Death Action. There is no reason to invoke this action yourself.
- name: Commit documentation changes
uses: ./../../_actions/current/ntd2d
with:
docs-folder: docs/
default-branch: 'main'
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 epub
pre-build-command: ''
apt-packages: ''
pip-requirements: ''
conda-environment: ''
Note
This action must be synchronized with the invoked version of the
NISTtheDocs2Death Action, but
“usnistgov/NISTtheDocs2Death/borg_the_docs@${{ github.action_ref }}
”
doesn’t work,
hence the clumsy uses:
statement.
Inputs¶
docs-folder
¶
The folder containing your Sphinx configuration.
default-branch
¶
The default branch configured in GitHub.
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 to build your html documentation.
build-epub-command
¶
The command used to build your ePUB documentation.
build-pdf-command
¶
The command used to build your PDF documentation.
pre-build-command
¶
Run 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.
Outputs¶
borged-build-folder
¶
The folder containing the Sphinx build outputs.
Implementation¶
This action implements a Docker workflow step.
The Docker ENTRYPOINT
installs any specified apt-packages, pip-requirements, and conda-environment,
wraps the Sphinx configuration directory in a
BorgedSphinxDocs
object,invokes
assimilate_theme()
executes any pre-build-command,
invokes
build_docs()
for html and any other formats specified in formats,wraps the
GITHUB_REPOSITORY
in aRepository
object,invokes
update_pages()
.