diff mbox series

[libgpiod,v3,15/16] doc: add documentation for D-Bus API, daemon and command-line client

Message ID 20250206-improve-docs-v3-15-2065191fff6f@linaro.org
State New
Headers show
Series doc: improvements for ReadTheDocs | expand

Commit Message

Bartosz Golaszewski Feb. 6, 2025, 12:22 p.m. UTC 
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Use the man pages for gpio-manager and gpiocli + some manual labor to
provide sphinx docs for the libgpiod D-Bus API.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 .readthedocs.yaml    |  2 ++
 docs/.gitignore      |  6 ++++++
 docs/Makefile.am     |  3 +++
 docs/conf.py         | 17 +++++++++++++++++
 docs/dbus.rst        | 24 ++++++++++++++++++++++++
 docs/dbus_api.rst    | 23 +++++++++++++++++++++++
 docs/gpiocli_top.rst | 29 +++++++++++++++++++++++++++++
 docs/index.rst       |  1 +
 8 files changed, 105 insertions(+)
diff mbox series

Patch

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index c2b0a7f..5f4f5ac 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -24,6 +24,8 @@  build:
       - gir1.2-glib-2.0-dev
       - gobject-introspection
       - graphviz
+      - libglib2.0-dev-bin
+      - libgudev-1.0-dev
       - libtool
       - pandoc
       - pkg-config
diff --git a/docs/.gitignore b/docs/.gitignore
index c9ffb90..61dac9a 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -11,3 +11,9 @@  gpioget.rst
 gpioset.rst
 gpiomon.rst
 gpionotify.rst
+
+gpio-manager.rst
+
+dbus-io.gpiod1.*.rst
+gpiocli.rst
+gpiocli-*.rst
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 269dd7e..096095d 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -30,10 +30,13 @@  DOCS_DEPS = \
 	cpp_line_settings.rst \
 	cpp_misc.rst \
 	cpp_request_config.rst \
+	dbus.rst \
+	dbus_api.rst \
 	Doxyfile \
 	index.rst \
 	glib_api.rst \
 	gpio_tools.rst \
+	gpiocli_top.rst \
 	python_api.rst \
 	python_chip_info.rst \
 	python_chip.rst \
diff --git a/docs/conf.py b/docs/conf.py
index 5e20c17..bf4028d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -101,6 +101,7 @@  subprocess.run(
         "--enable-bindings-glib",
         "--enable-introspection",
         "--enable-tools",
+        "--enable-dbus",
     ],
     check=True,
 )
@@ -114,6 +115,20 @@  for page in [
     "gpioset",
     "gpiomon",
     "gpionotify",
+    "gpio-manager",
+    "gpiocli",
+    "gpiocli-detect",
+    "gpiocli-find",
+    "gpiocli-info",
+    "gpiocli-get",
+    "gpiocli-monitor",
+    "gpiocli-notify",
+    "gpiocli-reconfigure",
+    "gpiocli-release",
+    "gpiocli-request",
+    "gpiocli-requests",
+    "gpiocli-set",
+    "gpiocli-wait",
 ]:
     subprocess.run(
         [
@@ -127,3 +142,5 @@  for page in [
         ],
         check=True,
     )
+
+subprocess.run(["gdbus-codegen", "--generate-rst", "dbus", "../dbus/lib/io.gpiod1.xml"])
diff --git a/docs/dbus.rst b/docs/dbus.rst
new file mode 100644
index 0000000..0dcbb81
--- /dev/null
+++ b/docs/dbus.rst
@@ -0,0 +1,24 @@ 
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+   GPIO D-Bus API, daemon and command-line client documentation
+
+D-Bus interface
+===============
+
+The **libgpiod D-Bus API** provides an abstraction for interacting with GPIO
+chips on Linux systems via the D-Bus messaging system. It enables relatively
+efficient, asynchronous control of GPIO lines, offering methods for
+configuring, monitoring, and manipulating GPIOs.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   dbus_api
+   gpio-manager<gpio-manager>
+   gpiocli_top
diff --git a/docs/dbus_api.rst b/docs/dbus_api.rst
new file mode 100644
index 0000000..6192949
--- /dev/null
+++ b/docs/dbus_api.rst
@@ -0,0 +1,23 @@ 
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+   GPIO D-Bus API documentation
+
+D-Bus API
+=========
+
+The following set of strictly defined interfaces allow users to use any
+**D-Bus** library in order to interact with the **gpio-manager** as well as
+reimplement the manager itself if required.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Interfaces
+
+   dbus-io.gpiod1.Chip
+   dbus-io.gpiod1.Line
+   dbus-io.gpiod1.Request
diff --git a/docs/gpiocli_top.rst b/docs/gpiocli_top.rst
new file mode 100644
index 0000000..52e3295
--- /dev/null
+++ b/docs/gpiocli_top.rst
@@ -0,0 +1,29 @@ 
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+   GPIO D-Bus command-line client documentation
+
+Command-line client
+===================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manual entries
+
+   gpiocli<gpiocli>
+   gpiocli-detect<gpiocli-detect>
+   gpiocli-find<gpiocli-find>
+   gpiocli-info<gpiocli-info>
+   gpiocli-get<gpiocli-get>
+   gpiocli-monitor<gpiocli-monitor>
+   gpiocli-notify<gpiocli-notify>
+   gpiocli-reconfigure<gpiocli-reconfigure>
+   gpiocli-release<gpiocli-release>
+   gpiocli-request<gpiocli-request>
+   gpiocli-requests<gpiocli-requests>
+   gpiocli-set<gpiocli-set>
+   gpiocli-wait<gpiocli-wait>
diff --git a/docs/index.rst b/docs/index.rst
index a52cc3a..3101e14 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,3 +27,4 @@  this interface.
    core_api
    bindings
    gpio_tools
+   dbus