Customization¶
NISTtheDocs2Death uses two sets of templates that determine the appearance of the hosted documentation.
Assimilation templates¶
The first set of templates is used by
assimilate_theme()
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.
Pages templates¶
The second set of tempaltes is used by
update_pages()
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.
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 theHEAD
of the default GitHub branch formatted by variant_item.html.stable
: A pre-formatted string with thestable_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.