[PATCH libgpiod v2 0/3] doc: add rust docs

[PATCH libgpiod v2 0/3] doc: add rust docs

[Bartosz Golaszewski]

While full integration of Rust docs with sphinx is currently hard, if
not impossible, we can still follow the pattern we used for GLib
bindings and generate the docs using cargo, then linking to them from
the sphinx page.

While at it: fix some minor issues in conf.py.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
Changes in v2:
- Pass --package=libgpiod to cargo doc to limit the scope of the docs to
  the user-facing API of libgpiod rust bindings
- Drop LD_LIBRARY_PATH and SYSTEM_DEPS_LIBGPIOD_SEARCH_NATIVE variables
  from the environment of cargo doc as they're not needed at build-time
- Link to v1: https://lore.kernel.org/r/20250604-rust-docs-v1-0-8ff23924a917@linaro.org

---
Bartosz Golaszewski (3):
      doc: reformat conf.py with black
      doc: improve the readability of the prefix variable
      doc: integrate rust docs into the sphinx build

 .readthedocs.yaml |  3 +++
 docs/conf.py      | 43 ++++++++++++++++++++++++++++++++++---------
 docs/rust_api.rst | 22 ++++++++++++++--------
 3 files changed, 51 insertions(+), 17 deletions(-)
---
base-commit: 088c66ef20662b76eebf03e71f11196a5ae14b33
change-id: 20250604-rust-docs-502d6caf207b

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

[PATCH libgpiod v2 1/3] doc: reformat conf.py with black

[Bartosz Golaszewski]

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

There's one missing newline according to black so add it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 docs/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/conf.py b/docs/conf.py
index 6fb399dcf195bd01d1fa739de89f142672f3f16e..d89c13454baa8fbe9dab17b7c3fde6fc59b577f1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,6 +54,7 @@ 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 but app.outdir is
 # only set once the builder is initialized. Let's delay running gi-docgen
 # until we're notified.

-- 
2.48.1

[PATCH libgpiod v2 2/3] doc: improve the readability of the prefix variable

[Bartosz Golaszewski]

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

Currently the default value for prefix - indicating the current
directory - is an empty string. This means that if we do
"{prefix}/foo", we may end up pointing to the root directory which is
not what we want. Make "./" be the default value so that the example
becomes valid and add "/" where we couldn't do it before.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 docs/conf.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index d89c13454baa8fbe9dab17b7c3fde6fc59b577f1..04d1cea2a2175166555993c3e936e7cf1ebd0fe6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -61,15 +61,15 @@ html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
 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 ""
+    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",
+            f"{prefix}/bindings/glib/gi-docgen.toml",
+            f"{prefix}/bindings/glib/Gpiodglib-1.0.gir",
             "--output-dir",
             f"{app.outdir}",
         ],

-- 
2.48.1

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

[Bartosz Golaszewski]

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 --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>`_

-- 
2.48.1

Re: [PATCH libgpiod v2 0/3] doc: add rust docs

[Erik Schilling]

On Thu Jun 5, 2025 at 10:13 AM CEST, Bartosz Golaszewski wrote:
> While full integration of Rust docs with sphinx is currently hard, if
> not impossible, we can still follow the pattern we used for GLib
> bindings and generate the docs using cargo, then linking to them from
> the sphinx page.
>
> While at it: fix some minor issues in conf.py.
>
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> ---
> Changes in v2:
> - Pass --package=libgpiod to cargo doc to limit the scope of the docs to
>   the user-facing API of libgpiod rust bindings
> - Drop LD_LIBRARY_PATH and SYSTEM_DEPS_LIBGPIOD_SEARCH_NATIVE variables
>   from the environment of cargo doc as they're not needed at build-time
> - Link to v1: https://lore.kernel.org/r/20250604-rust-docs-v1-0-8ff23924a917@linaro.org
>
> ---
> Bartosz Golaszewski (3):
>       doc: reformat conf.py with black
>       doc: improve the readability of the prefix variable
>       doc: integrate rust docs into the sphinx build
>
>  .readthedocs.yaml |  3 +++
>  docs/conf.py      | 43 ++++++++++++++++++++++++++++++++++---------
>  docs/rust_api.rst | 22 ++++++++++++++--------
>  3 files changed, 51 insertions(+), 17 deletions(-)
> ---
> base-commit: 088c66ef20662b76eebf03e71f11196a5ae14b33
> change-id: 20250604-rust-docs-502d6caf207b
>
> Best regards,
> -- 
> Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

My config on new setup is still all messed up. This time to the right
set of To: and with the right mail...:

Reviewed-by: Erik Schilling <erik@riscstar.com>

Re: [PATCH libgpiod v2 0/3] doc: add rust docs

[Viresh Kumar]

On 05-06-25, 10:13, Bartosz Golaszewski wrote:
> While full integration of Rust docs with sphinx is currently hard, if
> not impossible, we can still follow the pattern we used for GLib
> bindings and generate the docs using cargo, then linking to them from
> the sphinx page.
> 
> While at it: fix some minor issues in conf.py.
> 
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> ---
> Changes in v2:
> - Pass --package=libgpiod to cargo doc to limit the scope of the docs to
>   the user-facing API of libgpiod rust bindings
> - Drop LD_LIBRARY_PATH and SYSTEM_DEPS_LIBGPIOD_SEARCH_NATIVE variables
>   from the environment of cargo doc as they're not needed at build-time
> - Link to v1: https://lore.kernel.org/r/20250604-rust-docs-v1-0-8ff23924a917@linaro.org
> 
> ---
> Bartosz Golaszewski (3):
>       doc: reformat conf.py with black
>       doc: improve the readability of the prefix variable
>       doc: integrate rust docs into the sphinx build

Reviewed-by: Viresh Kumar <viresh.kumar@linaro.org>

-- 
viresh

Re: [PATCH libgpiod v2 0/3] doc: add rust docs

[Bartosz Golaszewski]

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


On Thu, 05 Jun 2025 10:13:18 +0200, Bartosz Golaszewski wrote:
> While full integration of Rust docs with sphinx is currently hard, if
> not impossible, we can still follow the pattern we used for GLib
> bindings and generate the docs using cargo, then linking to them from
> the sphinx page.
> 
> While at it: fix some minor issues in conf.py.
> 
> [...]

Applied, thanks!

[1/3] doc: reformat conf.py with black
      commit: 1c4199e56b74162838a9510097302e3a79fe4190
[2/3] doc: improve the readability of the prefix variable
      commit: 4b779774dbe73acc15e29b0b53b548248dcb8202
[3/3] doc: integrate rust docs into the sphinx build
      commit: e4427590d9d63a7104dd5df564dd6b7b0c784547

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>