Introspect theme to find its CSS (#10)

* Obtain css from `html_theme` (fixes #9)
* Make NIST header/footer optional (`--insert-header-footer`)

   NIST header/footer conflicts with [sphinx_rtd_theme](https://sphinx-rtd-theme.readthedocs.io/).

action.yml

@@ -73,6 +73,16 @@ inputs:
     options:
       - true
       - false
+  insert-header-footer:
+    description:
+      Whether to insert the NIST branding headers and footers
+      (which are incompatible with sphinx_rtd_theme).
+    # Idiot GitHub Actions inputs doesn't support 'type'.
+    # https://stackoverflow.com/questions/76292948/github-action-boolean-input-with-default-value
+    default: 'true'
+    options:
+      - true
+      - false
 runs:
   using: "composite"
   steps:
@@ -121,6 +131,7 @@ runs:
         apt-packages: ${{ inputs.apt-packages }}
         pip-requirements: ${{ inputs.pip-requirements }}
         conda-environment: ${{ inputs.conda-environment }}
+        insert-header-footer: ${{ inputs.insert-header-footer }}
     - name: Change ownership
       shell: bash
       run: |

docs/customization.rst

@@ -52,7 +52,7 @@ This template file controls the appearance of the dropdown menu.
 Pages templates
 --------------------------
 
-The second set of tempaltes is used by
+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.

docs/nistthedocs2death.rst

@@ -39,6 +39,7 @@ as :file:`.github/workflows/NISTtheDocs2Death.yml`:
              pip-requirements: ''
              conda-environment: ''
              push-pulls-pages: false
+             include-header-footer: true
 
 Inputs
 ------
@@ -133,14 +134,22 @@ project.
 
 Whether the results of pull requests should be pushed to
 :ref:`PAGES_BRANCH`.  For
-`security <https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/>`
+`security <https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/>`_
 `reasons <https://securitylab.github.com/research/github-actions-preventing-pwn-requests/>`_,
 this is impossible for pull requests from repository forks, but it is
 generally undesirable in any case (they appear with cryptic names like
 `merge_1234` and are redundant to the branch the pull is from).  As long as
 this action is set to run `on: push`, then any build products from branches
 in the same repository will appear at :ref:`PAGES_URL`.
 
+``include-header-footer``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whether to insert the
+`NIST header and footer <https://pages.nist.gov/nist-header-footer>`_.
+This content conflicts with, e.g.,
+`sphinx_rtd_theme <https://sphinx-rtd-theme.readthedocs.io/>`_.
+
 Implementation
 --------------
 

docs/ntd2d.rst

@@ -31,6 +31,7 @@ yourself.
         apt-packages: ''
         pip-requirements: ''
         conda-environment: ''
+        include-header-footer: true
 
 .. note::
 
@@ -141,6 +142,14 @@ The path to the pip requirements file, relative to the root of the project.
 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 <https://pages.nist.gov/nist-header-footer>`_.
+This content conflicts with, e.g.,
+`sphinx_rtd_theme <https://sphinx-rtd-theme.readthedocs.io/>`_.
+
 
 Outputs
 -------

ntd2d/action.yml

@@ -63,6 +63,16 @@ inputs:
       The path to the Conda environment file, relative to the root of the
       project.
     required: false
+  insert-header-footer:
+    description:
+      Whether to insert the NIST branding headers and footers
+      (which are incompatible with sphinx_rtd_theme).
+    # Idiot GitHub Actions inputs doesn't support 'type'.
+    # https://stackoverflow.com/questions/76292948/github-action-boolean-input-with-default-value
+    default: 'true'
+    options:
+      - true
+      - false
 outputs:
   borged-docs-folder:
     description: 'The folder containing modified Sphinx configuration'

ntd2d/entrypoint.py

@@ -36,7 +36,10 @@ def main():
             requirements = pathlib.Path(requirements)
             if requirements.is_file():
                 gha_utils.debug(f"pip installing", use_subprocess=True)
-                subprocess.check_call(["pip", "install", "-r", requirements.as_posix()])
+                subprocess.run(["pip", "install", "-r", requirements.as_posix()],
+                               bufsize=1,
+                               text=True,
+                               check=True)
 
     # Install any Conda packages requested
     environment = os.environ['INPUT_CONDA-ENVIRONMENT']
@@ -51,14 +54,14 @@ def main():
                                 "--name", "base",
                                 "--solver", "libmamba",
                                 "--file", environment.as_posix()],
-                                bufsize=1,
-                                text=True,
-                                check=True)
+                               bufsize=1,
+                               text=True,
+                               check=True)
                 subprocess.run(["conda", "list",
                                 "--name", "base"],
-                                bufsize=1,
-                                text=True,
-                                check=True)
+                               bufsize=1,
+                               text=True,
+                               check=True)
 
     # Actually NIST the Docs 2 Death
     # This needs to be a subprocess so that it sees packages installed above

