[GRASS-git] [OSGeo/grass] 7bc9ce: docs: Configure intersphinx to reference Python's ...

[Edouard Choinière]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 7bc9ce071b203bf91ba413c8360dafbf9f009734
      https://github.com/OSGeo/grass/commit/7bc9ce071b203bf91ba413c8360dafbf9f009734
  Author: Edouard Choinière <27212526+echoix at users.noreply.github.com>
  Date:   2025-06-10 (Tue, 10 Jun 2025)

  Changed paths:
    M python/grass/app/data.py
    M python/grass/docs/conf.py
    M python/grass/script/core.py
    M python/grass/script/raster.py
    M python/grass/script/setup.py

  Log Message:
  -----------
  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



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications