Generating ARMI docs also in PDF format (#2072)

terrapower · Feb 3, 2025 · 13c2dbb · 13c2dbb
1 parent 3f3f8df
commit 13c2dbb
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 34 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -37,7 +37,8 @@ jobs:
           git submodule init
           git submodule update
           make html
-      - name: deploy
+          make simplepdf
+      - name: Deploy
         if: github.ref == 'refs/heads/main'
         uses: JamesIves/[email protected]
         with:
@@ -46,10 +47,16 @@ jobs:
           branch: main
           folder: doc/_build/html
           target-folder: armi
-      - name: Archive Docs from PR
+      - name: Archive HTML Docs
         if: github.ref != 'refs/heads/main'
         uses: actions/upload-artifact@v4
         with:
-          name: pr-docs
+          name: html-docs
           path: doc/_build/html
           retention-days: 5
+      - name: Archive PDF Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: pdf-docs
+          path: doc/_build/simplepdf/ARMI.pdf
+          retention-days: 5
diff --git a/doc/.static/css/theme_fixes.css b/doc/.static/css/theme_fixes.css
@@ -10,4 +10,14 @@
    .wy-table-responsive {
       overflow: visible !important;
    }
-}
+}
+
+.rst-content table.docutils {
+    margin: 0;
+    padding: 0;
+    font-size: 10pt;
+}
+
+img {
+   max-width: 100% !important;
+}
diff --git a/doc/.static/dochelpers.py b/doc/.static/dochelpers.py
@@ -79,7 +79,8 @@ def createListTable(
 
     Returns
     -------
-        str: RST list-table string
+    str
+        RST list-table string
     """
     # we need valid input data
     assert len(rows) > 1, "Not enough input data."
@@ -110,21 +111,24 @@ def createListTable(
 
 def generateParamTable(klass, fwParams, app=None):
     """
-    Return a string containing one or more restructured text list tables containing
-    parameter descriptions for the passed ArmiObject class.
+    Return a string containing one or more restructured text list tables containing parameter
+    descriptions for the passed ArmiObject class.
 
     Parameters
     ----------
     klass : ArmiObject subclass
         The Class for which parameter tables should be generated
-
     fwParams : ParameterDefinitionCollection
-        A parameter definition collection containing the parameters that are always
-        defined for the passed ``klass``. The rest of the parameters come from the
-        plugins registered with the passed ``app``
-
+        A parameter definition collection containing the parameters that are always defined for the
+        passed ``klass``. The rest of the parameters come from the plugins registered with the
+        passed ``app``
     app : App, optional
         The ARMI-based application to draw plugins from.
+
+    Returns
+    -------
+    str
+        RST-formatted string table
     """
     from armi import apps
 
@@ -142,13 +146,16 @@ def generateParamTable(klass, fwParams, app=None):
                 defs[plugin] = pDefs
 
     headerContent = """
+.. container:: break_before ssp-landscape
+
     .. list-table:: {} Parameters from {{}}
-       :header-rows: 1
-       :widths: 30 40 30
+        :class: ssp-tiny
+        :widths: 30 40 30
+        :header-rows: 1
 
-       * - Name
-         - Description
-         - Units
+        * - Name
+          - Description
+          - Units
     """.format(
         klass.__name__
     )
@@ -160,9 +167,9 @@ def generateParamTable(klass, fwParams, app=None):
         content.append(f".. _{srcName}-{klass.__name__}-param-table:")
         pluginContent = headerContent.format(srcName)
         for pd in pdefs:
-            pluginContent += f"""   * - {pd.name}
-         - {escapeSpecialCharacters(str(pd.description))}
-         - {escapeSpecialCharacters(pd.units)}
+            pluginContent += f"""    * - {pd.name}
+          - {escapeSpecialCharacters(str(pd.description))}
+          - {escapeSpecialCharacters(pd.units)}
     """
         content.append(pluginContent + "\n")
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -293,6 +293,7 @@ def setup(app):
     "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
     "sphinx_rtd_theme",  # needed here for loading jquery in sphinx 6
+    "sphinx_simplepdf",
     "sphinxcontrib.apidoc",
     "sphinxcontrib.jquery",  # see https://github.com/readthedocs/sphinx_rtd_theme/issues/1452
     "sphinxcontrib.plantuml",
@@ -395,17 +396,17 @@ def setup(app):
 
 # Theme options are theme-specific and customize the look and feel of a theme further.
 html_theme_options = {
-    "style_external_links": True,
-    "style_nav_header_background": "#233C5B",  # TP blue looks better than green
-    "logo_only": False,
     "display_version": True,
+    "logo_only": False,
     "prev_next_buttons_location": "bottom",
+    "style_external_links": True,
+    "style_nav_header_background": "#233C5B",  # TP blue looks better than green
     "vcs_pageview_mode": "",
     # Toc options
     "collapse_navigation": True,
-    "sticky_navigation": True,
-    "navigation_depth": 4,
     "includehidden": True,
+    "navigation_depth": 4,
+    "sticky_navigation": True,
     "titles_only": False,
 }
 
@@ -432,11 +433,11 @@ def setup(app):
 htmlhelp_basename = "ARMIdoc"
 
 html_context = {
+    "conf_py_path": "/doc/",  # Path in the checkout to the docs root
     "display_github": True,  # Integrate GitHub
-    "github_user": "terrapower",  # Username
     "github_repo": "armi",  # Repo name
+    "github_user": "terrapower",  # Username
     "github_version": "main",  # Version
-    "conf_py_path": "/doc/",  # Path in the checkout to the docs root
 }
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -523,3 +524,8 @@ def setup(app):
 if "win32" in sys.platform:
     image_converter = "magick"
     image_converter_args = ["convert"]
+
+simplepdf_vars = {
+    "links": "#FF3333",
+    "primary": "#333333",
+}
diff --git a/doc/release/0.5.rst b/doc/release/0.5.rst
@@ -26,6 +26,7 @@ Bug Fixes
 
 Quality Work
 ------------
+#. Adding PDF versions of the ARMI docs. (`PR#2072 <https://github.com/terrapower/armi/pull/2072>`_)
 #. TBD
 
 

diff --git a/doc/user/inputs.rst b/doc/user/inputs.rst
@@ -1591,9 +1591,9 @@ through ``self.cs``.
 
 
 .. exec::
-    from armi import settings
     import textwrap
     from dochelpers import escapeSpecialCharacters
+    from armi import settings
 
     def looks_like_path(s):
         """Super quick, not robust, check if a string looks like a file path."""
@@ -1605,23 +1605,30 @@ through ``self.cs``.
     cs = settings.Settings()
 
     # User textwrap to split up long words that mess up the table.
+    ws = "    "
+    ws2 = ws + "    "
+    ws3 = ws2 + "  "
     wrapper = textwrap.TextWrapper(width=25, subsequent_indent='')
     wrapper2 = textwrap.TextWrapper(width=10, subsequent_indent='')
-    content = '\n.. list-table:: ARMI Settings\n   :header-rows: 1\n   :widths: 20 30 15 15\n    \n'
-    content += '   * - Name\n     - Description\n     - Default\n     - Options\n'
+    content = '\n.. container:: break_before ssp-landscape\n\n'
+    content += ws + '.. list-table:: ARMI Settings\n'
+    content += ws2 + ':widths: 25 25 10 25\n'
+    content += ws2 + ':class: ssp-tiny\n'
+    content += ws2 + ':header-rows: 1\n\n'
+    content += ws2 + '* - Name\n' + ws3 + '- Description\n' + ws3 + '- Default\n' + ws3 + '- Options\n'
 
     for setting in sorted(cs.values(), key=lambda s: s.name):
-        content += '   * - {}\n'.format(' '.join(wrapper.wrap(setting.name)))
+        content += ws2 + '* - {}\n'.format(' '.join(wrapper.wrap(setting.name)))
         description = escapeSpecialCharacters(str(setting.description) or "")
-        content += "     - {}\n".format(" ".join(wrapper.wrap(description)))
+        content += ws3 + "- {}\n".format(" ".join(wrapper.wrap(description)))
         default = str(getattr(setting, 'default', None)).split("/")[-1]
         options = str(getattr(setting,'options','') or '')
         if looks_like_path(default):
             # We don't want to display default file paths in this table.
             default = ""
             options = ""
-        content += '     - {}\n'.format(' '.join(['``{}``'.format(wrapped) for wrapped in wrapper2.wrap(default)]))
-        content += '     - {}\n'.format(' '.join(['``{}``'.format(wrapped) for wrapped in wrapper.wrap(options)]))
+        content += ws3 + '- {}\n'.format(' '.join(['``{}``'.format(wrapped) for wrapped in wrapper2.wrap(default)]))
+        content += ws3 + '- {}\n'.format(' '.join(['``{}``'.format(wrapped) for wrapped in wrapper.wrap(options)]))
 
     content += '\n'
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -116,6 +116,7 @@ docs = [
     "sphinxcontrib-jquery==4.1", # Handle missing jquery errors
     "jupyter-contrib-nbextensions", # A collections of JS extensions for jupyter notebooks
     "lxml<5.0.0", # Needed because the dep above is no longer an active project
+    "sphinx-simplepdf==1.6.0", # Used to make PDF versions of the docs
 ]
 
 [project.scripts]
-Original file line number
+Diff line change
@@ Expand Up / @@ -26,6 +26,7 @@ Bug Fixes @@
     Quality Work
     ------------
+    #. Adding PDF versions of the ARMI docs. (`PR#2072 <https://github.com/terrapower/armi/pull/2072>`_)
     #. TBD
@@ Expand Down @@