docs: Configure intersphinx to reference Python's and NumPy's docs (#5861)

By enabling the widely used intersphinx functionality, Sphinx is able to resolve types, exceptions, etc. and allows us to create cross-references to the docs of an external project, like the Python standard library.

For example, a `:raises OSError: ...` or `:raises ValueError: ...` in the docstrings are magically linked to the Python docs. Same thing for the base classes that come from NumPy.

When using cross-refs, I opted to be explicit by using `:external:` followed by the domain and role, so looking like: ``:external:py:func:`sys.exit` ``. It then makes it easier to search for `:external:`, and there's less a surprise that Sphinx links to the python docs when not knowing about it. This comes in as justified when we know we have a couple of classes that override/wrap some python stdlib classes, like our `grass.script.core.Popen`, so being explicit is useful.


* docs: Configure intersphinx extension for linking to python library docs

* docs: Create external references to python docs in grass.script.core and related docstrings

* docs: Add external cross-refs to RegionManager docstrings

* docs: Add numpy inventory to intersphinx config

Author: echoix

python/grass/app/data.py

@@ -207,7 +207,8 @@ def acquire_mapset_lock(
     :param env: system environment variables
 
     The function assumes the `GISBASE` variable is in the environment. The variable is
-    used to find the lock program. If *env* is not provided, `os.environ` is used.
+    used to find the lock program. If *env* is not provided,
+    :external:py:data:`os.environ` is used.
     """
     if process_id is None:
         process_id = os.getpid()

python/grass/docs/conf.py

@@ -104,6 +104,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
@@ -498,3 +499,9 @@
     "search.html",
     "genindex.html",
 ]
+
+# Intersphinx config
+intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3", None),
+}

python/grass/script/core.py

@@ -337,7 +337,7 @@ def handle_errors(returncode, result, args, kwargs):
     handling mechanism is not desirable or the return code has some
     meaning not necessarily interpreted as an error by the caller.
 
-    For ``errors="exit"``, ``sys.exit()`` is called with the
+    For ``errors="exit"``, :external:py:func:`sys.exit()` is called with the
     *returncode*, so it behaves similarly to a Bash script with
     ``set -e``. No additional error message or exception is produced.
     This might be useful for a simple script where error message
@@ -477,7 +477,7 @@ def run_command(*args, **kwargs):
 
     This function passes all arguments to ``start_command()``,
     then waits for the process to complete. It is similar to
-    ``subprocess.check_call()``, but with the :func:`make_command()`
+    :external:py:func:`subprocess.check_call()`, but with the :func:`make_command()`
     interface. By default, an exception is raised in case of a non-zero
     return code by default.
 
@@ -721,7 +721,8 @@ def exec_command(
     :param bool quiet: True to run quietly (<tt>--q</tt>)
     :param bool superquiet: True to run quietly (<tt>--qq</tt>)
     :param bool verbose: True to run verbosely (<tt>--v</tt>)
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     :param list kwargs: module's parameters
 
     """
@@ -740,7 +741,8 @@ def message(msg, flag=None, env=None):
 
     :param str msg: message to be displayed
     :param str flag: flags (given as string)
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     run_command("g.message", flags=flag, message=msg, errors="ignore", env=env)
 
@@ -753,11 +755,13 @@ def debug(msg, debug=1, env=None):
     (with `X` set to the debug level specified in the function call).
 
     :param str msg: debugging message to be displayed
-    :param str debug: debug level (0-5) with the following recommended levels:
-        Use 1 for messages generated once of few times,
-        3 for messages generated for each raster row or vector line,
-        5 for messages generated for each raster cell or vector point.
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param str debug: debug level (0-5) with the following recommended
+        levels:
+        - Use 1 for messages generated once of few times,
+        - 3 for messages generated for each raster row or vector line,
+        - 5 for messages generated for each raster cell or vector point.
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     if debug_level() >= debug:
         # TODO: quite a random hack here, do we need it somewhere else too?
@@ -771,7 +775,8 @@ def verbose(msg, env=None):
     """Display a verbose message using `g.message -v`
 
     :param str msg: verbose message to be displayed
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     message(msg, flag="v", env=env)
 
@@ -780,7 +785,8 @@ def info(msg, env=None):
     """Display an informational message using `g.message -i`
 
     :param str msg: informational message to be displayed
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     message(msg, flag="i", env=env)
 
@@ -799,7 +805,8 @@ def percent(i, n, s, env=None):
     :param int i: current item
     :param int n: total number of items
     :param int s: increment size
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     message("%d %d %d" % (i, n, s), flag="p", env=env)
 
@@ -808,7 +815,8 @@ def warning(msg, env=None):
     """Display a warning message using `g.message -w`
 
     :param str msg: warning message to be displayed
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     message(msg, flag="w", env=env)
 
@@ -821,7 +829,8 @@ def error(msg, env=None):
     For error handling using the standard mechanism use :func:`fatal()`.
 
     :param str msg: error message to be displayed
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     message(msg, flag="e", env=env)
 
@@ -830,11 +839,12 @@ def fatal(msg, env=None):
     """Display an error message using `g.message -e`, then abort or raise
 
     Raises exception when module global raise_on_error is 'True', abort
-    (calls exit) otherwise.
+    (calls :external:py:func:`sys.exit`) otherwise.
     Use :func:`set_raise_on_error()` to set the behavior.
 
     :param str msg: error message to be displayed
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     """
     global raise_on_error
     if raise_on_error:
@@ -847,8 +857,9 @@ def fatal(msg, env=None):
 def set_raise_on_error(raise_exp=True):
     """Define behaviour on fatal error (fatal() called)
 
-    :param bool raise_exp: True to raise ScriptError instead of calling
-                           sys.exit(1) in fatal()
+    :param bool raise_exp: True to raise :py:exc:`~grass.exceptions.ScriptError`
+        instead of calling :external:py:func:`sys.exit(1) <sys.exit>`
+        in :py:func:`~grass.script.core.fatal`
 
     :return: current status
     """
@@ -859,8 +870,9 @@ def set_raise_on_error(raise_exp=True):
 
 
 def get_raise_on_error():
-    """Return True if a ScriptError exception is raised instead of calling
-    sys.exit(1) in case a fatal error was invoked with fatal()
+    """Return True if a :py:exc:`~grass.exceptions.ScriptError` exception is raised
+    instead of calling :external:py:func:`sys.exit(1) <sys.exit>` in case a fatal error
+    was invoked with :py:func:`~grass.script.core.fatal`.
     """
     global raise_on_error
     return raise_on_error
@@ -872,10 +884,10 @@ def set_capture_stderr(capture=True):
 
     By default, standard error output (stderr) of child processes shows
     in the same place as output of the parent process. This may not
-    always be the same place as ``sys.stderr`` is written.
-    After calling this function, functions in the ``grass.script``
+    always be the same place as :external:py:data:`sys.stderr` is written.
+    After calling this function, functions in the :py:mod:`grass.script`
     package will capture the stderr of child processes and pass it
-    to ``sys.stderr`` if there is an error.
+    to :external:py:data:`sys.stderr` if there is an error.
 
     .. note::
 
@@ -1237,7 +1249,8 @@ def gisenv(env: _Env | None = None) -> KeyValue[str | None]:
         >>> print(env["GISDBASE"])  # doctest: +SKIP
         /opt/grass-data
 
-    :param env: dictionary with system environment variables (`os.environ` by default)
+    :param env: dictionary with system environment variables
+                (:external:py:data:`os.environ` by default)
     :return: list of GRASS variables
     """
     s = read_command("g.gisenv", flags="n", env=env)

python/grass/script/raster.py

@@ -459,7 +459,8 @@ def __init__(self, env: dict[str, str] | None = None, **kwargs):
         """
         Initializes the MaskManager.
 
-        :param env: Environment to use. Defaults to modifying os.environ.
+        :param env: Environment to use.
+                    Defaults to modifying :external:py:data:`os.environ`.
         :param kwargs: Keyword arguments passed to `g.region`
         """
         self.env = env if env is not None else os.environ
@@ -543,7 +544,8 @@ def __init__(self, env: dict[str, str] | None = None, **kwargs):
         """
         Initializes the MaskManager.
 
-        :param env: Environment to use. Defaults to modifying os.environ.
+        :param env: Environment to use.
+                    Defaults to modifying :external:py:data:`os.environ`.
         :param kwargs: Keyword arguments passed to `g.region`
         """
         self.env = env if env is not None else os.environ

python/grass/script/setup.py

@@ -409,7 +409,8 @@ class SessionHandle:
             pass
         # session ends automatically here when outside of the "with" block
 
-    The example above is modifying the global, process environment (`os.environ`).
+    The example above is modifying the global, process environment
+    (:external:py:data:`os.environ`).
     If you don't want to modify the global environment, use the _env_ parameter
     for the _init_ function to modify the provided environment instead.
     This environment is then available as an attribute of the session object.