Update doc build to py313 (#2050)

Author: opotowsky

.github/workflows/docs.yaml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
+          python-version: 3.13
       - name: Update package index
         run: sudo apt-get update
       - name: Install mpi libs

armi/physics/neutronics/crossSectionGroupManager.py

@@ -63,7 +63,6 @@
 from armi.physics.neutronics.const import CONF_CROSS_SECTION
 from armi.reactor import flags
 from armi.reactor.components import basicShapes
-from armi.reactor.converters.blockConverters import stripComponents
 from armi.reactor.flags import Flags
 from armi.utils import safeCopy
 from armi.utils.units import C_TO_K, TRACE_NUMBER_DENSITY
@@ -710,6 +709,8 @@ def _makeRepresentativeBlock(self):
 
     def _getNucTempHelper(self):
         """All candidate blocks are used in the average."""
+        from armi.reactor.converters.blockConverters import stripComponents
+
         nvt = np.zeros(len(self.allNuclidesInProblem))
         nv = np.zeros(len(self.allNuclidesInProblem))
         for block in self.getCandidateBlocks():

armi/reactor/__init__.py

@@ -16,36 +16,6 @@
 The reactor package houses the data model used in ARMI to represent the reactor during its
 simulation. It contains definitions of the reactor, assemblies, blocks, components, etc.
 
-The key classes of the reactor package are shown below:
-
-.. _reactor-class-diagram:
-
-.. pyreverse:: armi.reactor -A -k --ignore=
-               assemblyParameters.py,
-               basicShapes.py,
-               blockParameters.py,
-               blueprints,
-               complexShapes.py,
-               componentParameters.py,
-               converters,
-               excoreStructure.py,
-               flags.py,
-               geometry.py,
-               grids.py,
-               parameters,
-               plugins.py,
-               reactorParameters.py,
-               shapes.py,
-               spentFuelPool.py,
-               tests,
-               volumetricShapes.py,
-               zones.py
-    :align: center
-    :alt: Reactor class diagram
-    :width: 90%
-
-    Class inheritance diagram for :py:mod:`armi.reactor`.
-
 See :doc:`/developer/index`.
 """
 

armi/runLog.py

@@ -572,7 +572,7 @@ def __init__(self, *args, **kwargs):
         handler.setFormatter(form)
         self.addHandler(handler)
 
-    def log(self, msgType, msg, single=False, label=None, **kwargs):
+    def log(self, msgType, msg, single=False, label=None, *args, **kwargs):
         """
         This is a wrapper around logger.log() that does most of the work.
 

doc/conf.py

@@ -24,6 +24,7 @@
 All configuration values have a default; values that are commented out
 serve to show the default.
 """
+
 # ruff: noqa: E402
 import datetime
 import inspect
@@ -35,7 +36,7 @@
 import sys
 import warnings
 
-import sphinx_rtd_theme
+import sphinx_rtd_theme  # noqa: F401
 from docutils import nodes, statemachine
 from docutils.parsers.rst import Directive, directives
 from sphinx.domains.python import PythonDomain
@@ -96,17 +97,15 @@ class ExecDirective(Directive):
 
     def run(self):
         try:
-            code = inspect.cleandoc(
-                """
-            def usermethod():
-                {}
-            """
-            ).format("\n    ".join(self.content))
-            exec(code)
-            result = locals()["usermethod"]()
+            # clean the content, then put back into a list
+            cleancode = inspect.cleandoc("\n".join(self.content)).split("\n")
+            code = "def usermethod():\n    " + "\n    ".join(cleancode)
+            globals = {}
+            exec(code, globals)
 
-            if result is None:
+            result = globals["usermethod"]()
 
+            if result is None:
                 raise self.error(
                     "Return value needed! The body of your `.. exec::` is used as a "
                     "function call that must return a value."
@@ -119,9 +118,7 @@ def usermethod():
         except Exception as e:
             docname = self.state.document.settings.env.docname
             raise self.error(
-                "Unable to execute embedded doc code at {}:{} ... {}\n{}".format(
-                    docname, self.lineno, datetime.datetime.now(), str(e)
-                )
+                f"Unable to execute embedded doc code at {docname}:{self.lineno}\n{str(e)}"
             )
 
 
@@ -363,6 +360,11 @@ def setup(app):
 exclude_patterns = [
     "**/Python27*",
     "**/ccl*",
+    # prevent sphinx-gallery from causing duplicate source file errors
+    "gallery/**/*.ipynb",
+    "gallery/**/*.md5",
+    "gallery/**/*.zip",
+    "gallery/**/*.json",
     "**.ipynb_checkpoints",
     "_build",
 ]  # , '**/tests*']
@@ -410,9 +412,6 @@ def setup(app):
     "titles_only": False,
 }
 
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
 # as long as this file @import's the theme's main css it won't break anything
 html_style = "css/theme_fixes.css"
 

doc/gallery-src/framework/run_chartOfNuclides.py

@@ -22,7 +22,9 @@
 
     Our :ref:`extended tutorial for nuclides </tutorials/nuclide_demo.ipynb>` and
     detailed :py:mod:`nucDirectory docs <armi.nucDirectory>` may also be of interest.
+
 """
+
 import matplotlib.pyplot as plt
 
 from armi import configure

doc/gallery-src/framework/run_computeReactionRates.py

@@ -28,7 +28,7 @@
 from armi import configure, nuclideBases, settings
 from armi.materials import ht9, sodium, uZr
 from armi.nuclearDataIO.cccc import isotxs
-from armi.reactor import assemblies, blocks, blueprints, geometry, grids, reactors
+from armi.reactor import assemblies, blocks, geometry, grids, reactors
 from armi.reactor.components import Circle, DerivedShape, Hexagon
 from armi.reactor.flags import Flags
 from armi.tests import ISOAA_PATH
@@ -56,7 +56,9 @@ def createDummyReactor():
     Often, a reactor model like this is built directly from input files rather
     than from code as done here.
     """
-    bp = blueprints.Blueprints()
+    from armi.reactor.blueprints import Blueprints
+
+    bp = Blueprints()
     cs = settings.Settings()
 
     r = reactors.Reactor("Reactor", bp)

doc/gallery-src/framework/run_fuelManagement.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 """
 Fuel management in a LWR.
+=========================
 
 Demo of locating and swapping assemblies in a core with Cartesian geometry. Given a burnup
 distribution, this swaps high burnup assemblies with low ones.
@@ -26,6 +27,7 @@
 ARMI to do fuel management. Thus, this example applies a dummy burnup distribution for
 demonstration purposes.
 """
+
 # Tell the gallery to feature the 2nd image
 # sphinx_gallery_thumbnail_number = 2
 import math

doc/release/0.5.rst

@@ -29,6 +29,7 @@ Bug Fixes
 Quality Work
 ------------
 #. Adding PDF versions of the ARMI docs. (`PR#2072 <https://github.com/terrapower/armi/pull/2072>`_)
+#. Update docs build to occur with python 3.13 and updated docs dependencies. (`PR#2050 <https://github.com/terrapower/armi/pull/2050>`_)
 #. TBD
 
 

pyproject.toml

@@ -92,31 +92,27 @@ test = [
 docs = [
 #######################################################################
 # These are most specified that usual, because Sphinx docs seem to be
-# quite fragile limited <7 by sphinx-rtd-theme at the moment.
+# quite fragile.
 #
-# sphinx-rtd-theme requires docutils <0.19 but sphinx dropped support
-# for 0.18 in 6.0.0 so we're stuck at these versions.
-#
-# We are only building our docs with Python 3.9.
+# We are only building our docs with Python 3.13.
 #######################################################################
-    "Sphinx==5.3.0", # central library used to build our docs
-    "docutils==0.18.1", # Needed by sphinx-rtd-them
-    "sphinx-rtd-theme==1.2.2", # Read-The-Docs theme for Sphinx
-    "nbsphinx==0.9.2", # Parses Jupyter notebooks
-    "nbsphinx-link==1.3.0", # Adds Jupyter NBs to Sphinx source root
-    "sphinx-gallery==0.13.0", # Builds an HTML version of a Python script and puts it into a gallery
-    "sphinxcontrib-apidoc==0.3.0", # More easily document our API
-    "sphinxext-opengraph==0.8.2", # Generates OpenGraph metadata to make good-looking cards on social media
-    "sphinx-needs==1.2.2", # Requirements traceability matrices for QA
-    "sphinxcontrib-plantuml==0.25", # UML support in sphinx-needs
+    "Sphinx==8.1.3", # central library used to build our docs
+    "docutils==0.21.2", # Needed by sphinx-rtd-them
+    "sphinx-rtd-theme==3.0.2", # Read-The-Docs theme for Sphinx
+    "nbsphinx", # Parses Jupyter notebooks
+    "nbsphinx-link", # Adds Jupyter NBs to Sphinx source root
+    "sphinx-gallery", # Builds an HTML version of a Python script and puts it into a gallery
+    "sphinxcontrib-apidoc==0.5.0", # More easily document our API
+    "sphinxext-opengraph", # Generates OpenGraph metadata to make good-looking cards on social media
+    "sphinx-needs==4.1.0", # Requirements traceability matrices for QA
+    "sphinxcontrib-plantuml==0.30", # UML support in sphinx-needs
     "pandoc", # Must be in the path (to convert file formats)
-    "ipykernel==6.25.1", # iPython kernel to run Jupyter notebooks
-    "pylint==2.17.5", # Generates UML diagrams
-    "Jinja2==3.0.3", # Used in numpydoc and nbconvert
+    "ipykernel", # iPython kernel to run Jupyter notebooks
+    "pylint", # Generates UML diagrams
+    "Jinja2", # Used in numpydoc and nbconvert
     "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
+    "setuptools",  # needed for conf.py tooling
 ]
 
 [project.scripts]