Customization

NISTtheDocs2Death uses two sets of templates that determine the appearance of the hosted documentation.

borg_the_docs templates

The first set of templates is used by the borg_the_docs Sub-Action to modify the Sphinx configuration.

These templates can be customized by forking this repository.

conf.py

This template file overlays the html_theme you chose for your documentation with the ntd2d theme, described next.

ntd2d/

This template directory provides a Sphinx theme that modifies your chosen documentation theme.

ntd2d/layout.html

This template file inserts standard NIST headers and footers and a dropdown menu that allows selecting different versions of your documentation.

ntd2d/static/ntd2d.css_t

This template file controls the appearance of the dropdown menu.

update_pages templates

The second set of tempaltes is used by the update_pages Sub-Action sub-action to create the pages on the hosting site that enable switching between different documentation variants.

You can customize any of these templates by copying them to a _templates/ directory at the root of your nist-pages branch and editing them to suit.

These templates use Python string format syntax (Sphinx and pages.nist.gov already fight over Jekyll templating, so we’re not getting fancy, here).

downloads.html

A section inserted into menu.html if a documentation variant has any downloadable output, e.g., PDF or ePUB.

Available subsitution keywords are:

• downloads: A pre-formatted string with each downloadable output formatted by download_item.html.

download_item.html

Formats a link to a single downloadable output.

Available subsitution keywords are:

• href: URL of the downloadable output.

• kind: Type of downloadable output, e.g., PDF or ePUB.

index.html

The default page for your documentation displayed at https://pages.nist.gov/{repository}.

Available subsitution keywords are:

• owner: The GitHub user or organization for your repository.

• repository: The name of your repository.

• variants: The result of filling the variants.html template.

menu.html

The dropdown menu that allows selecting different branches and tags of your documentation.

Available subsitution keywords are:

• downloads: The result of filling the downloads.html template.

• tree_url: The GitHub URL corresponding to the active tag or branch.

• variant: The name of the active tag or branch.

• variants: The result of filling the variants.html template.

ntd2d_active.css

Style sheet that controls the appearance of the active tag or branch in the dropdown menu.

Available subsitution keywords are:

• variant: The name of the active tag or branch.

variants.html

Lists tags and branches that are configured to serve documentation with this Action.

Available subsitution keywords are:

• branches: A pre-formatted string with each git branch formatted by variant_item.html.

• latest: A pre-formatted string with the HEAD of the default GitHub branch formatted by variant_item.html.

• stable: A pre-formatted string with the stable_version that has the highest version identifier, as formatted by variant_item.html.

• stable_versions: A pre-formatted string with the tags or branches that satisfy the PEP 440 version specification and aren’t pre-releases, each formatted by variant_item.html.

• versions: A pre-formatted string with the tags or branches that satisfy the PEP 440 version specification, each formatted by variant_item.html.

variant_item.html

Formats a link to a single tag or branch.

Available subsitution keywords are:

• href: URL of the downloadable output.

• kind: Type of downloadale output, e.g., PDF or ePUB.