docs: enable nitpicky mode and fix broken cross-references (#889)

doc/source/api/modules.rst

@@ -101,6 +101,7 @@ Materials
    :template: myclass.rst
 
    montepy.Element
+   montepy.Library
    montepy.Material
    montepy.Nuclide
    montepy.ThermalScatteringLaw
@@ -174,6 +175,7 @@ Enumerations
    :template: myclass.rst
 
    montepy.geometry_operators.Operator
+   montepy.LibraryType
    montepy.particle.Particle
    montepy.SurfaceType
    montepy.input_parser.shortcuts.Shortcuts

doc/source/changelog.rst

@@ -12,6 +12,10 @@ MontePy Changelog
 
 * Fixed a bug where ``append_renumber`` raised a ``TypeError`` when called with an object whose ``number`` is ``None`` (e.g. an object created with no arguments) (:issue:`880`).
 
+**Documentation**
+
+* Enable Sphinx nitpicky mode and fix ~30 broken cross-references in the developer guide, user guide, and migration docs (:issue:`889`).
+
 **Feature Added**
 
 * Added ``extend_renumber`` to ``NumberedObjectCollection`` with related test cases (:issue:`881`).

doc/source/conf.py

@@ -82,6 +82,9 @@
 linkcheck_ignore = [
     "https://nucleardata.lanl.gov/.*",
     "https://www.osti.gov/.*",  # Ignore osti.gov URLs
+    # GitHub returns 429/502 for link-checkers hitting issue/PR links in CI;
+    # the :issue: and :pull: extlinks are validated by the PR workflow itself.
+    r"https://github\.com/idaholab/MontePy/(issues|pull)/.*",
 ]
 
 # -- External link configuration ---------------------------------------------
@@ -144,6 +147,45 @@
 
 suppress_warnings = ["epub.unknown_project_files"]
 
+# -- Intersphinx mapping -----------------------------------------------------
+# Allows cross-references to Python stdlib, NumPy, etc.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+# -- Nitpicky mode -----------------------------------------------------------
+# Treat broken cross-references as warnings (CI promotes them to errors via -W).
+nitpicky = True
+
+# Exact (type, target) pairs that cannot be resolved and should be ignored.
+nitpick_ignore = [
+    # sly has no intersphinx inventory; all sly.* cross-refs are unresolvable
+    ("py:class", "sly.Parser"),
+    ("py:class", "sly.Lexer"),
+    ("py:class", "sly.lex.Token"),
+    ("py:class", "sly.lex.Lexer"),
+    ("py:class", "sly.yacc.Parser"),
+    ("py:class", "sly.yacc.ParserMeta"),
+    ("py:class", "sly.yacc.YaccProduction"),
+]
+
+# Regex patterns for cross-reference targets that cannot be resolved.
+nitpick_ignore_regex = [
+    # Sphinx/autodoc generates bare type names that are not valid cross-ref targets
+    (r"py:class", r"^(self|self\._\w+|generator|unknown|function|Class|InitInput|MCNP_Input)$"),
+    # sly Token is not in any intersphinx inventory
+    (r"py:class", r"^Token$"),
+    # Bare unqualified names from :type: annotations in older docstrings;
+    # ClassifierNode is an internal parser class not re-exported publicly
+    (r"py:class", r"^(ClassifierNode|enum|class)$"),
+    # numpy alias "np" is not in the numpy intersphinx inventory
+    (r"py:class", r"^np\..*"),
+    # montepy.input_parser and montepy.data_inputs are subpackages referenced
+    # with :mod: in developing.rst; they are not indexed as modules by autodoc
+    (r"py:mod", r"^montepy\.(surfaces|data_inputs|input_parser|input_parser\..+)$"),
+]
+
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

doc/source/migrations/migrate0_1.rst

@@ -30,15 +30,15 @@ Deprecations
 The following properties and objects are currently deprecated 
 and were removed in MontePy 1.0.0.
 
-* :func:`~montepy.data_inputs.material.Material.material_components`. 
+* :attr:`~montepy.Material.material_components`. 
   This is the dictionary that caused this design problem. 
 
 * :class:`~montepy.data_inputs.material_component.MaterialComponent`:
   This was the class that stores information in the above dictionary. 
   It was largely excess object wrapping that made the material interface 
   overly complex.
 
-* :class:`~montepy.data_inputs.isotope.Isotope` was renamed to :class:`~montepy.data_inputs.nuclide.Nuclide`. 
+* :class:`~montepy.data_inputs.isotope.Isotope` was renamed to :class:`~montepy.Nuclide`. 
   This is to better align with MCNP documentation
   and to better reflect that the nuclear data for a nuclide can represent 
   isotopic, isomeric, or atomic data.
@@ -48,7 +48,7 @@ New Interface & Migration
 -------------------------
 
 For more details, see the new :ref:`mat_tutorial` tutorial in the getting started guide,
-as well as the example in the :class:`~montepy.data_inputs.material.Material` documentation.
+as well as the example in the :class:`~montepy.Material` documentation.
 
 .. note::
 
@@ -61,7 +61,7 @@ as well as the example in the :class:`~montepy.data_inputs.material.Material` do
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Material composition data has moved from ``Material.material_components`` to the
-:class:`~montepy.data_inputs.material.Material` itself.
+:class:`~montepy.Material` itself.
 ``Material`` is now a list-like iterable.
 It is a list of tuples which are ``(nuclide, fraction)`` pairs.
 
@@ -80,19 +80,19 @@ Searching Components
 ^^^^^^^^^^^^^^^^^^^^
 
 Finding a specific ``Nuclide`` in a ``Material`` is now much easier.
-First, there is a :func:`~montepy.data_inputs.material.Material.find` method that takes either a ``Nuclide`` string,
+First, there is a :func:`~montepy.Material.find` method that takes either a ``Nuclide`` string,
 or various over search criteria (e.g., ``element``),
 and creates a generator of all matching component tuples.
 
 If you want to check if a ``Material`` contains a specific ``Nuclide``
 you can simply test ``nuclide in material``.
-The :func:`~montepy.data_inputs.material.Material.contains` function will provide more options,
+The :func:`~montepy.Material.contains_all` function will provide more options,
 such as setting a minimum threshold and testing for multiple nuclides at once.
 
 Adding Nuclides
 ^^^^^^^^^^^^^^^
 
-Adding a new nuclide is easiest with the :func:`~montepy.data_inputs.material.Material.add_nuclide` function.
+Adding a new nuclide is easiest with the :func:`~montepy.Material.add_nuclide` function.
 
 Editing Nuclide Composition
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -101,8 +101,8 @@ Editing a material composition will be very similar to editing a ``list``.
 Existing components can be set to a nuclide component nuclide.
 Also existing components can be deleted with ``del``. 
 For just editing the fractions or nuclides the functions:
-:func:`~montepy.data_inputs.material.Material.nuclides`
-and :func:`~montepy.data_inputs.material.Material.values` provide the easiest interface.
+:attr:`~montepy.Material.nuclides`
+and :attr:`~montepy.Material.values` provide the easiest interface.
 
 
 ``Isotope`` Deprecation and Removal
@@ -111,12 +111,12 @@ and :func:`~montepy.data_inputs.material.Material.values` provide the easiest in
 The decision was made to remove the name :class:`montepy.data_inputs.isotope.Isotope`.
 This is because not all material components are an isotope,
 they may be an isomer, or event an element.
-Rather the MCNP generalized terminology of :class:`montepy.data_inputs.nuclide.Nuclide` was adopted.
+Rather the MCNP generalized terminology of :class:`montepy.Nuclide` was adopted.
 The idea of a specific nuclide, e.g., ``H-1`` was separated from an
 MCNP material component e.g., ``1001.80c``. 
 The actual ``Nuclide`` information was moved to a new class: :class:`~montepy.data_inputs.nuclide.Nucleus`
 that is immutable. 
-The :class:`~montepy.data_inputs.nuclide.Nuclide` wraps this and adds a :class:`~montepy.data_inputs.nuclide.Library` object to specify the nuclear data that is used.
+The :class:`~montepy.Nuclide` wraps this and adds a :class:`~montepy.Library` object to specify the nuclear data that is used.
 It makes sense to be able to change a library.
 It does not make sense to change the intrinsic properties of a nuclide (i.e., ``Z``, ``A``, etc.).