docs: Mkdocstrings griffe 01

.github/workflows/documentation.yml

@@ -147,6 +147,7 @@ jobs:
       - name: Get mkdocs
         run: |
           pip install -r "grass/man/mkdocs/requirements.txt"
+          pip install 'mkdocstrings[python]'
 
       - name: Run mkdocs
         run: |
@@ -155,10 +156,12 @@ jobs:
           cd ..
           export SITE_NAME="GRASS $VERSION Documentation"
           export COPYRIGHT="© 2003-$YEAR GRASS Development Team, GRASS $VERSION Documentation"
+          export GRASS_PYTHON_DIR="$(grass --config python_path)"
           cd $MKDOCS_DIR
-          mkdocs build
+          grass --tmp-project XY --exec mkdocs build
 
       - name: Build Sphinx documentation
+        if: false
         run: |
           pip install -r "grass/python/grass/docs/requirements.txt"
           cd grass
@@ -167,6 +170,7 @@ jobs:
           mv -v dist.$ARCH/docs/html/libpython $MKDOCS_DIR/site
 
       - name: Merge Sphinx and MkDocs Sitemaps
+        if: false
         run: |
           cd grass
           python utils/merge_sitemaps.py \

man/mkdocs/mkdocs.yml

@@ -1,7 +1,7 @@
 ---
 # Project information
 site_author: The GRASS Development Team # Default author to all pages
-site_name: !ENV SITE_NAME
+site_name: !ENV [SITE_NAME, 'GRASS $VERSION Documentation']
 site_url: https://grass.osgeo.org/grass-stable/manuals/
 
 # Repository information
@@ -14,7 +14,7 @@
 use_directory_urls: false
 
 # Copyright
-copyright: !ENV COPYRIGHT
+copyright: !ENV [COPYRIGHT, '© 2003-$YEAR GRASS Development Team, GRASS $VERSION Documentation']
 
 # Theme configuration
 theme:
@@ -82,6 +82,56 @@
 plugins:
   - search
   - glightbox
+  - api-autonav:
+      exclude:
+        - "grass.lib"
+        - "ctypes"
+        - "grass.lib.ctypes_preamble.ctypes"
+        - "grass.lib.ctypes_preamble"
+        - grass.temporal.unit_tests
+        - grass.pygrass.modules.shortcuts
+      modules: [../../etc/python/grass]
+  - mkdocstrings:
+      handlers:
+        python:
+          inventories:
+            - https://numpy.org/doc/stable/objects.inv
+            - https://docs.python.org/3/objects.inv 
+          options:
+            docstring_style: sphinx
+            # allow_inspection: true
+            force_inspection: true
+            preload_modules:
+              - grass.script
+              # - grass
+              # - numpy
+            show_if_no_docstring: true
+            summary: true
+            parameter_headings: true
+            show_signature_annotations: true
+            filters:
+              - "!^_[^_]"
+              - "!^unit_tests"
+          # load_external_modules: true
+          # docstring_style: sphinx
+          paths: 
+            - !ENV [GRASS_PYTHON_DIR, '.']
+            - '.'
+            - !ENV [LD_LIBRARY_PATH, '.']
+
+          # paths: [/home/vscode/grass/dist.x86_64-pc-linux-gnu/lib, /home/vscode/grass/dist.x86_64-pc-linux-gnu/etc/python, /home/vscode/grass/dist.x86_64-pc-linux-gnu/docs/mkdocs]
+          # paths: [/home/vscode/grass/dist.x86_64-pc-linux-gnu/etc/python, .]
+          # paths: [/home/vscode/grass/dist.x86_64-pc-linux-gnu/etc/python/grass]
+
+      # modules: [../../etc/python/grass, ., ]
+  # - mkdocs-autoapi
+  # # - mkdocs-autoapi:
+  # #     autoapi_dir: /home/vscode/grass/dist.x86_64-pc-linux-gnu/etc/python/grass
+  # - mkdocstrings:
+  #     handlers:
+  #       python:
+  #         paths: [/home/vscode/grass/dist.x86_64-pc-linux-gnu/etc/python]
+
   - tags:
       tags_name_property: keywords
       tags_slugify_format: "{slug}"

man/mkdocs/requirements.txt

@@ -4,3 +4,4 @@ mkdocs-material==9.6.14
 pymdown-extensions==10.16
 pyyaml-env-tag==1.1
 mkdocs-material[imaging]==9.6.14
+mkdocs-api-autonav

python/grass/script/raster.py

@@ -421,11 +421,13 @@
     The original region is saved at the beginning of the context and restored at the end.
 
     Example with explicit region parameters:
+    
+    .. code-block:: pycon
 
-    >>> with gs.RegionManager(n=226000, s=222000, w=634000, e=638000):
-    ...     gs.parse_command("r.univar", map="elevation", format="json")
+        >>> with gs.RegionManager(n=226000, s=222000, w=634000, e=638000):
+        ...     gs.parse_command("r.univar", map="elevation", format="json")
 
-    Example matching a raster map's region:
+    Example matching a raster map's region::
 
     >>> with gs.RegionManager(raster="elevation"):
     ...     gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
@@ -436,6 +438,7 @@
     ...     gs.run_command("g.region", n=226000, s=222000, w=634000, e=638000)
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
+    Example2 using :func:`~grass.script.raster.RegionManager.set_region`:
     Example using :py:func:`~grass.script.raster.RegionManager.set_region`:
 
     >>> with gs.RegionManager() as manager: