From f1557a0b3630edda51f690066782e0bd272187c0 Mon Sep 17 00:00:00 2001 From: Arrielle Opotowsky Date: Thu, 6 Feb 2025 12:55:19 -0600 Subject: [PATCH] Update doc build to py313 (#2050) --- .github/workflows/docs.yaml | 2 +- .../neutronics/crossSectionGroupManager.py | 3 +- armi/reactor/__init__.py | 30 ---------------- armi/runLog.py | 2 +- doc/conf.py | 31 ++++++++-------- .../framework/run_chartOfNuclides.py | 2 ++ .../framework/run_computeReactionRates.py | 6 ++-- .../framework/run_fuelManagement.py | 2 ++ doc/release/0.5.rst | 1 + pyproject.toml | 36 +++++++++---------- 10 files changed, 44 insertions(+), 71 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 5ee163089a..4080a44e22 100644 --- a/.github/workflows/docs.yaml +++ b/.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 diff --git a/armi/physics/neutronics/crossSectionGroupManager.py b/armi/physics/neutronics/crossSectionGroupManager.py index 1eca9a3820..f049890bb8 100644 --- a/armi/physics/neutronics/crossSectionGroupManager.py +++ b/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(): diff --git a/armi/reactor/__init__.py b/armi/reactor/__init__.py index 3536b698c9..85bddbb215 100644 --- a/armi/reactor/__init__.py +++ b/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`. """ diff --git a/armi/runLog.py b/armi/runLog.py index 484672dfd4..b7393bd66e 100644 --- a/armi/runLog.py +++ b/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. diff --git a/doc/conf.py b/doc/conf.py index e83bc4c8bd..e40b036774 100644 --- a/doc/conf.py +++ b/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" diff --git a/doc/gallery-src/framework/run_chartOfNuclides.py b/doc/gallery-src/framework/run_chartOfNuclides.py index f0818d7e48..5a4516ffcf 100644 --- a/doc/gallery-src/framework/run_chartOfNuclides.py +++ b/doc/gallery-src/framework/run_chartOfNuclides.py @@ -22,7 +22,9 @@ Our :ref:`extended tutorial for nuclides ` and detailed :py:mod:`nucDirectory docs ` may also be of interest. + """ + import matplotlib.pyplot as plt from armi import configure diff --git a/doc/gallery-src/framework/run_computeReactionRates.py b/doc/gallery-src/framework/run_computeReactionRates.py index 1a7c2d52ba..2c2578e2ea 100644 --- a/doc/gallery-src/framework/run_computeReactionRates.py +++ b/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) diff --git a/doc/gallery-src/framework/run_fuelManagement.py b/doc/gallery-src/framework/run_fuelManagement.py index a55adcab23..7512f8c17c 100644 --- a/doc/gallery-src/framework/run_fuelManagement.py +++ b/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 diff --git a/doc/release/0.5.rst b/doc/release/0.5.rst index 11a818762e..1dc228f6ab 100644 --- a/doc/release/0.5.rst +++ b/doc/release/0.5.rst @@ -29,6 +29,7 @@ Bug Fixes Quality Work ------------ #. Adding PDF versions of the ARMI docs. (`PR#2072 `_) +#. Update docs build to occur with python 3.13 and updated docs dependencies. (`PR#2050 `_) #. TBD diff --git a/pyproject.toml b/pyproject.toml index 033b68a7fe..cd188f8f73 100644 --- a/pyproject.toml +++ b/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]