diff mbox series

[libgpiod,v3,13/16] doc: add documentation for GLib bindings

Message ID 20250206-improve-docs-v3-13-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>

The GObject docs are generated with gi-docgen and there doesn't seem to
be an easy way of converting them to sphinx. Let's put the GLib docs
statically into the sphinx output and reference them from the bindings
chapter.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 .readthedocs.yaml |  9 ++++++++-
 docs/Makefile.am  |  1 +
 docs/bindings.rst |  1 +
 docs/conf.py      | 38 ++++++++++++++++++++++++++++++++++++++
 docs/glib_api.rst | 23 +++++++++++++++++++++++
 5 files changed, 71 insertions(+), 1 deletion(-)
diff mbox series

Patch

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 510b5c1..97086fa 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -11,13 +11,20 @@ 
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.12"
   apt_packages:
+      - autoconf
+      - autoconf-archive
       # doxygen is available by default, but just in case.
       - doxygen
+      - gi-docgen
+      - gir1.2-glib-2.0-dev
+      - gobject-introspection
       - graphviz
+      - libtool
+      - pkg-config
 
 sphinx:
    configuration: docs/conf.py
diff --git a/docs/Makefile.am b/docs/Makefile.am
index dd3e6ac..ef9ebf2 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -32,6 +32,7 @@  DOCS_DEPS = \
 	cpp_request_config.rst \
 	Doxyfile \
 	index.rst \
+	glib_api.rst \
 	python_api.rst \
 	python_chip_info.rst \
 	python_chip.rst \
diff --git a/docs/bindings.rst b/docs/bindings.rst
index ed7ec69..73f1262 100644
--- a/docs/bindings.rst
+++ b/docs/bindings.rst
@@ -19,3 +19,4 @@  C library.
 
    cpp_api
    python_api
+   glib_api
diff --git a/docs/conf.py b/docs/conf.py
index 3d0209a..33fc89f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -62,8 +62,46 @@  def autodoc_skip_init(app, what, name, obj, would_skip, options):
     return would_skip
 
 
+# We need to know where to put docs generated by gi-docgen but app.outdir is
+# only set once the builder is initialized. Let's delay running gi-docgen
+# until we're notified.
+def make_glib_docs(app):
+    # For some reason on RTD we're in the docs/ directory while during a local
+    # build, we're still in the top source directory.
+    prefix = "../" if os.getenv("READTHEDOCS") == "True" else ""
+
+    subprocess.run(
+        [
+            "gi-docgen",
+            "generate",
+            "--config",
+            f"{prefix}bindings/glib/gi-docgen.toml",
+            f"{prefix}bindings/glib/Gpiodglib-1.0.gir",
+            "--output-dir",
+            f"{app.outdir}",
+        ],
+        check=True,
+    )
+
+
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_init)
+    app.connect("builder-inited", make_glib_docs)
 
 
 subprocess.run(["doxygen", "Doxyfile"])
+
+cwd = os.getcwd()
+os.chdir("..")
+subprocess.run(["autoreconf", "-ifv"], check=True)
+subprocess.run(
+    [
+        "./configure",
+        "--enable-tools",
+        "--enable-bindings-glib",
+        "--enable-introspection",
+    ],
+    check=True,
+)
+subprocess.run(["make", "-j"], check=True)
+os.chdir(cwd)
diff --git a/docs/glib_api.rst b/docs/glib_api.rst
new file mode 100644
index 0000000..307f5f7
--- /dev/null
+++ b/docs/glib_api.rst
@@ -0,0 +1,23 @@ 
+..
+   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 GObject API documentation
+
+libgpiod GObject bindings API
+=============================
+
+**GObject bindings** for libgpiod provide a high-level, object-oriented
+interface to interact with GPIO (General Purpose Input/Output) lines on Linux
+systems. These bindings leverage the **GObject framework**, commonly used in
+GNOME and GTK+ applications, to wrap the lower-level C API of libgpiod.
+
+.. warning::
+   The documentation for GObject bindings is generated using gi-docgen and
+   cannot be easily integrated with sphinx documentation. Please navigate to
+   a separate section dedicated exclusively to the GLib part of the API.
+
+`Navigate to GObject bindings documentation <Gpiodglib-1.0/index.html>`_