[PATCH libgpiod v3 12/16] doc: add documentation for python bindings

[Bartosz Golaszewski <brgl@bgdev.pl>]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Integrate python docs with sphinx using autodoc and the import mock
feature which allows us to avoid having to build the C extension.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 docs/Makefile.am              | 13 ++++++++++++-
 docs/bindings.rst             |  1 +
 docs/conf.py                  | 18 +++++++++++++++++-
 docs/python_api.rst           | 33 +++++++++++++++++++++++++++++++++
 docs/python_chip.rst          | 12 ++++++++++++
 docs/python_chip_info.rst     | 12 ++++++++++++
 docs/python_edge_event.rst    | 12 ++++++++++++
 docs/python_exceptions.rst    | 17 +++++++++++++++++
 docs/python_info_event.rst    | 12 ++++++++++++
 docs/python_line.rst          | 27 +++++++++++++++++++++++++++
 docs/python_line_info.rst     | 12 ++++++++++++
 docs/python_line_request.rst  | 12 ++++++++++++
 docs/python_line_settings.rst | 12 ++++++++++++
 docs/python_misc.rst          | 13 +++++++++++++
 14 files changed, 204 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index b8cf010..dd3e6ac 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -31,7 +31,18 @@ DOCS_DEPS = \
 	cpp_misc.rst \
 	cpp_request_config.rst \
 	Doxyfile \
-	index.rst
+	index.rst \
+	python_api.rst \
+	python_chip_info.rst \
+	python_chip.rst \
+	python_edge_event.rst \
+	python_exceptions.rst \
+	python_info_event.rst \
+	python_line_info.rst \
+	python_line_request.rst \
+	python_line.rst \
+	python_line_settings.rst \
+	python_misc.rst
 
 docs: $(DOCS_DEPS)
 	sphinx-build ./ ./sphinx-output
diff --git a/docs/bindings.rst b/docs/bindings.rst
index 069fc8f..ed7ec69 100644
--- a/docs/bindings.rst
+++ b/docs/bindings.rst
@@ -18,3 +18,4 @@ C library.
    :caption: Contents
 
    cpp_api
+   python_api
diff --git a/docs/conf.py b/docs/conf.py
index 04c8c3b..3d0209a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,6 +9,7 @@ import os
 import re
 import subprocess
 import sys
+from pathlib import Path
 
 project = "libgpiod"
 copyright = "2017-2025, Bartosz Golaszewski"
@@ -34,11 +35,14 @@ with open("../configure.ac", "r") as fd:
 
         release = f"{version}{extra}"
 
-extensions = ["breathe"]
+extensions = ["breathe", "sphinx.ext.autodoc"]
 
 breathe_projects = {"libgpiod": "./doxygen-output/xml"}
 breathe_default_project = "libgpiod"
 
+sys.path.insert(0, str(Path("../bindings/python").resolve()))
+autodoc_mock_imports = ["gpiod._ext"]
+
 # Use the RTD theme if available
 sphinx_rtd_theme = None
 try:
@@ -50,4 +54,16 @@ except ImportError:
 
 html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
 
+
+def autodoc_skip_init(app, what, name, obj, would_skip, options):
+    if name == "__init__":
+        return False
+
+    return would_skip
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", autodoc_skip_init)
+
+
 subprocess.run(["doxygen", "Doxyfile"])
diff --git a/docs/python_api.rst b/docs/python_api.rst
new file mode 100644
index 0000000..00b30cb
--- /dev/null
+++ b/docs/python_api.rst
@@ -0,0 +1,33 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+   libgpiod python bindings documentation
+
+libgpiod Python bindings API
+============================
+
+The **libgpiod Python bindings** provide an interface to control and interact
+with GPIO (General-Purpose Input/Output) lines on Linux systems using the
+libgpiod library. The Python bindings allow developers to manage GPIO pins
+easily through Python scripts, enabling tasks such as reading input values,
+setting outputs, monitoring events, and configuring more fine-grained pin
+options.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   python_chip
+   python_chip_info
+   python_exceptions
+   python_line
+   python_line_info
+   python_info_event
+   python_edge_event
+   python_line_settings
+   python_line_request
+   python_misc
diff --git a/docs/python_chip.rst b/docs/python_chip.rst
new file mode 100644
index 0000000..8f56004
--- /dev/null
+++ b/docs/python_chip.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO chip
+=========
+
+.. autoclass:: gpiod.Chip
+   :members:
diff --git a/docs/python_chip_info.rst b/docs/python_chip_info.rst
new file mode 100644
index 0000000..c6db865
--- /dev/null
+++ b/docs/python_chip_info.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO chip info
+==============
+
+.. autoclass:: gpiod.ChipInfo
+   :members:
diff --git a/docs/python_edge_event.rst b/docs/python_edge_event.rst
new file mode 100644
index 0000000..b316665
--- /dev/null
+++ b/docs/python_edge_event.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO edge event
+===============
+
+.. autoclass:: gpiod.EdgeEvent
+   :members:
diff --git a/docs/python_exceptions.rst b/docs/python_exceptions.rst
new file mode 100644
index 0000000..260dc3d
--- /dev/null
+++ b/docs/python_exceptions.rst
@@ -0,0 +1,17 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+libgpiod python errors
+======================
+
+.. autoclass:: gpiod.ChipClosedError
+   :members:
+   :show-inheritance:
+
+.. autoclass:: gpiod.RequestReleasedError
+   :members:
+   :show-inheritance:
diff --git a/docs/python_info_event.rst b/docs/python_info_event.rst
new file mode 100644
index 0000000..b89cdfa
--- /dev/null
+++ b/docs/python_info_event.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO info event
+===============
+
+.. autoclass:: gpiod.InfoEvent
+   :members:
diff --git a/docs/python_line.rst b/docs/python_line.rst
new file mode 100644
index 0000000..ec8f09f
--- /dev/null
+++ b/docs/python_line.rst
@@ -0,0 +1,27 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO line definitions
+=====================
+
+.. autoclass:: gpiod.line.Value
+   :members:
+
+.. autoclass:: gpiod.line.Direction
+   :members:
+
+.. autoclass:: gpiod.line.Bias
+   :members:
+
+.. autoclass:: gpiod.line.Drive
+   :members:
+
+.. autoclass:: gpiod.line.Edge
+   :members:
+
+.. autoclass:: gpiod.line.Clock
+   :members:
diff --git a/docs/python_line_info.rst b/docs/python_line_info.rst
new file mode 100644
index 0000000..06f526f
--- /dev/null
+++ b/docs/python_line_info.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO line info
+==============
+
+.. autoclass:: gpiod.LineInfo
+   :members:
diff --git a/docs/python_line_request.rst b/docs/python_line_request.rst
new file mode 100644
index 0000000..2d78b4c
--- /dev/null
+++ b/docs/python_line_request.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO line request
+=================
+
+.. autoclass:: gpiod.LineRequest
+   :members:
diff --git a/docs/python_line_settings.rst b/docs/python_line_settings.rst
new file mode 100644
index 0000000..b1d594e
--- /dev/null
+++ b/docs/python_line_settings.rst
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+GPIO line settings
+==================
+
+.. autoclass:: gpiod.LineSettings
+   :members:
diff --git a/docs/python_misc.rst b/docs/python_misc.rst
new file mode 100644
index 0000000..3ba1e2d
--- /dev/null
+++ b/docs/python_misc.rst
@@ -0,0 +1,13 @@
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+libgpiod python bindings misc
+=============================
+
+.. autofunction:: gpiod.is_gpiochip_device
+
+.. autofunction:: gpiod.request_lines

-- 
2.45.2