Reducing the number of warnings when building docs (terrapower#1769)

armi/bookkeeping/tests/test_historyTracker.py

@@ -101,11 +101,11 @@ def tearDown(self):
         self.td.__exit__(None, None, None)
 
     def test_calcMGFluence(self):
-        """
+        r"""
         This test confirms that mg flux has many groups when loaded with the history tracker.
 
         armi.bookeeping.db.hdf.hdfDB.readBlocksHistory requires
-        historical_values[historical_indices] to be cast as a list to read more than the
+        historical_values\[historical_indices\] to be cast as a list to read more than the
         first energy group. This test shows that this behavior is preserved.
 
         .. test:: Demonstrate that a parameter stored at differing time nodes can be recovered.
@@ -202,9 +202,10 @@ def test_historyReport(self):
         """
         Test generation of history report.
 
-        This does a swap for 5 timesteps:
-        |       TS  0     1      2       3       4
-        |LOC      (1,1) (2,1)  (3,1)   (4,1)   SFP
+        This does a swap for 5 timesteps::
+
+            |       TS  0     1      2       3       4
+            |LOC      (1,1) (2,1)  (3,1)   (4,1)   SFP
         """
         history = self.o.getInterface("history")
         history.interactBOL()

armi/materials/__init__.py

@@ -171,7 +171,7 @@ def resolveMaterialClassByName(name: str, namespaceOrder: List[str] = None):
 
     Returns
     -------
-    matCls : Material
+    matCls : armi.materials.material.Material
         The material
 
     Raises

armi/materials/material.py

@@ -33,7 +33,7 @@
 
 
 class Material:
-    """
+    r"""
     A material is made up of elements or isotopes. It has bulk properties like density.
 
     .. impl:: The abstract material class.
@@ -62,7 +62,7 @@ class Material:
     massFrac : dict
         Mass fractions for all nuclides in the material keyed on the nuclide symbols
     refDens : float
-        A reference density used by some materials, for instance `SimpleSolid`s, during thermal
+        A reference density used by some materials, for instance `SimpleSolid`\ s, during thermal
         expansion
     theoreticalDensityFrac : float
         Fraction of the material's density in reality, which is commonly different from 1.0 in solid

armi/nucDirectory/elements.py

@@ -71,7 +71,7 @@
 
 
 Retrieve elements that are classified as actinides:
- 
+
  >>> elements.getElementsByChemicalGroup(elements.ChemicalGroup.ACTINIDE)
     [<Element  AC (Z=89), Actinium, ChemicalGroup.ACTINIDE, ChemicalPhase.SOLID>,
      <Element  TH (Z=90), Thorium, ChemicalGroup.ACTINIDE, ChemicalPhase.SOLID>,
@@ -125,7 +125,8 @@ def getAttributes(element):
         return createTable(tabulate(tabular_data=[getAttributes(elem) for elem in sortedElements],
                                     headers=attributes,
                                     tablefmt='rst'),
-                           caption='List of elements')
+                           caption='List of elements',
+                           label='nuclide-bases-table')
 """
 
 import os

armi/nuclearDataIO/cccc/__init__.py

@@ -58,7 +58,7 @@
 
 .. [CCCC-IV] R. Douglas O'Dell, "Standard Interface Files and Procedures for Reactor Physics
              Codes, Version IV," LA-6941-MS, Los Alamos National Laboratory (September 1977).
-             Web. doi:10.2172/5369298. (`OSTI <https://www.osti.gov/biblio/5369298>`_)
+             Web. doi:10.2172/5369298. (`OSTI <https://www.osti.gov/biblio/5369298>`__)
 
 Using the system
 ----------------

armi/nuclearDataIO/cccc/gamiso.py

@@ -33,7 +33,7 @@
 
 .. [GAMSOR] Smith, M. A., Lee, C. H., and Hill, R. N. GAMSOR: Gamma Source Preparation and DIF3D
             Flux Solution. United States: N. p., 2016. Web. doi:10.2172/1343095. `On OSTI
-            <https://www.osti.gov/biblio/1343095-gamsor-gamma-source-preparation-dif3d-flux-solution>`_
+            <https://www.osti.gov/biblio/1343095-gamsor-gamma-source-preparation-dif3d-flux-solution>`__
 """
 
 from armi import runLog

armi/nuclearDataIO/cccc/pmatrx.py

@@ -20,7 +20,7 @@
 .. [MC23] Lee, Changho, Jung, Yeon Sang, and Yang, Won Sik. MC2-3: Multigroup Cross Section
           Generation Code for Fast Reactor Analysis Nuclear. United States: N. p., 2018. Web.
           doi:10.2172/1483949. (`OSTI
-          <https://www.osti.gov/biblio/1483949-mc2-multigroup-cross-section-generation-code-fast-reactor-analysis-nuclear>`_)
+          <https://www.osti.gov/biblio/1483949-mc2-multigroup-cross-section-generation-code-fast-reactor-analysis-nuclear>`__)
 """
 
 import traceback

armi/physics/neutronics/latticePhysics/latticePhysicsInterface.py

@@ -118,7 +118,7 @@ def interactBOC(self, cycle=0):
         Notes
         -----
         :py:meth:`armi.physics.fuelCycle.fuelHandlerInterface.FuelHandlerInterface.interactBOC`
-        also calls this if the ``runLatticePhysicsBeforeShuffling``setting is True.
+        also calls this if the ``runLatticePhysicsBeforeShuffling`` setting is True.
         This happens because branch searches may need XS.
         """
         if self._latticePhysicsFrequency == LatticePhysicsFrequency.BOC:

armi/plugins.py

@@ -49,8 +49,7 @@
 - :py:mod:`armi.settings` and their validators
 - :py:mod:`armi.reactor.components` for custom geometry
 - :py:mod:`armi.reactor.flags` for custom reactor components
-- :py:mod:`armi.interfaces` to define new calculation sequences and interactions with
-  new codes
+- :py:mod:`armi.interfaces` to define new calculation sequences and interactions with new codes
 - :py:mod:`armi.reactor.parameters` to represent new physical state on the reactor
 - :py:mod:`armi.materials` for custom materials
 - Elements of the :py:mod:`armi.gui`
@@ -89,34 +88,35 @@
 deliberate design choice to keep the plugin system simple and to preclude a large class
 of potential bugs. At some point it may make sense to revisit this.
 
-Other customization points
---------------------------
+**Other customization points**
+
 While the Plugin API is the main place for ARMI framework customization, there are
 several other areas where ARMI may be extended or customized. These typically pre-dated
 the Plugin-based architecture, and as the need arise may be migrated to here.
 
- - Component types: Component types are registered dynamically through some metaclass
-   magic, found in :py:class:`armi.reactor.components.component.ComponentType` and
-   :py:class:`armi.reactor.composites.CompositeModelType`. Simply defining a new
-   Component subclass should register it with the appropriate ARMI systems. While this
-   is convenient, it does lead to potential issues, as the behavior of ARMI becomes
-   sensitive to module import order and the like; the containing module needs to be
-   imported before the registration occurs, which can be surprising.
-
- - Interface input files: Interfaces used to be discovered dynamically, rather than
-   explicitly as they are now in the :py:meth:`armi.plugins.ArmiPlugin.exposeInterfaces`
-   plugin hook. Essentially they functioned as ersatz plugins. One of the ways that they
-   would customize ARMI behavior is through the
-   :py:meth:`armi.physics.interface.Interface.specifyInputs` static method, which is
-   still used to determine inter-Case dependencies and support cloning and hashing Case
-   inputs. Going forward, this approach will likely be deprecated in favor of a plugin
-   hook.
-
- - Fuel handler logic: The
-   :py:class:`armi.physics.fuelCycle.fuelHandlers.FuelHandlerInterface` supports
-   customization through the dynamic loading of fuel handler logic modules, based on
-   user settings. This also predated the plugin infrastructure, and may one day be
-   replaced with plugin-based fuel handler logic.
+    - Component types: Component types are registered dynamically through some metaclass
+      magic, found in :py:class:`armi.reactor.components.component.ComponentType` and
+      :py:class:`armi.reactor.composites.CompositeModelType`. Simply defining a new
+      Component subclass should register it with the appropriate ARMI systems. While this
+      is convenient, it does lead to potential issues, as the behavior of ARMI becomes
+      sensitive to module import order and the like; the containing module needs to be
+      imported before the registration occurs, which can be surprising.
+
+    - Interface input files: Interfaces used to be discovered dynamically, rather than
+      explicitly as they are now in the :py:meth:`armi.plugins.ArmiPlugin.exposeInterfaces`
+      plugin hook. Essentially they functioned as ersatz plugins. One of the ways that they
+      would customize ARMI behavior is through the
+      :py:meth:`armi.physics.interface.Interface.specifyInputs` static method, which is
+      still used to determine inter-Case dependencies and support cloning and hashing Case
+      inputs. Going forward, this approach will likely be deprecated in favor of a plugin
+      hook.
+
+    - Fuel handler logic: The
+      :py:class:`armi.physics.fuelCycle.fuelHandlers.FuelHandlerInterface` supports
+      customization through the dynamic loading of fuel handler logic modules, based on
+      user settings. This also predated the plugin infrastructure, and may one day be
+      replaced with plugin-based fuel handler logic.
+
 """
 from typing import Callable, Dict, List, Union, TYPE_CHECKING
 
@@ -309,10 +309,12 @@ def defineBlockTypes() -> List:
         corresponding ``Component`` type that should activate it. For instance a
         ``HexBlock`` would be created when the largest component is a ``Hexagon``::
 
+            [(Hexagon, HexBlock)]
+
         Returns
         -------
         list
-            [(Hexagon, HexBlock)]
+            ``[(compType, BlockType), ...]``
         """
 
     @staticmethod
@@ -337,11 +339,13 @@ def defineAssemblyTypes() -> List:
 
         Example
         -------
-        [
-            (HexBlock, HexAssembly),
-            (CartesianBlock, CartesianAssembly),
-            (ThRZBlock, ThRZAssembly),
-        ]
+        .. code::
+
+            [
+                (HexBlock, HexAssembly),
+                (CartesianBlock, CartesianAssembly),
+                (ThRZBlock, ThRZAssembly),
+            ]
 
         Returns
         -------
@@ -363,16 +367,16 @@ def defineBlueprintsSections() -> List:
         list
             (name, section, resolutionMethod) tuples, where:
 
-             - name : The name of the attribute to add to the Blueprints class; this
-               should be a valid Python identifier.
+            - name : The name of the attribute to add to the Blueprints class; this
+              should be a valid Python identifier.
 
-             - section : An instance of ``yaml.Attribute`` defining the data that is
-               described by the Blueprints section.
+            - section : An instance of ``yaml.Attribute`` defining the data that is
+              described by the Blueprints section.
 
-             - resolutionMethod : A callable that takes a Blueprints object and case
-               settings as arguments. This will be called like an unbound instance
-               method on the passed Blueprints object to initialize the state of the new
-               Blueprints section.
+            - resolutionMethod : A callable that takes a Blueprints object and case
+              settings as arguments. This will be called like an unbound instance
+              method on the passed Blueprints object to initialize the state of the new
+              Blueprints section.
 
         Notes
         -----
@@ -807,7 +811,7 @@ class PluginError(RuntimeError):
     These should always come from some form of programmer error, and indicates
     conditions such as:
 
-     - A plugin improperly implementing a hook, when possible to detect.
-     - A collision between components provided by plugins (e.g. two plugins providing
-       the same Blueprints section)
+    - A plugin improperly implementing a hook, when possible to detect.
+    - A collision between components provided by plugins (e.g. two plugins providing
+      the same Blueprints section)
     """

armi/reactor/blocks.py

@@ -1065,9 +1065,11 @@ def getNumPins(self):
         nPins = [
             sum(
                 [
-                    int(c.getDimension("mult"))
-                    if isinstance(c, basicShapes.Circle)
-                    else 0
+                    (
+                        int(c.getDimension("mult"))
+                        if isinstance(c, basicShapes.Circle)
+                        else 0
+                    )
                     for c in self.iterComponents(compType)
                 ]
             )
@@ -1233,6 +1235,7 @@ def getPitch(self, returnComp=False):
         ----------
         returnComp : bool, optional
             If true, will return the component that has the maximum pitch as well
+
         Returns
         -------
         pitch : float or None
@@ -1820,13 +1823,13 @@ def createHomogenizedCopy(self, pinSpatialLocators=False):
         by omitting this detailed data and only providing the necessary level of detail for
         the uniform mesh reactor: number densities on each block.
 
-        .. note: Individual components within a block can have different temperatures, and this
+        Individual components within a block can have different temperatures, and this
         can affect cross sections. This temperature variation is captured by the lattice physics
         module. As long as temperature distribution is correctly captured during cross section
         generation, it doesn't need to be transferred to the neutronics solver directly through
         this copy operation.
 
-        .. note: If you make a new block, you must add it to an assembly and a reactor.
+        If you make a new block, you must add it to an assembly and a reactor.
 
         Returns
         -------

armi/reactor/blueprints/isotopicOptions.py

@@ -387,7 +387,7 @@ def apply(self, material):
 
         Parameters
         ----------
-        material : Material
+        material : armi.materials.material.Material
             An ARMI Material instance.
         """
         material.massFrac = dict(self.massFracs)
@@ -424,7 +424,7 @@ def apply(self, material, customIsotopicsName):
 
         Parameters
         ----------
-        material : Material
+        material : armi.materials.material.Material
             Material instance to adjust.
 
         customIsotopicName : str

armi/reactor/composites.py

@@ -2255,7 +2255,7 @@ def getComponentsOfMaterial(self, material=None, materialName=None):
 
         Parameters
         ----------
-        material : Material object, optional
+        material : armi.materials.material.Material, optional
             The material to match
         materialName : str, optional
             The material name to match.
@@ -2453,7 +2453,7 @@ def getDominantMaterial(self, typeSpec: TypeSpec = None, exact=False):
 
         Returns
         -------
-        mat : Material
+        mat : armi.materials.material.Material
              the first instance of the most dominant material (by volume) in this object.
 
         See Also

armi/reactor/converters/axialExpansionChanger.py

@@ -255,10 +255,9 @@ def setAssembly(self, a, setFuel=True, expandFromTinputToThot=False):
         Notes
         -----
         When considering thermal expansion, if there is an axial temperature distribution on the
-        assembly, the axial expansion methodology will NOT perfectly preseve mass. The magnitude of
+        assembly, the axial expansion methodology will NOT perfectly preserve mass. The magnitude of
         the gradient of the temperature distribution is the primary factor in determining the
-        cumulative loss of mass conservation. Additional details will be documented in
-        :ref:`axialExpansion` of the documentation.
+        cumulative loss of mass conservation.
         """
         self.linked = AssemblyAxialLinkage(a)
         self.expansionData = ExpansionData(

armi/reactor/converters/uniformMesh.py

@@ -32,9 +32,9 @@
 
 
 .. warning::
-    This procedure can cause numerical diffusion in some cases. For example, 
+    This procedure can cause numerical diffusion in some cases. For example,
     if a control rod tip block has a large coolant block below it, things like peak
-    absorption rate can get lost into it. We recalculate some but not all 
+    absorption rate can get lost into it. We recalculate some but not all
     reaction rates in the re-mapping process based on a flux remapping. To avoid this,
     finer meshes will help. Always perform mesh sensitivity studies to ensure appropriate
     convergence for your needs.
@@ -369,15 +369,16 @@ class UniformMeshGeometryConverter(GeometryConverter):
     Notes
     -----
     There are several staticmethods available on this class that allow for:
+
         - Creation of a new reactor without applying a new uniform axial mesh. See:
-        `<UniformMeshGeometryConverter.initNewReactor>`
+          `<UniformMeshGeometryConverter.initNewReactor>`
         - Creation of a new assembly with a new axial mesh applied. See:
-        `<UniformMeshGeometryConverter.makeAssemWithUniformMesh>`
+          `<UniformMeshGeometryConverter.makeAssemWithUniformMesh>`
         - Resetting the parameter state of an assembly back to the defaults for the
-        provided block parameters. See:
-        `<UniformMeshGeometryConverter.clearStateOnAssemblies>`
+          provided block parameters. See:
+          `<UniformMeshGeometryConverter.clearStateOnAssemblies>`
         - Mapping number densities and block parameters between one assembly to
-        another. See: `<UniformMeshGeometryConverter.setAssemblyStateFromOverlaps>`
+          another. See: `<UniformMeshGeometryConverter.setAssemblyStateFromOverlaps>`
 
     This class is meant to be extended for specific physics calculations that require a
     uniform mesh. The child types of this class should define custom
@@ -390,9 +391,9 @@ class UniformMeshGeometryConverter(GeometryConverter):
     is being applied to prevent the numerical diffusion problem.
 
     - "in" is used when mapping parameters into the uniform assembly
-    from the non-uniform assembly.
+      from the non-uniform assembly.
     - "out" is used when mapping parameters from the uniform assembly back
-    to the non-uniform assembly.
+      to the non-uniform assembly.
 
     .. warning::
         If a parameter is calculated by a physics solver while the reactor is in its