Skip to content

docs: Generate libpython API docs only under the grass namespace #7740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
echoix merged 1 commit into from
Jul 17, 2026
Merged

docs: Generate libpython API docs only under the grass namespace #7740

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,15 +193,7 @@ CMakeUserPresets.json

# Auto-generated sphinx source files for python library docs
python/grass/docs/_templates/layout.html
python/grass/docs/src/exceptions.rst
python/grass/docs/src/ctypes*.rst
python/grass/docs/src/grass.*rst
python/grass/docs/src/gunittest.rst
python/grass/docs/src/imaging.rst
python/grass/docs/src/pydispatch.rst
python/grass/docs/src/pygrass.*rst
python/grass/docs/src/script.rst
python/grass/docs/src/temporal.rst

# Test result files
*junit.xml
2 changes: 1 addition & 1 deletion doc/examples/notebooks/parallelization_tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
"source": [
"### Data-based parallelization\n",
"Data-based parallelism involves spatial domain decomposition, a process of splitting data into smaller datasets that can be processed in parallel.\n",
"As part of [GRASS Python API](https://grass.osgeo.org/grass-stable/manuals/libpython/index.html), [GridModule](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.modules.grid.html) decomposes input data into rectangular tiles, executes a given tool for each tile in parallel, and merges the results. Effectively, tiling is applied virtually (using computational region), determining the spatial extent of analysis for each parallel process. In some cases such as moving window analysis, tiles need to overlap to get correct results. Note that GridModule can be fairly inefficient due to the overhead from merging results back and is therefore best suited for computationally-itensive tasks such as interpolation."
"As part of [GRASS Python API](https://grass.osgeo.org/grass-stable/manuals/libpython/index.html), [GridModule](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.modules.grid.html) decomposes input data into rectangular tiles, executes a given tool for each tile in parallel, and merges the results. Effectively, tiling is applied virtually (using computational region), determining the spatial extent of analysis for each parallel process. In some cases such as moving window analysis, tiles need to overlap to get correct results. Note that GridModule can be fairly inefficient due to the overhead from merging results back and is therefore best suited for computationally-itensive tasks such as interpolation."
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion doc/grass_projects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ data file are often the most practical and convenient options.
Projects can be created in various ways depending on the environment:

- GRASS Python API: Allows creating a project programmatically with the function
[`create_project`](https://grass.osgeo.org/grass-stable/manuals/libpython/script.html#script.core.create_project).
[`create_project`](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.create_project).
This example creates a project named *my_project* with a specific EPSG code:

```python
Expand Down
70 changes: 35 additions & 35 deletions doc/python_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,11 +292,11 @@ The [grass.pygrass.gis](https://grass.osgeo.org/grass-stable/manuals/libpython/p
module provides access to the project and region management
of GRASS. The [grass.pygrass.gis](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_gis.html)
module provides functions to create, manage, and delete GRASS projects and
mapsets. The core classes include [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase),
[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location),
and [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset).
mapsets. The core classes include [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Gisdbase),
[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location),
and [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Mapset).

The [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Gisdbase)
The [Gisdbase](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Gisdbase)
class provides access to the GRASS database
and where you can manage GRASS projects and mapsets.

Expand All @@ -311,14 +311,14 @@ print(projects)
```

This will return a list of all projects in the GRASS database directory as
[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location)
[Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location)
objects.

```text
['nc_spm_08_grass7', 'my_project']
```

The [Location](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.Location)
The [Location](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Location)
object provides access to the specific project
and its mapsets.

Expand All @@ -334,7 +334,7 @@ print(location.name)
mapsets = location.mapsets()
```

The [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/pygrass.gis.html#pygrass.gis.Mapset)
The [Mapset](https://grass.osgeo.org/grass86/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.Mapset)
object provides access to the specific mapset and its layers.

```python
Expand All @@ -352,7 +352,7 @@ For more details about the `gis` module, see the Full Documentation:

### Region

The [grass.pygrass.gis.region](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#pygrass.gis.region.Region)
The [grass.pygrass.gis.region](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#grass.pygrass.gis.region.Region)
module gives access to read and modify computational regions. For example, to
get the current extent and resolution of the active mapset:

Expand Down Expand Up @@ -416,7 +416,7 @@ Resolution: [10.0, 10.0]
For more details about the `region` module, see the Full Documentation:

<!-- markdownlint-disable-next-line line-length -->
[Full Documentation :material-arrow-right-bold:](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.gis.html#module-pygrass.gis){ .md-button }
[Full Documentation :material-arrow-right-bold:](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.gis.html#module-grass.pygrass.gis){ .md-button }

### Data Management

Expand Down Expand Up @@ -495,15 +495,15 @@ For more details about the `raster` module, see the Full Documentation:

The [grass.pygrass.vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vector)
module provides direct read and write access to vector data in GRASS.
The core classes include [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector)
The core classes include [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector)
and [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label).

| Class | Description |
| ----- | ----------- |
| [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector) | Provides basic information about vector data. |
| [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector) | Provides basic information about vector data. |
| [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label) | Read and write access to vector data. |

Here is a simple example with [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector)
Here is a simple example with [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector)
to check if a vector map exists and print the mapset it is in.

```python
Expand All @@ -520,7 +520,7 @@ if roads.exist():

With the [VectorTopo](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_vector.html#vectortopo-label)
class you can get the same basic information about the
vector map returned by the [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.Vector)
vector map returned by the [Vector](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.Vector)
class in addition to read and write access.

```python
Expand All @@ -544,17 +544,17 @@ and attributes are treated separately. This means that the attributes of a
vector are not automatically read when the geometry is read.

To build a geometry object, you can use the geometry class in the
[grass.pygrass.vector.geometry](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#module-pygrass.vector.geometry)
[grass.pygrass.vector.geometry](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#module-grass.pygrass.vector.geometry)
module.

| Geometry Class | Description |
| -------------- | ----------- |
| [Area](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Area) | Represents the topological composition of a closed ring of boundaries and a centroid. |
| [Boundary](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Boundary) | Represents the border line to describe an area. |
| [Centroid](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Centroid) | Represents a centroid feature in a vector map. |
| [Isle](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Isle) | Represents an isle feature in a vector map. |
| [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line) | Represents a line feature in a vector map. |
| [Point](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Point) | Represents a point feature in a vector map. |
| [Area](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Area) | Represents the topological composition of a closed ring of boundaries and a centroid. |
| [Boundary](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Boundary) | Represents the border line to describe an area. |
| [Centroid](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Centroid) | Represents a centroid feature in a vector map. |
| [Isle](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Isle) | Represents an isle feature in a vector map. |
| [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line) | Represents a line feature in a vector map. |
| [Point](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Point) | Represents a point feature in a vector map. |

Each geometry class has its own set of methods to help extract useful
information. For example, let's build a `Boundary` object from a list of points
Expand Down Expand Up @@ -625,7 +625,7 @@ with VectorTopo('roadsmajor', mode='rw') as roads:
roads.build()
```

Features can also be updated by using the [rewrite](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.VectorTopo.rewrite)
Features can also be updated by using the [rewrite](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.VectorTopo.rewrite)
method instead of the `write`. If the geometry of the feature has not changed,
you can save the attributes to the database table without rebuilding the
topology using `table.conn.commit`.
Expand Down Expand Up @@ -653,10 +653,10 @@ You can also use many of `Geometry` and `Attribute` methods to filter
features in a more concise way.

For example, to test if a random point is within 5000 meters of a road segment
you can use the [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line.distance)
method of the [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line)
geometry object. The [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.Line.distance)
method returns a [LineDist](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.geometry.LineDist)
you can use the [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line.distance)
method of the [Line](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line)
geometry object. The [distance](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.Line.distance)
method returns a [LineDist](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.geometry.LineDist)
object that contains the distance and the closest point on the line.

```python
Expand Down Expand Up @@ -686,8 +686,8 @@ with VectorTopo('roadsmajor') as roads:
```

Or to simply filter a table using `SQL` you can use the `where` method with
[table_to_dict](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.VectorTopo.table_to_dict)
to get a dictionary of the features that match the query, the [table.Filter](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass.vector.html#pygrass.vector.table.Filters)
[table_to_dict](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.VectorTopo.table_to_dict)
to get a dictionary of the features that match the query, the [table.Filter](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.pygrass.vector.html#grass.pygrass.vector.table.Filters)
class for more advanced operations.

```python
Expand Down Expand Up @@ -743,12 +743,12 @@ The *grass.script* package provides a set of tool-calling functions
which follow text input and output handling use cases from
a command-line shell perspective.
Four main functions are:
*[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.run_command)*,
*[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.parse_command)*,
*[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.read_command)*,
and *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.write_command)*.
*[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.run_command)*,
*[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.parse_command)*,
*[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.read_command)*,
and *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.write_command)*.

The *[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.run_command)*
The *[gs.run_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.run_command)*
function is used to run a GRASS tool when you require
no return value. For example, when computing raster slope with
[r.slope.aspect](r.slope.aspect.md):
Expand All @@ -757,7 +757,7 @@ no return value. For example, when computing raster slope with
gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
```

The *[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.parse_command)*
The *[gs.parse_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.parse_command)*
function is useful when the tool returns
machine-readable text output on the standard output.
For example, use it to parse the output of [v.db.select](v.db.select.md#json)
Expand All @@ -767,7 +767,7 @@ to represent attribute data in a Python dictionary:
data = gs.parse_command("v.db.select", map="hospitals", format="json")
```

The *[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.read_command)*
The *[gs.read_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.read_command)*
function returns the text output of a GRASS tool.
This can be useful when you want to print human-readable output of a tool.
For example, when reading the output of [g.region](g.region.md):
Expand All @@ -776,7 +776,7 @@ For example, when reading the output of [g.region](g.region.md):
print(gs.read_command("g.region", flags="p"))
```

The *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#script.core.write_command)*
The *[gs.write_command](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script.html#grass.script.core.write_command)*
function is used to send data to a GRASS tool
through the standard input. For example, when writing a custom color scheme to
a raster map with [r.colors](r.colors.md):
Expand Down
15 changes: 0 additions & 15 deletions python/grass/docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,25 +48,10 @@ libpythonhelp:
libpythonclean:
-rm -rf $(BUILDDIR)/*
-rm -f _templates/layout.html
-rm -f src/ctypes*.rst
-rm -f src/exceptions.rst
-rm -f src/gunittest.*rst
-rm -f src/imaging.rst
-rm -f src/pydispatch.rst
-rm -f src/pygrass.*rst
-rm -f src/script.rst
-rm -f src/temporal.rst
-rm -f src/grass*.rst

libpythonapidoc:
@echo "SPHINXBUILD: Using <$(SPHINXBUILD)>"
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../imaging/)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../exceptions/)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../gunittest/ ../gunittest/multireport.py ../gunittest/multirunner.py ../gunittest/main.py)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../pydispatch/)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../pygrass/)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../script/)
$(call run_grass,$(SPHINXAPIDOC) -T -f -t _templates/sphinx/apidoc/ -o src/ ../temporal/)
$(call run_grass,$(SPHINXAPIDOC) --module-first -T -f -t _templates/sphinx/apidoc/ -o src/ ../../grass)

libpythonhtml: checksphinx
Expand Down
Loading
Loading