ntd2d/ntd2d.py

@@ -13,7 +13,9 @@ def main():
     with gha_utils.group("Borg the Docs", use_subprocess=True):
         original_docs = SphinxDocs(docs_dir=os.environ['INPUT_DOCS-FOLDER'])
         docs = BorgedSphinxDocs(original_docs=original_docs)
-        docs.assimilate_theme(name="ntd2d")
+        insert_header_footer = (os.environ['INPUT_INSERT-HEADER-FOOTER'] == "true")
+        docs.assimilate_theme(name="ntd2d",
+                              insert_header_footer=insert_header_footer)
 
         gha_utils.set_output("borged-build-folder", docs.build_dir.as_posix())
 

ntd2d/ntd2d_action/files/templates/header_footer_script.html

@@ -0,0 +1 @@
+<script src="https://pages.nist.gov/nist-header-footer/js/nist-header-footer.js" type="text/javascript" defer="defer"></script>

ntd2d/ntd2d_action/files/templates/ntd2d/layout.html

@@ -5,7 +5,7 @@
 
   <link rel="stylesheet" href="https://pages.nist.gov/nist-header-footer/css/nist-combined.css">
   <script src="https://code.jquery.com/jquery-3.6.2.min.js" type="text/javascript" defer="defer"></script>
-  <script src="https://pages.nist.gov/nist-header-footer/js/nist-header-footer.js" type="text/javascript" defer="defer"></script>
+  {header_footer_script}
 {{% endblock %}}
 
 

ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t

@@ -1,4 +1,4 @@
-@import url("{inherited_theme}.css");
+@import url("{inherited_css}");
 
 
 .dropbtn {{

ntd2d/ntd2d_action/sphinxdocs.py

@@ -8,11 +8,14 @@
 import pathlib
 import shlex
 import shutil
+from sphinx.application import Sphinx
+from sphinx.theming import HTMLThemeFactory
 import subprocess
 import tempfile
 
 from .files import ConfFile
 from .files import SphinxLog, BorgedConfFile, TemplateHierarchy
+from .files.template import FileTemplate
 
 
 class SphinxDocs:
@@ -45,6 +48,18 @@ def epub_file(self):
     def pdf_file(self):
         return self.build_dir / "latex" / f"{self.conf.project.lower()}.pdf"
 
+    @property
+    def stylesheet(self):
+        app = Sphinx(srcdir=self.source_dir,
+                     confdir=self.source_dir,
+                     outdir=self.build_dir,
+                     doctreedir=self.build_dir / "doctrees",
+                     buildername="html")
+        theme_factory = HTMLThemeFactory(app)
+        theme = theme_factory.create(app.config.html_theme)
+
+        return theme.get_config("theme", "stylesheet")
+
     def build_docs(self, build_command):
         """Build Sphinx Documentation
 
@@ -126,12 +141,19 @@ def make_conf_file(self):
     def inherited_theme(self):
         return self.original_docs.conf.html_theme
 
-    def assimilate_theme(self, name):
+    def assimilate_theme(self, name, insert_header_footer=True):
         """Replace configuration directory with customized html theme."""
 
+        if insert_header_footer:
+            header_footer = FileTemplate(name="header_footer_script.html").read()
+        else:
+            header_footer = ""
+
         self.theme = TemplateHierarchy(name=name,
                                        destination_dir=self.conf.theme_path,
-                                       inherited_theme=self.inherited_theme)
+                                       inherited_theme=self.inherited_theme,
+                                       inherited_css=self.stylesheet,
+                                       header_footer_script=header_footer)
         self.theme.write()
 
         self.conf.set_html_theme(name=name)