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,7 @@
 import string
 from shutil import copy
 
+
 # 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 +90,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 +115,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 +218,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

python/grass/docs/src/gunittest_running_tests.rst

@@ -110,7 +110,7 @@ Currently there is full support only for running all the tests in
 the small (basic) version of GRASS sample Location for North Carolina
 (see `GRASS sample data`).
 
-.. _GRASS sample data: https://grass.osgeo.org/download/sample-data
+.. _GRASS sample data: https://grass.osgeo.org/download/data
 
 
 Example Bash script to run be used as a cron job

python/grass/docs/src/gunittest_testing.rst

@@ -715,10 +715,9 @@ Further reading
    gunittest_running_tests
 
 
-.. _unittest: https://docs.python.org/2/library/unittest.html
-.. _doctest: https://docs.python.org/2/library/doctest.html
+.. _unittest: https://docs.python.org/3/library/unittest.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/sampledata/north_carolina/ (nc_spm_full_v2beta1.tar.gz)

python/grass/docs/src/index.rst

@@ -23,7 +23,7 @@ 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
 
@@ -40,14 +40,15 @@ Additional Resources
 Modules and Packages
 --------------------
 .. toctree::
-   :maxdepth: 1
+  :maxdepth: 1
 
-   index
-   grass.tools
-   script_intro
-   pygrass_index
-   grass.jupyter
-   exceptions
-   imaging
-   pydispatch
-   gunittest_testing
+  grass
+  grass.tools
+  script_intro
+  pygrass_index
+  grass.jupyter
+  exceptions
+  imaging
+  pydispatch
+  temporal_framework
+  gunittest_testing