ntd2d Sub-Action

This GitHub action is invoked by the main Docs4NIST Action to move built documentation into your designated pages-branch.

Usage

This action is invoked as a step of the composite workflow of the Docs4NIST 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: ''
    include-header-footer: true
    hidden: false

Note

This action must be synchronized with the invoked version of the Docs4NIST Action, but “usnistgov/Docs4NIST/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.

include-header-footer

Whether to insert the NIST header and footer. This content conflicts with, e.g., sphinx_rtd_theme.

hidden

When true, removes the active branch or tag from the version dropdown menu.

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 a Repository object,

• invokes update_pages().