docs: enable nitpicky mode and fix broken cross-references (#889)#916
docs: enable nitpicky mode and fix broken cross-references (#889)#916MicahGale merged 29 commits intoidaholab:developfrom
Conversation
) 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
|
Update to use the PR template. |
|
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
left a comment
MicahGale
left a comment
There was a problem hiding this comment.
This currently overly relies on nitpick-ignore.
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)
…ick_ignore Library and LibraryType were undocumented in modules.rst, causing Sphinx to generate no inventory entries for montepy.Library / montepy.LibraryType. Add them to the Materials and Enumerations autosummary sections respectively so cross-refs in docstrings (e.g. :class:`~montepy.LibraryType`) resolve. Python type annotations in material.py / materials.py / nuclide.py get resolved by Sphinx to the canonical module paths (montepy.data_inputs.nuclide.Library, montepy.particle.LibraryType). Those paths remain unresolvable until all docstrings migrate to the public API paths; add narrow nitpick_ignore entries with explanatory comments rather than silently hiding them.
Per MicahGale's review feedback that the PR 'overly relies on nitpick-ignore', replace broad suppression patterns with actual docstring fixes. Changes: - Update 12 source files (.py + .rst) to use public API paths in cross-references: montepy.Cell instead of montepy.cell.Cell, montepy.Material instead of montepy.data_inputs.material.Material, montepy.MCNP_Problem instead of montepy.mcnp_problem.MCNP_Problem, etc. for all classes re-exported at the top-level montepy namespace. - Replace stale montepy.mcnp_card.MCNP_Card refs in developing.rst with the current montepy.mcnp_object.MCNP_Object. - Fix LatticeType.RECTANGULAR docstring so Sphinx no longer generates a phantom 'A rectangular prism is a type' py:class reference. - Fix typo in cell.py: :rytpe: -> :rtype: conf.py cleanup (5 entries removed): - Remove py:meth 'montepy.data_inputs.mode.Mode.set' (ref migrated) - Remove broad py:attr regex for internal cell/mcnp_problem/surfaces/ data_inputs paths (all attrs now use public API paths) - Remove broad py:func regex for internal cell/cells/mcnp_problem/ surfaces/data_inputs/materials/universe paths (all refs fixed) - Remove 'A rectangular prism is a type' regex (docstring fixed) - Remove 'hexahedron' from bare-name regex (no longer referenced)
|
Thanks for the continued feedback — I've addressed the What changed: Instead of suppressing whole categories of cross-reference warnings, I updated the source docstrings and RST files to use MontePy's public API paths (e.g. Removed from
Also fixed:
What remains in |
|
All montepy classes should be removed from the nitpick Ignore. |
Addresses MicahGale's review comment: 'All montepy classes should be
removed from the nitpick Ignore.'
Changes:
doc/source/developing.rst:
- montepy.errors.MalformedInputError → montepy.exceptions.MalformedInputError
- Private method cross-refs replaced with plain code style (backticks):
_generate_default_node, _convert_to_int, _convert_to_enum,
_format_tree, _check_redundant_definitions, PREFIX_MATCHES
- ListNode, IsotopesNode cross-refs replaced with plain code style
(IsotopesNode does not exist as a class; ListNode not in autodoc)
doc/source/starting.rst + migrations/migrate0_1.rst:
- Bare :class:`Nucleus` → :class:`~montepy.data_inputs.nuclide.Nucleus`
(full canonical path resolves without suppression)
montepy/__init__.py:
- Library.__module__ = 'montepy' and LibraryType.__module__ = 'montepy'
so autodoc uses the public re-export path, not the internal module path
montepy/input_parser/syntax_node.py:
- ClassifierNode docstring: montepy.data_input → montepy.data_inputs.data_input
doc/source/conf.py:
- Removed all 12 montepy.* entries from nitpick_ignore
- Removed 3 montepy.* regex entries from nitpick_ignore_regex
- Kept: sly.* (no inventory), py:mod subpackages, bare-name artifacts
|
Done — b0bb000 removes all What changed: developing.rst — replaced all private-method cross-ref markup with plain code backticks (
starting.rst / migrate0_1.rst — bare montepy/init.py — montepy/input_parser/syntax_node.py — ClassifierNode docstring: old conf.py — all 12 |
…attr for surface_constants, add Nucleus to autosummary
|
Pushed 3f8431c with additional cross-reference fixes surfaced during a stash-pop merge:
|
|
Good question — rather than adding autodoc coverage for the internal subpackages, I went the other direction: replaced all Pushed
No more suppressed |
- Export Nucleus and SingletonGroup from montepy.__init__, set __module__ = 'montepy' so autodoc uses public paths - Add montepy.UnitHalfSpace and montepy.SingletonGroup to autosummary in modules.rst so base-class cross-refs resolve - Fix TypeErrror → TypeError typo in Library docstring (nuclide.py) - Fix :attr: ref to use montepy.MCNP_Problem.cells (public path) instead of montepy.mcnp_problem.MCNP_Problem.cells (cell_modifier.py) - Fix ShortcutNode docstring: bare :class:`ListNode` → full :class:`~montepy.input_parser.syntax_node.ListNode` - Fix changelog.rst: montepy.data_inputs.Importance → montepy.data_inputs.importance.Importance - Fix dev_standards.rst: montepy.surfaces.surface.Surface.surface_constants → montepy.Surface.surface_constants - Fix starting.rst: montepy.surfaces.half_space.UnitHalfSpace.side → montepy.UnitHalfSpace.side; montepy.data_inputs.nuclide.Nucleus → montepy.Nucleus (two occurrences)
The linkcheck builder flagged 'api/modules.html' as a broken link in starting.rst (introduced in 18654ca when replacing :mod: cross-refs). Replace the raw HTML anchor with a proper Sphinx :doc: cross-reference.
|
CI is now fully green (16/16 jobs, including Cross-reference fixes (all
The final |
MicahGale
left a comment
MicahGale
left a comment
There was a problem hiding this comment.
This is improved, but still there is far too much hiding of errors, rather than correcting them.
As requested, rather than explicitly calling `automethod` in `developing.rst` for `_generate_default_node`, `_format_tree`, `_check_redundant_definitions`, `_convert_to_int`, and `_convert_to_enum`, these methods have been added to the `:private-members:` directive in `doc/source/_templates/myclass.rst` so autodoc indexes them automatically.
|
@MicahGale I see what you mean! I assume you were referring to the 4th bullet point (Private Methods), since you mentioned I've removed the explicit Everything should now be properly indexed by Autodoc via the template. |
MicahGale
left a comment
MicahGale
left a comment
There was a problem hiding this comment.
This is looking very good. Just an issue still with documenting the modules.
…nces - Convert subpackage .rst files to use autosummary for explicit sub-module inclusion, resolving the issue where Autodoc failed to index them under the package pages. - Correct py:class references for `montepy.Surfaces` to `montepy.surface_collection.Surfaces` since it is not exported in the base namespace. - Remove non-existent `_convert_to_int` and `_convert_to_enum` from `:private-members:` and correct their public names in `developing.rst`.
|
@MicahGale Got it! I've updated the I also fixed the references to |
|
@MicahGale I fixed the Sphinx |
|
@novavale it's still failing, but with a lot of these warnings: I think this is an issue of |
|
Under further review |
|
@novavale don't actually pin sphinx, just ignore the warnings. |
|
@MicahGale I pinned |
|
@novavale actually belay that last input. Pinning is the correct course of action. I will open an issue to handle migration to sphinx 9. |
novavale
left a comment
novavale
left a comment
There was a problem hiding this comment.
Ah, I missed that the autosummaries for submodules were removed in my previous commit. I've restored them in the latest commit!
|
Ah, I missed that the autosummaries for submodules were removed in my previous commit. I've restored them in the latest commit! The Sphinx warnings I mentioned earlier have now been suppressed in Sphinx 9 without pinning, by adding |
|
Are these failures possibly due to classes being listed in the documentation multiple times due to the added documentation for the modules? If so let's drop the modules |
…tions in Sphinx 9
2 participants
Pull Request Checklist for MontePy
Description
Enable Sphinx nitpicky mode and migrate all cross-references to public API paths, fixing the broken Sphinx cross-references tracked in issue #889.
Fixes #889
Summary of changes:
conf.py: enablenitpicky = True; addnitpick_ignore/nitpick_ignore_regexonly for genuinely unresolvable refs (sly., montepy.errors., private methods, autodoc-generated canonical paths)montepy.cell.Cell,montepy.data_inputs.material.Material, etc.) to public API paths (montepy.Cell,montepy.Material, etc.)montepy.mcnp_card.MCNP_Cardrefs →montepy.mcnp_object.MCNP_Objectindeveloping.rstLatticeType.RECTANGULARdocstring (was generating phantom class cross-ref):rytpe:→:rtype:incell.pyGeneral Checklist
blackversion 25 or 26.LLM Disclosure
Are you?
Were any large language models (LLM or "AI") used in to generate any of this code?
Documentation Checklist
First-Time Contributor Checklist
pyproject.tomlif you wish to do so.Additional Notes for Reviewers
Ensure that:
📚 Documentation preview 📚: https://montepy--916.org.readthedocs.build/en/916/