docs: fix sphinx build warnings and broken cross-references#7526
docs: fix sphinx build warnings and broken cross-references#7526neteler wants to merge 9 commits into
Conversation
Fix Sphinx build warnings and broken cross-references `.rst` fixes (cross-references, toctree, unused labels): - `index.rst`: fixes broken relative links (`../python_intro.html`, `../jupyter_intro.html`); added `exceptions` and `temporal_framework` to the toctree (were producing document isn't included in any toctree warnings); removed duplicate toctree entries (`grass.tools`, `grass.jupyter`, `grass.exceptions`) that were already covered by the parent `grass` entry - `gunittest_testing.rst`: renamed duplicate label `GRASS sample data` to `GRASS sample data testing` to resolve sphinx `duplicate label` conflict with `gunittest_running_tests.rst`; removed unused `test-as-scripts` and `doctest` label definitions - `pygrass_gis.rst`: removed unused `GRASSdatabase-label` and `Region-label` definitions - `pygrass_raster.rst`: removed unused `raster-label` definition `conf.py` fixes (config errors, lexer docstrings, theme options): - fixed `today` type mismatch (`date` → `str` via `.strftime()`) - added `autodoc_mock_imports = ["grass.lib", "grass.lib.gis"]` to mock C extension modules during autodoc - added `skip_member` filter to skip PLY lexer `t_*` methods in `temporal_algebra` and `temporal_operator` (their regex docstrings are not intended for RST parsing, were causing `Unknown target name` errors). - added pickleable `html_context` proxy to replace `sphinx_material` theme class objects (`TableFix`, `DerenderToc`) which sphinx cannot cache (fixes `cannot cache unpickleable configuration value` warning). - removed unsupported logo option from `html_theme_options`. Template fix (duplicate object descriptions): - `package.rst.jinja`: Added `:no-index:` to automodule directives for subpackages and submodules in the auto-generated API docs template. The root `grass` package keeps full index entries; subpackages use `:no-index:` to avoid duplicating entries already generated by the parent.
| @@ -716,9 +714,8 @@ Further reading | |||
|
|
|||
|
|
|||
| .. _unittest: https://docs.python.org/2/library/unittest.html | |||
There was a problem hiding this comment.
Probably super outdated, but out of context.
| .. _Cppcheck: http://cppcheck.sourceforge.net/ | ||
| .. _sandbox: https://svn.osgeo.org/grass/sandbox/wenzeslaus/grass_py_static_check.py | ||
| .. _GRASS sample data: https://grass.osgeo.org/download/data/ and http://fatra.cnr.ncsu.edu/data/ (nc_spm_full_v2beta1) | ||
| .. _GRASS sample data: https://grass.osgeo.org/download/data/ and http://fatra.cnr.ncsu.edu/data/ (nc_spm_full_v2alpha2) |
There was a problem hiding this comment.
Is the v2 alpha 2 really the successor of v2 beta 1?
There was a problem hiding this comment.
I guess not but this is what is stored in the fatra server. Maybe something missing there, @wenzeslaus ?
There was a problem hiding this comment.
Found the nc_spm_full_v2beta1.tar.gz file on the server, updated in a0b135c
| grass | ||
| script_intro | ||
| pygrass_index | ||
| exceptions | ||
| imaging | ||
| pydispatch | ||
| temporal_framework | ||
| gunittest_testing |
There was a problem hiding this comment.
Is it intended to remove grass.tools ? It seems like a new api that could have been replaced if the ai tool based itself on old pages
And index is missing too, was it useful?
There was a problem hiding this comment.
I have restored grass.tools in 1357dd2, good point.
Re: index: keeping it leads to:
/home/mneteler/software/grass_main/python/grass/docs/src/index.rst:42: WARNING: toctree contains reference to nonexisting document 'index' [toc.not_readable]
| # When building docs, compiled GRASS extension modules (C libraries) may not | ||
| # be importable; mock them so autodoc can proceed using the pure-Python | ||
| # checkout sources. | ||
| autodoc_mock_imports = ["grass.lib", "grass.lib.gis"] |
There was a problem hiding this comment.
Ok, I'm curious to see what it'll generate. I'll probably want to do a diff of the generated artifacts before and after (this PR) to see what pages miss content.
There was a problem hiding this comment.
Here, the links are gone:
Here too ("Bases: CalledModuleError" isn't linked anymore)
| import string | ||
| from shutil import copy | ||
|
|
||
| from _pickleable import table_fix, derender_toc |
There was a problem hiding this comment.
Added to fix this one (I have added the original warnings above):
pickling environment... WARNING: cannot cache unpickleable configuration value: 'html_context' (because it contains a function, class, or module object) [config.cache]
|
I checked the diff of the artifact I refreshed yesterday, vs the one on main. See #7526 (comment). Some links to code are now gone. The navigation added at the bottom is nice. The TOC of individual pages has less items in it now, it doesn't matter that much. I didn't look at all the pages |
3 participants
I played around with the terminal based
OpenCodetool, a open source AI coding agent (https://opencode.ai/).To try something hopefully useful, I let it fix the broken crosslinks in the sphinx based docs, using DeepSeek Flash free.
Goal: let
make sphinxdoclibrun free of errors and warnings.A critical review is desired.
Original warnings and errors:
This PR collects the sphinx code changes:
.rstfixes (cross-references, toctree, unused labels):index.rst: fixes broken relative links (../python_intro.html,../jupyter_intro.html); addedexceptionsandtemporal_frameworkto the toctree (were producing document isn't included in any toctree warnings); removed duplicate toctree entries (grass.tools,grass.jupyter,grass.exceptions) that were already covered by the parentgrassentrygunittest_testing.rst: renamed duplicate labelGRASS sample datatoGRASS sample data testingto resolve sphinxduplicate labelconflict withgunittest_running_tests.rst; removed unusedtest-as-scriptsanddoctestlabel definitionspygrass_gis.rst: removed unusedGRASSdatabase-labelandRegion-labeldefinitionspygrass_raster.rst: removed unusedraster-labeldefinitionconf.pyfixes (config errors, lexer docstrings, theme options):todaytype mismatch (date→strvia.strftime())autodoc_mock_imports = ["grass.lib", "grass.lib.gis"]to mock C extension modules during autodocskip_memberfilter to skip PLY lexert_*methods intemporal_algebraandtemporal_operator(their regex docstrings are not intended for RST parsing, were causingUnknown target nameerrors).html_contextproxy to replacesphinx_materialtheme class objects (TableFix,DerenderToc) which sphinx cannot cache (fixescannot cache unpickleable configuration valuewarning).html_theme_options.Template fix (duplicate object descriptions):
package.rst.jinja: Added:no-index:to automodule directives for subpackages and submodules in the auto-generated API docs template. The rootgrasspackage keeps full index entries; subpackages use:no-index:to avoid duplicating entries already generated by the parent.If acceptable (as is or modified), I recommend to backport it to G85.