diff --git a/action.yml b/action.yml index 5f46aaa..fce59b7 100644 --- a/action.yml +++ b/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: | diff --git a/docs/customization.rst b/docs/customization.rst index 5ad684e..6be518a 100644 --- a/docs/customization.rst +++ b/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. diff --git a/docs/nistthedocs2death.rst b/docs/nistthedocs2death.rst index 6df2e39..d7a9f0e 100644 --- a/docs/nistthedocs2death.rst +++ b/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,7 +134,7 @@ project. Whether the results of pull requests should be pushed to :ref:`PAGES_BRANCH`. For -`security ` +`security `_ `reasons `_, this is impossible for pull requests from repository forks, but it is generally undesirable in any case (they appear with cryptic names like @@ -141,6 +142,14 @@ generally undesirable in any case (they appear with cryptic names like 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 `_. +This content conflicts with, e.g., +`sphinx_rtd_theme `_. + Implementation -------------- diff --git a/docs/ntd2d.rst b/docs/ntd2d.rst index 8b40391..f8396cf 100644 --- a/docs/ntd2d.rst +++ b/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 `_. +This content conflicts with, e.g., +`sphinx_rtd_theme `_. + Outputs ------- diff --git a/ntd2d/action.yml b/ntd2d/action.yml index 2c9a69d..3621224 100644 --- a/ntd2d/action.yml +++ b/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' diff --git a/ntd2d/entrypoint.py b/ntd2d/entrypoint.py index 215c8cf..c7d5efc 100755 --- a/ntd2d/entrypoint.py +++ b/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 diff --git a/ntd2d/ntd2d.py b/ntd2d/ntd2d.py index 8907eff..467748f 100755 --- a/ntd2d/ntd2d.py +++ b/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()) diff --git a/ntd2d/ntd2d_action/files/templates/header_footer_script.html b/ntd2d/ntd2d_action/files/templates/header_footer_script.html new file mode 100644 index 0000000..1e9e211 --- /dev/null +++ b/ntd2d/ntd2d_action/files/templates/header_footer_script.html @@ -0,0 +1 @@ + diff --git a/ntd2d/ntd2d_action/files/templates/ntd2d/layout.html b/ntd2d/ntd2d_action/files/templates/ntd2d/layout.html index f2bf688..7b9a64f 100644 --- a/ntd2d/ntd2d_action/files/templates/ntd2d/layout.html +++ b/ntd2d/ntd2d_action/files/templates/ntd2d/layout.html @@ -5,7 +5,7 @@ - + {header_footer_script} {{% endblock %}} diff --git a/ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t b/ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t index ea66e39..003b912 100644 --- a/ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t +++ b/ntd2d/ntd2d_action/files/templates/ntd2d/static/ntd2d.css_t @@ -1,4 +1,4 @@ -@import url("{inherited_theme}.css"); +@import url("{inherited_css}"); .dropbtn {{ diff --git a/ntd2d/ntd2d_action/sphinxdocs.py b/ntd2d/ntd2d_action/sphinxdocs.py index 40da9ef..69661c7 100644 --- a/ntd2d/ntd2d_action/sphinxdocs.py +++ b/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)