Add documentation (#1)

* Flesh out documentation

* Add note about YAML syntax for formats

* Rename "annex" to "active"

More accurately describe what this additional css is for

* Convert document structure to sub-sections with cross-references

* Add templates for individual variant or download items

* Improve phrasing

* Fix grammar

* Remove unnecessary IFrame class

FileTemplate is sufficient

* Add NIST disclaimer

* Rename sub-action modules to differentiate them

* Document classes and methods

* Incorporate API documentation

README.md

@@ -31,3 +31,6 @@ host on <https://pages.nist.gov> as an approximation of
 elements, so
 [use a multiline string](https://stackoverflow.com/questions/75420197/how-to-use-array-input-for-a-custom-github-actions)
 to declare formats, as illustrated above.
+
+The self-generated documentation for this action is available at
+<https://pages.nist.gov/NISTtheDocs2Death>.

borg_the_docs/Dockerfile

@@ -8,6 +8,6 @@ RUN pip install github-action-utils
 
 ADD borg_the_docs.py /borg_the_docs.py
 ADD entrypoint.py /entrypoint.py
-ADD ntd2d_action /ntd2d_action
+ADD borg_the_docs_action /borg_the_docs_action_action
 
 ENTRYPOINT ["/entrypoint.py"]

borg_the_docs/action.yml

@@ -1,4 +1,4 @@
-name: "NISTtheDocs2Death workhorse"
+name: "Borg the docs"
 description: "Python Container to do actual work"
 author: "Jonathan Guyer"
 inputs:

borg_the_docs/borg_the_docs.py

@@ -2,7 +2,7 @@
 import github_action_utils as gha_utils
 import os
 
-from ntd2d_action.files import BorgedConfFile
+from borg_the_docs_action.files import BorgedConfFile
 
 
 def main():

borg_the_docs/ntd2d_action/files/borgedconffile.py → borg_the_docs/borg_the_docs_action/files/borgedconffile.py

@@ -9,6 +9,8 @@
 
 
 class BorgedConfFile(ConfFile):
+    """Sphinx configuration file that overlays the html theme."""
+
     def __init__(self, docs_dir, source_rel=""):
         self.original_docs_dir = pathlib.Path(docs_dir)
         borged_docs_dir = self.original_docs_dir.as_posix() + "-BORGED"
@@ -27,7 +29,7 @@ def inherited_theme(self):
         return self.configuration.get("html_theme", "default")
 
     def assimilate_theme(self, name):
-        configuration = self.read()
+        """Replace configuration directory with customized html theme."""
 
         self.theme = TemplateHierarchy(name=name,
                                        destination_dir=self.theme_path,

update_pages/ntd2d_action/files/conffile.py → borg_the_docs/borg_the_docs_action/files/conffile.py

@@ -20,6 +20,8 @@ def working_directory(path):
         os.chdir(prev_cwd)
 
 class ConfFile(File):
+    """Sphinx configuration file."""
+
     def __init__(self, docs_dir, source_rel=""):
         self.docs_dir = pathlib.Path(docs_dir)
         self.source_dir = self.docs_dir / source_rel
@@ -29,6 +31,8 @@ def __init__(self, docs_dir, source_rel=""):
 
     @property
     def configuration(self):
+        """Text of configuration file."""
+
         if self._configuration is None:
             self._configuration = self.read()
         return self._configuration

update_pages/ntd2d_action/files/file.py → borg_the_docs/borg_the_docs_action/files/file.py

@@ -1,4 +1,6 @@
 class File:
+    """Base file class
+    """
     def __init__(self):
         pass
 

borg_the_docs/ntd2d_action/files/template.py → borg_the_docs/borg_the_docs_action/files/template.py

@@ -23,7 +23,3 @@ def __init__(self, working_dir, name):
         self.template_path = working_dir / "_templates" / name
         if not self.template_path.exists():
             super().__init__(name=name)
-
-class IFrame(PagesTemplate):
-    def __init__(self, working_dir):
-        super().__init__(working_dir=working_dir, name="iframe.html")

docs/QandA.rst

@@ -0,0 +1,17 @@
+Q & A
+=====
+
+Can't I just use Read the Docs?
+-------------------------------
+
+Nope.
+
+Is there a reason?
+------------------
+
+Yep.
+
+Is it a good reason?
+--------------------
+
+Nope.

docs/borg_the_docs.rst

@@ -0,0 +1,79 @@
+.. _BORGTHEDOCS:
+
+``borg_the_docs`` Sub-Action
+============================
+
+This `GitHub action <https://docs.github.com/en/actions>`_ is invoked by
+the main :ref:`NISTTHEDOCS2DEATH` to modify the Sphinx configuration before
+building the documentation.
+
+Usage
+-----
+
+This action is invoked as a step of the composite workflow of the
+:ref:`NISTTHEDOCS2DEATH`.  There is no reason to invoke this action
+yourself.
+
+.. code-block:: yaml
+
+    - name: Add cruft to theme
+      id: borg-the-docs
+      uses: ./../../_actions/current/borg_the_docs
+      with:
+        docs-folder: 'docs/'
+        separated-layout: false
+
+.. note::
+
+   This action must be synchronized with the invoked version of the
+   :ref:`NISTTHEDOCS2DEATH`, but
+   "``usnistgov/NISTtheDocs2Death/borg_the_docs@${{ github.action_ref }}``"
+   `doesn't work
+   <https://github.com/orgs/community/discussions/41927#discussioncomment-4605881>`_,
+   hence the clumsy ``uses:`` statement.
+
+Inputs
+------
+
+``docs-folder``
+~~~~~~~~~~~~~~~
+
+The folder containing your Sphinx configuration.
+
+``separated-layout``
+~~~~~~~~~~~~~~~~~~~~
+
+Whether Sphinx is configued to have separate :file:`source/` and
+:file:`build/` directories.
+
+Outputs
+-------
+
+``borged-docs-folder``
+~~~~~~~~~~~~~~~~~~~~~~
+
+The folder containing the Sphinx configuration modified by this Action.
+
+
+Implementation
+--------------
+
+This action implements a `Docker workflow step
+<https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action>`_.
+The Docker ``ENTRYPOINT`` installs any :file:`requirements.txt` in the
+`Sphinx configuration directory
+<https://www.sphinx-doc.org/en/master/usage/configuration.html>`_, wraps
+the :file:`conf.py` file with a
+:class:`~borg_the_docs_action.files.borgedconffile.BorgedConfFile` object,
+and invokes
+:meth:`~borg_the_docs_action.files.borgedconffile.BorgedConfFile.assimilate_theme`.
+
+
+API
+~~~
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   borg_the_docs_action

docs/conf.py

@@ -7,21 +7,36 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'NISTtheDocs2Death'
-copyright = '2023, Jonathan E. Guyer'
+copyright = u'works of NIST employees are not not subject to copyright protection in the United States'
 author = 'Jonathan E. Guyer'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosummary']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here.
+import pathlib
+import sys
+
+_action_root = pathlib.Path(__file__).parents[1].resolve()
+sys.path.insert(0, (_action_root / "borg_the_docs").as_posix())
+sys.path.insert(0, (_action_root / "update_pages").as_posix())
+
+print(sys.path)
+
+autoclass_content = "both"
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'alabaster'
 html_static_path = ['_static']
+
+html_show_copyright = False