Customization
=============

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

Assimilation templates
----------------------

The first set of templates is used by
:meth:`~ntd2d_action.sphinxdocs.BorgedSphinxDocs.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
<https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme>`_
you chose for your documentation with the ``ntd2d`` theme, described next.

.. NTD2DTHEME:

|ntd2d|_
~~~~~~~~

This template directory provides a `Sphinx theme
<https://www.sphinx-doc.org/en/master/development/theming.html>`_ that
modifies your chosen documentation theme.

|layout.html|_
..............

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

Some Sphinx themes may display the NIST footer at the top of the page.
This occurs when the theme's CSS conflicts with the dynamically injected
NIST header and footer elements.

To fix this, create a custom ``layout.html`` template in your
``_templates/`` directory:

.. code-block:: jinja

   {% extends "!layout.html" %}
   {%- block extrahead %}
     {{ super() }}
     <!-- Fix NIST footer positioning -->
     <style>
       /* Target the wrapper divs created by NIST JavaScript */
       #nistheadergoeshere {
         position: relative !important;
         display: block !important;
         z-index: 10;
         width: 100%;
       }
       #nistfootergoeshere {
         position: relative !important;
         display: block !important;
         clear: both !important;
         margin-top: 2rem !important;
         width: 100%;
       }
       /* Also target the actual footer/header elements inside */
       #nistfootergoeshere footer,
       #nistheadergoeshere header {
         position: relative !important;
         display: block !important;
       }
       /* Ensure theme content doesn't overlap */
       .wy-grid-for-nav {
         position: relative;
         z-index: 1;
       }
       .wy-nav-content-wrap {
         min-height: calc(100vh - 200px);
       }
       .rst-footer-buttons {
         margin-bottom: 2rem;
       }
     </style>
   {%- endblock %}

Add ``templates_path = ['_templates']`` to your ``conf.py`` if not already
present. The ``.wy-*`` selectors target ``sphinx_rtd_theme``; other themes may
require different CSS adjustments.

|static/ntd2d.css_t|_
.....................

This template file controls the appearance of the dropdown menu.

.. |conf.py|  replace:: :file:`conf.py`
.. _conf.py:  https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/conf.py
.. |ntd2d|    replace:: :file:`ntd2d/`
.. _ntd2d:    https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/ntd2d/
.. |layout.html|  replace:: :file:`ntd2d/layout.html`
.. _layout.html:  https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/ntd2d/layout.html
.. |static/ntd2d.css_t|  replace:: :file:`ntd2d/static/ntd2d.css_t`
.. _static/ntd2d.css_t:  https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t

Pages templates
--------------------------

The second set of templates is used by
:meth:`~ntd2d_action.repository.Repository.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
:file:`_templates/` directory at the root of your `nist-pages` branch and
editing them to suit.

These templates use `Python string format syntax
<https://docs.python.org/3/tutorial/inputoutput.html#the-string-format-method>`_
(Sphinx and pages.nist.gov already fight over Jekyll templating, so we're
not getting fancy, here).

.. _DOWNLOADS_HTML:

|downloads.html|_
~~~~~~~~~~~~~~~~~

A section inserted into :ref:`MENU_HTML` if a documentation variant has
any downloadable output, e.g., PDF or ePUB.

Available substitution keywords are:

- ``downloads``: A pre-formatted string with each downloadable output
  formatted by :ref:`DOWNLOAD_ITEM_HTML`.

.. _DOWNLOAD_ITEM_HTML:

|download_item.html|_
~~~~~~~~~~~~~~~~~~~~~

Formats a link to a single downloadable output.

Available substitution keywords are:

- ``href``: URL of the downloadable output.
- ``kind``: Type of downloadable output, e.g., PDF or ePUB.

.. _INDEX_HTML:

|index.html|_
~~~~~~~~~~~~~

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

Available substitution keywords are:

- ``owner``: The GitHub
  `user or organization
  <https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts>`_
  for your repository.
- ``repository``: The name of your repository.
- ``variants``: The result of filling the :ref:`VARIANTS_HTML` template.

.. _MENU_HTML:

|menu.html|_
~~~~~~~~~~~~

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

Available substitution keywords are:

- ``downloads``: The result of filling the :ref:`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 :ref:`VARIANTS_HTML` template.

.. _NTD2D_ACTIVE_CSS:

|ntd2d_active.css|_
~~~~~~~~~~~~~~~~~~~

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

Available substitution keywords are:

- ``variant``: The name of the active tag or branch.

.. _VARIANTS_HTML:

|variants.html|_
~~~~~~~~~~~~~~~~

Lists tags and branches that are :ref:`configured <USAGE>` to serve
documentation with this Action.

Available substitution keywords are:

- ``branches``: A pre-formatted string with each git branch formatted by
  :ref:`VARIANT_ITEM_HTML`.
- ``latest``: A pre-formatted string with the ``HEAD`` of the
  `default GitHub branch
  <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch>`_
  formatted by :ref:`VARIANT_ITEM_HTML`.
- ``stable``: A pre-formatted string with the ``stable_version`` that has the
  highest version identifier, as formatted by :ref:`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 <https://peps.python.org/pep-0440/#pre-releases>`_,
  each formatted by :ref:`VARIANT_ITEM_HTML`.
- ``versions``: A pre-formatted string with the tags or branches that
  satisfy the :pep:`440` version specification, each formatted by
  :ref:`VARIANT_ITEM_HTML`.

.. _VARIANT_ITEM_HTML:

|variant_item.html|_
~~~~~~~~~~~~~~~~~~~~~

Formats a link to a single tag or branch.

Available substitution keywords are:

- ``href``: URL of the downloadable output.
- ``kind``: Type of downloadable output, e.g., PDF or ePUB.


.. |downloads.html|   replace:: :file:`downloads.html`
.. _downloads.html:   https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/downloads.html
.. |download_item.html| replace:: :file:`download_item.html`
.. _download_item.html: https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/download_item.html
.. |index.html|       replace:: :file:`index.html`
.. _index.html:       https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/index.html
.. |menu.html|        replace:: :file:`menu.html`
.. _menu.html:        https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/menu.html
.. |ntd2d_active.css| replace:: :file:`ntd2d_active.css`
.. _ntd2d_active.css: https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/ntd2d_active.css
.. |variants.html|    replace:: :file:`variants.html`
.. _variants.html:    https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/variants.html
.. |variant_item.html| replace:: :file:`variant_item.html`
.. _variant_item.html: https://github.com/usnistgov/Docs4NIST/blob/main/ntd2d/ntd2d_action/files/templates/variant_item.html