docs: enable nitpicky mode and fix broken cross-references (#889)#916
Draft
novavale wants to merge 4 commits intoidaholab:developfrom
Draft
docs: enable nitpicky mode and fix broken cross-references (#889)#916novavale wants to merge 4 commits intoidaholab:developfrom
novavale wants to merge 4 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. |
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/