diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 3c04964d77d..0b1eba66864 100644 --- a/.github/workflows/documentation.yml +++ b/.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 \ diff --git a/man/mkdocs/mkdocs.yml b/man/mkdocs/mkdocs.yml index f20e57b0e85..bf6c5781088 100644 --- a/man/mkdocs/mkdocs.yml +++ b/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 @@ docs_dir: source 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,61 @@ extra_css: plugins: - search - glightbox + # - autorefs + - 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 + - url: https://docs.python.org/3/objects.inv + domains: [std, py] + + 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 + signature_crossrefs: 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}" diff --git a/man/mkdocs/requirements.txt b/man/mkdocs/requirements.txt index 29c7efef97a..7c81b9d34c1 100644 --- a/man/mkdocs/requirements.txt +++ b/man/mkdocs/requirements.txt @@ -4,3 +4,4 @@ mkdocs-material==9.6.15 pymdown-extensions==10.16 pyyaml-env-tag==1.1 mkdocs-material[imaging]==9.6.15 +mkdocs-api-autonav diff --git a/python/grass/pygrass/vector/geometry.py b/python/grass/pygrass/vector/geometry.py index c599f5f1624..c25add1edc2 100644 --- a/python/grass/pygrass/vector/geometry.py +++ b/python/grass/pygrass/vector/geometry.py @@ -719,7 +719,7 @@ def point_on_line(self, distance, angle=0, slope=0): """Return a Point object on line in the specified distance, using the `Vect_point_on_line` C function. - :raises: Raise a ValueError If the distance exceed the Line length. + :raises ValueError: Raise a ValueError if the distance exceeds the Line length. .. code-block:: pycon @@ -736,7 +736,7 @@ def point_on_line(self, distance, angle=0, slope=0): # instantiate an empty Point object maxdist = self.length() if distance > maxdist: - str_err = "The distance exceed the length of the line, that is: %f" + str_err = "The distance exceeds the length of the line, that is: %f" raise ValueError(str_err % maxdist) pnt = Point(0, 0, -9999) if not libvect.Vect_point_on_line( diff --git a/python/grass/script/raster.py b/python/grass/script/raster.py index 2095f02de91..b6ebca6f4da 100644 --- a/python/grass/script/raster.py +++ b/python/grass/script/raster.py @@ -422,10 +422,12 @@ class RegionManager: Example with explicit region parameters: - >>> with gs.RegionManager(n=226000, s=222000, w=634000, e=638000): - ... gs.parse_command("r.univar", map="elevation", format="json") + .. code-block:: pycon + + >>> 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 @@ class RegionManager: ... 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: