docs: fix sphinx build warnings and broken cross-references

doc/Makefile

@@ -6,7 +6,7 @@ SUBDIRS = \
 include $(MODULE_TOPDIR)/include/Make/Dir.make
 
 FILES := $(wildcard *.html)
-# So far, we disntinguished user and contributor documentation here by
+# So far, we distinguished user and contributor documentation here by
 # extension. This is no longer possible with Markdown.
 MDFILES := grass_database.md \
 	projectionintro.md \

python/grass/docs/_templates/sphinx/apidoc/package.rst.jinja

@@ -1,8 +1,11 @@
-{%- macro automodule(modname, options) -%}
+{%- macro automodule(modname, options, noindex=False) -%}
 .. automodule:: {{ modname }}
 {%- for option in options %}
    :{{ option }}:
 {%- endfor %}
+{%- if noindex %}
+   :no-index:
+{%- endif %}
 {%- endmacro %}
 
 {%- macro toctree(docnames) -%}
@@ -24,7 +27,10 @@
 {% endif %}
 
 {%- if modulefirst and not is_namespace %}
-{{ automodule(pkgname, automodule_options) }}
+{# Root grass package keeps full index; subpackages use no-index to avoid
+   duplicating index entries that the parent already generates recursively. #}
+{%- set _pkg_noindex = pkgname != "grass" %}
+{{ automodule(pkgname, automodule_options, noindex=_pkg_noindex) }}
 {% endif %}
 
 {%- if subpackages %}
@@ -44,7 +50,7 @@ Submodules
 {% if show_headings %}
 {{- [submodule, "module"] | join(" ") | e | heading(2) }}
 {% endif %}
-{{ automodule(submodule, automodule_options) }}
+{{ automodule(submodule, automodule_options, noindex=True) }}
 {% endfor %}
 {%- endif %}
 {%- endif %}
@@ -53,5 +59,8 @@ Submodules
 Module contents
 ---------------
 
-{{ automodule(pkgname, automodule_options) }}
+{# Root grass package keeps full index; subpackages use no-index to avoid
+   duplicating index entries that the parent already generates recursively. #}
+{%- set _pkg_noindex = pkgname != "grass" %}
+{{ automodule(pkgname, automodule_options, noindex=_pkg_noindex) }}
 {% endif %}

python/grass/docs/conf.py

@@ -16,6 +16,8 @@
 import string
 from shutil import copy
 
+from _pickleable import table_fix, derender_toc
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -89,7 +91,7 @@
 )
 
 grass_version = core.version()["version"]
-today = date.today()
+today = date.today().strftime("%B %d, %Y")
 
 copy("_templates/layout.html.template", "_templates/layout.html")
 
@@ -114,6 +116,31 @@
     "sphinx_sitemap",
 ]
 
+# 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"]
+
+
+# Skip temporal lexer rule methods because their regex docstrings are not intended
+# for reStructuredText parsing and only serve PLY token definitions.
+def skip_member(app, what, name, obj, skip, options):
+    if name.startswith("t_"):
+        mod = getattr(obj, "__module__", None)
+        if mod in {
+            "grass.temporal.temporal_algebra",
+            "grass.temporal.temporal_operator",
+            "temporal.temporal_algebra",
+            "temporal.temporal_operator",
+        }:
+            return True
+    return None
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_member)
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -192,7 +219,6 @@
     "repo_url": "https://github.com/OSGeo/grass/",
     "repo_name": "GRASS",
     "repo_type": "github",
-    "logo": "grass_logo.svg",
     # Visible levels of the global TOC; -1 means unlimited
     "globaltoc_depth": 1,
     # If False, expand all TOC entries
@@ -243,6 +269,14 @@
     ],
 }
 
+# Make html_context cacheable by replacing theme's class objects with
+# pickleable proxy instances.  The theme stores class objects (type instances)
+# in html_context which Sphinx's is_serializable() conservatively rejects.
+html_context = {
+    "table_fix": table_fix,
+    "derender_toc": derender_toc,
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 

python/grass/docs/src/gunittest_testing.rst

@@ -27,7 +27,7 @@ caused by C library functions does not influence the main testing process.
 
 Some tests will run without any data but many tests require
 the small (basic) version of GRASS sample Location for North Carolina
-(see `GRASS sample data`).
+(see `GRASS sample data testing`).
 
 Basic example
 -------------
@@ -506,8 +506,6 @@ However, do not use use doctest for tests of edge cases, for tests which require
 generate complex data first, etc. In these cases use `gunittest`.
 
 
-.. _test-as-scripts:
-
 Tests as general scripts
 ------------------------
 
@@ -716,9 +714,8 @@ Further reading
 
 
 .. _unittest: https://docs.python.org/2/library/unittest.html
-.. _doctest: https://docs.python.org/2/library/doctest.html
 .. _Coverity Scan: https://scan.coverity.com/
 .. _1038: https://scan.coverity.com/projects/1038
 .. _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)

python/grass/docs/src/index.rst

@@ -23,31 +23,28 @@ at various levels:
 * `grass.jupyter package <grass.jupyter.html>`_ offers classes and setup functions for
   running GRASS in Jupyter Notebooks
 * `Testing GRASS source code and modules <gunittest_testing.html>`_ using gunittest package
-* `exceptions package <exceptions.html>`_ contains exceptions used by other packages
+* `exceptions package <grass.exceptions.html>`_ contains exceptions used by other packages
 * `imaging package <imaging.html>`_ is a library to create animated images and films
 * `pydispatch package <pydispatch.html>`_ is a library for signal-dispatching
 
 --------------------
 Additional Resources
 --------------------
-* `GRASS Python introduction <manuals/python_intro.html>`_ provides a general overview of
+* `GRASS Python introduction <../python_intro.html>`_ provides a general overview of
   the Python interface to GRASS.
-* `GRASS Jupyter notebooks introduction <manuals/jupyter_intro.html>`_ provides an overview of how to use the **grass.jupyter** module.
-
-.. _GRASS: https://grass.osgeo.org/
+* `GRASS Jupyter notebooks introduction <../jupyter_intro.html>`_ provides an overview of how to use the **grass.jupyter** module.
 
 --------------------
 Modules and Packages
 --------------------
 .. toctree::
-   :maxdepth: 1
+  :maxdepth: 1
 
-   index
-   grass.tools
-   script_intro
-   pygrass_index
-   grass.jupyter
-   exceptions
-   imaging
-   pydispatch
-   gunittest_testing
+  grass
+  script_intro
+  pygrass_index
+  exceptions
+  imaging
+  pydispatch
+  temporal_framework
+  gunittest_testing

python/grass/docs/src/pygrass_gis.rst

@@ -1,5 +1,3 @@
-.. _GRASSdatabase-label:
-
 GRASS database management
 =========================
 
@@ -16,8 +14,6 @@ database management (locations and mapsets) can be found in the `GRASS
 User's Manual: GRASS Quickstart
 <https://grass.osgeo.org/grass-devel/manuals/helptext.html>`_.
 
-.. _Region-label:
-
 Region management
 =================
 

python/grass/docs/src/pygrass_raster.rst

@@ -1,5 +1,3 @@
-.. _raster-label:
-
 Introduction to Raster classes
 ==============================