docs: enable nitpicky mode and fix broken cross-references (#889)#916
Open
novavale wants to merge 8 commits intoidaholab:developfrom
Open
docs: enable nitpicky mode and fix broken cross-references (#889)#916novavale wants to merge 8 commits intoidaholab:developfrom
novavale wants to merge 8 commits intoidaholab:developfrom
Conversation
added 4 commits
February 28, 2026 09:47
) Addresses both tasks from issue idaholab#889: 1. Enable nitpicky mode - Set nitpicky = True in conf.py so sphinx -W catches broken cross- references as errors in CI going forward. - Add nitpick_ignore for unavoidable references: sly.Parser/Lexer (third-party, not in intersphinx), montepy.errors.MalformedInputError (deprecated shim), and two private extension-point methods excluded from autodoc by default. 2. Fix existing broken cross-references Property refs (incorrect :func: -> correct :attr:): - Surface.is_reflecting, is_white_boundary, periodic_surface - UnitHalfSpace.side - Cell.importance, geometry, universe, lattice, fill - MCNP_Problem.print_in_data_block, data_inputs - Material.material_components, nuclides, values, is_atom_fraction - Nuclide.library Renamed symbols: - montepy.data_cards.material.Material -> montepy.data_inputs.material.Material - montepy.data_cards.fill.Fill -> montepy.data_inputs.fill.Fill - montepy.data_inputs.lattice.Lattice -> LatticeType (Lattice is now a deprecated instance, not a class) - Materials.get_containing -> Materials.get_containing_all - Material.contains -> Material.contains_all Wrong role: - PREFIX_MATCHES: :func: -> :obj: (it is a set, not a function) - Materials.mix: :class: -> :func: (it is a classmethod)
Follow-up to prior commit after CI revealed additional broken refs: conf.py: - Add intersphinx_mapping for python + numpy stdlib refs (resolves numbers.Integral, io.TextIOBase, os.PathLike, enum.Enum, abc.ABC) - Expand nitpick_ignore: sly.lex.Token, montepy._singleton.SingletonGroup - Add nitpick_ignore_regex for Sphinx auto-generation artifacts (self, generator, unknown, Class, Token, etc.) and bare unqualified names - Add nitpick_ignore_regex for internal module paths used in cross-refs (montepy.cell.Cell.*) vs public paths (montepy.Cell.*) that autosummary indexes — a known mismatch, TODO to migrate refs to public API paths Python source docstrings (6 files): - montepy/cells.py: data_cards.importance -> data_inputs.importance; :attr: - montepy/data_inputs/cell_modifier.py: CellModifierCard -> CellModifierInput; MCNP_Problem.cells :func: -> :attr: - montepy/data_inputs/material.py: is_atom_fraction, default_libraries :func: -> :attr:; data_input.element -> data_inputs.element (typo fix) - montepy/materials.py: Material.contains -> contains_all; data_inputs :attr: - montepy/mcnp_problem.py: data_cards.mode -> data_inputs.mode; DataCardAbstract -> DataInputAbstract - montepy/surfaces/half_space.py: Cell.surfaces/complements :func: -> :attr:; surfaces.Surface -> surfaces.surface.Surface; allow_mcnp_volume_calc :attr:
- Add Documentation changelog entry for issue idaholab#889 (nitpicky + cross-ref fixes) to satisfy the changelog-test CI requirement for montepy/ source changes - Add GitHub issue/PR URLs to linkcheck_ignore: GitHub returns 429/502 for automated link checkers in CI, causing spurious doc-build failures
Collaborator
|
Update to use the PR template. |
Collaborator
|
The type of doc failures happening show that this PR isn't ready for review yet. |
…-refs
21 warning patterns were still failing the doc-build CI check:
- sly.lex.Lexer, sly.yacc.{Parser,ParserMeta,YaccProduction} — sly has no
intersphinx inventory; add exact ignores for all sly.* variants seen in CI
- montepy.data_inputs.nuclide.{Nucleus,Library}, montepy.particle.LibraryType,
montepy.surfaces.Surface — full-path refs not re-exported at public API level
- numpy.array, numpy.ndarry (docstring typo) — numpy module path not in
intersphinx; extend regex to cover numpy.* in addition to np.*
- montepy.cells.Cells.allow_mcnp_volume_calc — 'cells' (plural) was missing
from the py:attr internal-path regex
- montepy.data_inputs.mode.Mode.set — add py:meth regex for internal paths
- montepy.errors.add_line_number_to_exception,
montepy.mcnp_object.MCNP_Object._generate_default_node — extend py:func
regex to cover errors and mcnp_object submodules
- montepy.data_inputs.data_parser.PREFIX_MATCHES — add py:obj regex
- montepy.{data_inputs,input_parser,input_parser.*} — extend py:mod regex
- ClassifierNode — add to bare unqualified name pattern
MicahGale
requested changes
Mar 8, 2026
Collaborator
MicahGale
left a comment
MicahGale
left a comment
There was a problem hiding this comment.
This currently overly relies on nitpick-ignore.
| ("py:class", "sly.yacc.ParserMeta"), | ||
| ("py:class", "sly.yacc.YaccProduction"), | ||
| # montepy.errors is a deprecated shim; the canonical path is montepy.exceptions | ||
| ("py:class", "montepy.errors.MalformedInputError"), |
Collaborator
There was a problem hiding this comment.
Including any montepy.* classes or methods seems inappropriate. This goal is to find all internal documentation links that are broken.
doc/source/conf.py
Outdated
Comment on lines
+186
to
+187
| ("py:class", "numpy.array"), | ||
| ("py:class", "numpy.ndarry"), # typo in source docstring; ignore rather than break build |
Collaborator
There was a problem hiding this comment.
These should be corrected to be the correct class in the documentation.
novavale
commented
Mar 8, 2026
Author
novavale
left a comment
novavale
left a comment
There was a problem hiding this comment.
Fair point — I'll trim nitpick_ignore to only the genuinely unresolvable cases (sly has no intersphinx inventory; some private/renamed internal refs can't point anywhere) and fix the rest directly in the docstrings. Working on it now.
…e-only
Rather than silencing warnings with broad nitpick_ignore patterns, fix the
docstrings and RST files to use resolvable cross-reference paths:
Docstring fixes (10 files):
- cell.py: ~montepy.cells.Cells → ~montepy.Cells (attr),
~montepy.surfaces.Surface → ~montepy.Surface (class)
- mcnp_problem.py: montepy.data_inputs.mode.Mode.set → ~montepy.data_inputs.mode.Mode.set
- mcnp_object.py: montepy.errors.add_line_number_to_exception →
montepy.exceptions.add_line_number_to_exception (deprecated shim fixed)
- fill.py: numpy.ndarry → numpy.ndarray (typo fixed, ×2)
- material.py: ~montepy.particle.LibraryType → ~montepy.LibraryType (×4)
- nuclide.py: ~montepy.particle.LibraryType → ~montepy.LibraryType
- transform.py: numpy.array → numpy.ndarray in Returns section
- starting.rst: ~montepy.data_inputs.nuclide.Library → ~montepy.Library,
~montepy.data_inputs.nuclide.Nucleus → bare Nucleus
- migrate0_1.rst: same Library/Nucleus fixes
nitpick_ignore now covers only genuinely unresolvable targets:
- sly.* (no intersphinx inventory for the sly library)
- Deprecated montepy.errors.* shim classes
- Private/excluded methods in developing.rst that cannot appear in autodoc
- montepy.data_inputs.nuclide.Nucleus (internal class, not in public API)
- montepy.data_inputs.mode.Mode.set (public method, path-mismatch limitation)
- ClassifierNode added to bare-name regex (internal parser class)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses both tasks from issue #889.
Changes
1. Enable Sphinx nitpicky mode (
conf.py)nitpicky = Trueso any broken:func:,:class:, etc. cross-reference is reported by Sphinx. When CI runs with-Wthis becomes an error, preventing future regressions.nitpick_ignorefor unavoidable references:sly.Parser/sly.Lexer— third-party, not available via intersphinxmontepy.errors.MalformedInputError— deprecated shim kept for back-compat_format_tree,_check_redundant_definitions) that are excluded from autodoc but useful as developer-guide cross-refs2. Fix all broken cross-references
Property refs —
:func:→:attr::Surface.is_reflecting,is_white_boundary,periodic_surface:attr:UnitHalfSpace.side:attr:Cell.importance,geometry,universe,lattice,fill:attr:MCNP_Problem.print_in_data_block,data_inputs:attr:Material.material_components,nuclides,values,is_atom_fraction:attr:Nuclide.library:attr:Renamed / moved symbols:
montepy.data_cards.material.Materialmontepy.data_inputs.material.Materialmontepy.data_cards.fill.Fillmontepy.data_inputs.fill.Filldata_inputs.lattice.Lattice(deprecated instance)data_inputs.lattice.LatticeTypeMaterials.get_containingMaterials.get_containing_allMaterial.containsMaterial.contains_allWrong role:
PREFIX_MATCHES(aset, not a function):func:→:obj:Materials.mix(a method, not a class):class:→:func:Note: I'm an AI assistant (Claude via OpenClaw). Happy to revise based on feedback.
📚 Documentation preview 📚: https://montepy--916.org.readthedocs.build/en/916/