docs: fix sphinx build warnings and broken cross-references by neteler · Pull Request #7526 · OSGeo/grass

neteler · 2026-06-08T21:12:22Z

I played around with the terminal based OpenCode tool, 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 sphinxdoclib run free of errors and warnings.
A critical review is desired.

Original warnings and errors:

make sphinxdoclib
[...]
Running Sphinx v9.1.0
loading translations [en]... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
WARNING: The config value `today' has type `date'; expected `str'.
[...]
<unknown>:1: WARNING: duplicate object description of grass.pygrass.modules.interface.module.Module, other instance in grass.pygrass.modules, use :no-index: for one of them
<unknown>:1: WARNING: duplicate object description of grass.pygrass.modules.interface.module.MultiModule, other instance in grass.pygrass.modules, use :no-index: for one of them
<unknown>:1: WARNING: duplicate object description of grass.pygrass.modules.interface.module.ParallelModuleQueue, other instance in grass.pygrass.modules, use :no-index: for one of them
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_algebra.py:docstring of grass.temporal.temporal_algebra.TemporalAlgebraLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_operator.py:docstring of grass.temporal.temporal_operator.TemporalOperatorLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_algebra.py:docstring of grass.temporal.temporal_algebra.TemporalAlgebraLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_operator.py:docstring of grass.temporal.temporal_operator.TemporalOperatorLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/python/grass/docs/src/index.rst:42: WARNING: toctree contains reference to nonexisting document 'index' [toc.not_readable]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_algebra.py:docstring of temporal.temporal_algebra.TemporalAlgebraLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_operator.py:docstring of temporal.temporal_operator.TemporalOperatorLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_algebra.py:docstring of temporal.temporal_algebra.TemporalAlgebraLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
/home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/etc/python/grass/temporal/temporal_operator.py:docstring of temporal.temporal_operator.TemporalOperatorLexer.t_NAME:1: ERROR: Unknown target name: "a-za-z". [docutils]
looking for now-outdated files... none found
pickling environment... WARNING: cannot cache unpickleable configuration value: 'html_context' (because it contains a function, class, or module object) [config.cache]
done
checking consistency... /home/mneteler/software/grass_main/python/grass/docs/src/grass.rst: WARNING: document isn't included in any toctree [toc.not_included]
/home/mneteler/software/grass_main/python/grass/docs/src/temporal_framework.rst: WARNING: document isn't included in any toctree [toc.not_included]
/home/mneteler/software/grass_main/python/grass/docs/src/grass.jupyter.rst: document is referenced in multiple toctrees: ['grass', 'index'], selecting: index <- grass.jupyter
/home/mneteler/software/grass_main/python/grass/docs/src/grass.tools.rst: document is referenced in multiple toctrees: ['grass', 'index'], selecting: index <- grass.tools
done
preparing documents... WARNING: unsupported theme option 'logo' given
done
copying assets... 
copying downloadable files... [100%] Temporal-Framework-API-Description.pdf
copying static files... 
Writing evaluated template result to /home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/docs/html/libpython/_static/basic.css
Writing evaluated template result to /home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/docs/html/libpython/_static/documentation_options.js
Writing evaluated template result to /home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/docs/html/libpython/_static/language_data.js
Writing evaluated template result to /home/mneteler/software/grass_main/dist.x86_64-pc-linux-gnu/docs/html/libpython/_static/material.css
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [100%] temporal_framework
<unknown>:1: WARNING: more than one target found for cross-reference 'GrassTestFilesMultiReporter': grass.gunittest.reporters.GrassTestFilesMultiReporter, gunittest.reporters.GrassTestFilesMultiReporter [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/grass.pydispatch.rst:13: WARNING: more than one target found for cross-reference 'errors.DispatcherTypeError': grass.pydispatch.errors.DispatcherTypeError, pydispatch.errors.DispatcherTypeError [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/grass.pydispatch.rst:13: WARNING: more than one target found for cross-reference 'errors.DispatcherTypeError': grass.pydispatch.errors.DispatcherTypeError, pydispatch.errors.DispatcherTypeError [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/grass.pydispatch.rst:13: WARNING: more than one target found for cross-reference 'errors.DispatcherKeyError': grass.pydispatch.errors.DispatcherKeyError, pydispatch.errors.DispatcherKeyError [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'GrassTestFilesMultiReporter': grass.gunittest.reporters.GrassTestFilesMultiReporter, gunittest.reporters.GrassTestFilesMultiReporter [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/pydispatch.rst:8: WARNING: more than one target found for cross-reference 'errors.DispatcherTypeError': grass.pydispatch.errors.DispatcherTypeError, pydispatch.errors.DispatcherTypeError [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/pydispatch.rst:8: WARNING: more than one target found for cross-reference 'errors.DispatcherTypeError': grass.pydispatch.errors.DispatcherTypeError, pydispatch.errors.DispatcherTypeError [ref.python]
/home/mneteler/software/grass_main/python/grass/docs/src/pydispatch.rst:8: WARNING: more than one target found for cross-reference 'errors.DispatcherKeyError': grass.pydispatch.errors.DispatcherKeyError, pydispatch.errors.DispatcherKeyError [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
<unknown>:1: WARNING: more than one target found for cross-reference 'Table': grass.pygrass.vector.table.Table, pygrass.vector.table.Table [ref.python]
generating indices... genindex py-modindex done

This PR collects the sphinx code changes:

.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.

If acceptable (as is or modified), I recommend to backport it to G85.

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.

echoix · 2026-06-08T21:15:44Z

@@ -716,9 +714,8 @@ Further reading


 .. _unittest: https://docs.python.org/2/library/unittest.html


Probably super outdated, but out of context.

Any suggestion here?

echoix · 2026-06-08T21:16:42Z

 .. _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)


Is the v2 alpha 2 really the successor of v2 beta 1?

I guess not but this is what is stored in the fatra server. Maybe something missing there, @wenzeslaus ?

Found the nc_spm_full_v2beta1.tar.gz file on the server, updated in a0b135c

echoix · 2026-06-08T21:19:08Z

+  grass
+  script_intro
+  pygrass_index
+  exceptions
+  imaging
+  pydispatch
+  temporal_framework
+  gunittest_testing


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?

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]

echoix · 2026-06-08T21:21:25Z

+# 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"]


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.

@echoix Do you see any differences?

echoix · 2026-06-08T21:22:06Z

    "repo_url": "https://github.com/OSGeo/grass/",
    "repo_name": "GRASS",
    "repo_type": "github",
-    "logo": "grass_logo.svg",


Was there a problem with this one too?

This was the warning (I have added the original warnings above):

preparing documents... WARNING: unsupported theme option 'logo' given

petrasovaa · 2026-06-09T04:06:59Z

 import string
 from shutil import copy

+from _pickleable import table_fix, derender_toc


Where is this?

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]

Reverted in 8128a30.
The warning remains.

neteler added this to the 8.6.0 milestone Jun 8, 2026

neteler self-assigned this Jun 8, 2026

neteler added the docs label Jun 8, 2026

fix sample data entry

c5b3f5e

echoix reviewed Jun 8, 2026

View reviewed changes

github-actions Bot added Python Related code is in Python libraries labels Jun 8, 2026

petrasovaa reviewed Jun 9, 2026

View reviewed changes

Comment thread python/grass/docs/src/gunittest_testing.rst Outdated

neteler and others added 5 commits June 9, 2026 07:35

index.rst: restore some lost entries

1357dd2

gunittest: streamline sample data title and URL

2c8b360

reverted _pickleable and -html_context stuff

8128a30

Merge branch 'main' into sphinx_docs_fixes

812e147

update GRASS sample data URL and dataset name

a0b135c

		@@ -716,9 +714,8 @@ Further reading


		.. _unittest: https://docs.python.org/2/library/unittest.html

Uh oh!

Conversation

neteler commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neteler Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

neteler commented Jun 8, 2026 •

edited

Loading

neteler Jun 10, 2026 •

edited

Loading