diff mbox series

[libgpiod,v3,14/16] doc: add documentation for gpio-tools

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

We already generate man pages for gpio-tools. Let's use man2html to make
them part of the sphinx docs.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 .readthedocs.yaml   |  2 ++
 configure.ac        | 32 +++++++++++++++++++-------------
 docs/.gitignore     |  8 ++++++++
 docs/Makefile.am    |  1 +
 docs/conf.py        | 22 ++++++++++++++++++++++
 docs/gpio_tools.rst | 25 +++++++++++++++++++++++++
 docs/index.rst      |  1 +
 7 files changed, 78 insertions(+), 13 deletions(-)
diff mbox series

Patch

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 97086fa..c2b0a7f 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -19,11 +19,13 @@  build:
       - autoconf-archive
       # doxygen is available by default, but just in case.
       - doxygen
+      - help2man
       - gi-docgen
       - gir1.2-glib-2.0-dev
       - gobject-introspection
       - graphviz
       - libtool
+      - pandoc
       - pkg-config
 
 sphinx:
diff --git a/configure.ac b/configure.ac
index 8eec855..af5d53d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -327,18 +327,6 @@  then
 		      AC_MSG_ERROR([systemdsystemunitdir not found - needed to enable systemd support]))
 fi
 
-AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false])
-AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false])
-AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue])
-if test "x$has_doxygen" = xfalse
-then
-	AC_MSG_NOTICE([doxygen not found - documentation cannot be generated])
-fi
-if test "x$has_sphinx" = xfalse
-then
-	AC_MSG_NOTICE([sphinx-build not found - documentation cannot be generated])
-fi
-
 if test "x$cross_compiling" = xno
 then
 	AC_CHECK_PROG([has_help2man], [help2man], [true], [false])
@@ -346,7 +334,25 @@  fi
 AM_CONDITIONAL([WITH_MANPAGES], [test "x$has_help2man" = xtrue])
 if test "x$has_help2man" = xfalse
 then
-	AC_MSG_NOTICE([help2man not found - man pages cannot be generated automatically])
+	AC_MSG_NOTICE([help2man not found - man pages and documentation cannot be generated])
+fi
+
+AC_DEFUN([DOC_PROG_NOT_FOUND], [AC_MSG_NOTICE([$1 not found - documentation cannot be generated])])
+AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false])
+AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false])
+AC_CHECK_PROG([has_pandoc], [pandoc], [true], [false])
+AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue && test "x$has_pandoc" = xtrue && test "x$has_help2man" = xtrue])
+if test "x$has_doxygen" = xfalse
+then
+	DOC_PROG_NOT_FOUND(["doxygen"])
+fi
+if test "x$has_sphinx" = xfalse
+then
+	DOC_PROG_NOT_FOUND(["sphinx-build"])
+fi
+if test "x$has_pandoc" = xfalse
+then
+	DOC_PROG_NOT_FOUND(["pandoc"])
 fi
 
 AC_CONFIG_FILES([Makefile
diff --git a/docs/.gitignore b/docs/.gitignore
index 86f8cfd..c9ffb90 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -3,3 +3,11 @@ 
 
 doxygen-output
 sphinx-output
+
+# Automatically generated .rst
+gpiodetect.rst
+gpioinfo.rst
+gpioget.rst
+gpioset.rst
+gpiomon.rst
+gpionotify.rst
diff --git a/docs/Makefile.am b/docs/Makefile.am
index ef9ebf2..269dd7e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -33,6 +33,7 @@  DOCS_DEPS = \
 	Doxyfile \
 	index.rst \
 	glib_api.rst \
+	gpio_tools.rst \
 	python_api.rst \
 	python_chip_info.rst \
 	python_chip.rst \
diff --git a/docs/conf.py b/docs/conf.py
index 33fc89f..5e20c17 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -100,8 +100,30 @@  subprocess.run(
         "--enable-tools",
         "--enable-bindings-glib",
         "--enable-introspection",
+        "--enable-tools",
     ],
     check=True,
 )
 subprocess.run(["make", "-j"], check=True)
 os.chdir(cwd)
+
+for page in [
+    "gpiodetect",
+    "gpioinfo",
+    "gpioget",
+    "gpioset",
+    "gpiomon",
+    "gpionotify",
+]:
+    subprocess.run(
+        [
+            "pandoc",
+            "--from=man",
+            "--to=rst",
+            "--standalone",
+            "--wrap=none",
+            f"--output={page}.rst",
+            f"../man/{page}.man",
+        ],
+        check=True,
+    )
diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst
new file mode 100644
index 0000000..7372de4
--- /dev/null
+++ b/docs/gpio_tools.rst
@@ -0,0 +1,25 @@ 
+..
+   SPDX-License-Identifier: CC-BY-SA-4.0
+   SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+   This file is part of libgpiod.
+
+   GPIO tools documentation
+
+Command-line tools
+==================
+
+The **libgpiod** project includes a suite of **command-line tools** to
+facilitate GPIO manipulation from console and shell scripts.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manual entries
+
+   gpiodetect<gpiodetect>
+   gpioinfo<gpioinfo>
+   gpioget<gpioget>
+   gpioset<gpioset>
+   gpiomon<gpiomon>
+   gpionotify<gpionotify>
diff --git a/docs/index.rst b/docs/index.rst
index 8dcea20..a52cc3a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -26,3 +26,4 @@  this interface.
 
    core_api
    bindings
+   gpio_tools