diff mbox series

[libgpiod,v2,3/3] doc: integrate rust docs into the sphinx build

Message ID 20250605-rust-docs-v2-3-883a0a3872c0@linaro.org
State New
Headers show
Series doc: add rust docs | expand

Commit Message

Bartosz Golaszewski June 5, 2025, 8:13 a.m. UTC 
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Follow the pattern we established with GLib bindings: generate a separate
set of docs for the rust bindings, make them part of the generated doc
bundle and point to the rust index.html from the dedicated sphinx page.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 .readthedocs.yaml |  3 +++
 docs/conf.py      | 38 +++++++++++++++++++++++++++++++-------
 docs/rust_api.rst | 22 ++++++++++++++--------
 3 files changed, 48 insertions(+), 15 deletions(-)
diff mbox series

Patch

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 5f4f5ac4954de70e060f1a7b2eafe3a731620c16..11ec1de1bddc5fe4525f9fdaffbb31781c0968d3 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -14,6 +14,7 @@  build:
   os: ubuntu-24.04
   tools:
     python: "3.12"
+    rust: "1.86"
   apt_packages:
       - autoconf
       - autoconf-archive
@@ -24,6 +25,8 @@  build:
       - gir1.2-glib-2.0-dev
       - gobject-introspection
       - graphviz
+      # Needed by rust bindgen for stdbool.h
+      - libclang-dev
       - libglib2.0-dev-bin
       - libgudev-1.0-dev
       - libtool
diff --git a/docs/conf.py b/docs/conf.py
index 04d1cea2a2175166555993c3e936e7cf1ebd0fe6..b41e78e95ab55183d2b8e48c160cca5118b70f58 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,15 +54,16 @@  except ImportError:
 
 html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
 
+# We need to know where to put docs generated by gi-docgen and cargo but
+# app.outdir is only set once the builder is initialized. Let's delay running
+# gi-docgen until we're notified.
+#
+# 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 "./"
+
 
-# 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",
@@ -77,8 +78,31 @@  def make_glib_docs(app):
     )
 
 
+def make_rust_docs(app):
+    subprocess.run(
+        [
+            "cargo",
+            "doc",
+            "--manifest-path",
+            f"{prefix}/bindings/rust/libgpiod/Cargo.toml",
+            "--target-dir",
+            f"{app.outdir}/rust/",
+            "--no-deps",
+            "--package=libgpiod",
+        ],
+        check=True,
+        env=dict(
+            os.environ,
+            SYSTEM_DEPS_LIBGPIOD_LIB="gpiod",
+            SYSTEM_DEPS_LIBGPIOD_NO_PKG_CONFIG="1",
+            SYSTEM_DEPS_LIBGPIOD_INCLUDE="../../../include/",
+        ),
+    )
+
+
 def setup(app):
     app.connect("builder-inited", make_glib_docs)
+    app.connect("builder-inited", make_rust_docs)
 
 
 subprocess.run(["doxygen", "Doxyfile"])
diff --git a/docs/rust_api.rst b/docs/rust_api.rst
index 1408b5c2457309938e314d1c289b81d583d9cc09..dda20d0baadcf8d97832cd60a60a5d00f99affc9 100644
--- a/docs/rust_api.rst
+++ b/docs/rust_api.rst
@@ -5,19 +5,25 @@ 
 ..
    This file is part of libgpiod.
 
-Where are the Rust bindings?
-=============================
+   libgpiod Rust bindings documentation
 
-.. warning::
-   There's currently no good way of integrating rust documentation with sphinx.
-   Rust bindings should be documented on https://docs.rs/ but due to a yet
-   unsolved build problem, this is currently not the case. Please refer to the
-   in-source comments for now.
+libgpiod Rust bindings API
+==========================
 
-Rust bindings are available on https://crates.io/ as the ``libgpiod`` package.
+Rust bindings for libgpiod aim to provide a memory-safe interface to the
+low-level C API. They are available on https://crates.io/ as the ``libgpiod``
+package.
 
 .. note::
    When building the Rust bindings along the C library using make, they will
    be automatically configured to build against the build results of the
    C library. Building rust bindings requires cargo to be available on the
    system.
+
+.. warning::
+   The documentation for Rust bindings is generated using ``cargo doc`` and
+   cannot be easily integrated with sphinx documentation. Please navigate to
+   a separate section dedicated exclusively to the Rust part of the API.
+
+
+`Navigate to Rust bindings documentation <rust/doc/libgpiod/index.html>`_