* [PATCH libgpiod v3 01/16] build: set PACKAGE_URL
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
@ 2025-02-06 12:21 ` Bartosz Golaszewski
2025-02-06 12:21 ` [PATCH libgpiod v3 02/16] bindings: cxx: doc: remove the gpiod_cxx doxygen group Bartosz Golaszewski
` (14 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:21 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
We don't set the package URL in AC_INIT() so the URL section in
pkgconfig files is empty. Set it to the address of the main git repo.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
configure.ac | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/configure.ac b/configure.ac
index 78a6670..34de870 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3,7 +3,8 @@
AC_PREREQ([2.71])
-AC_INIT([libgpiod], [2.3])
+AC_INIT([libgpiod], [2.3], [], [],
+ [https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/])
AC_SUBST(EXTRA_VERSION, [-devel])
AC_DEFINE_UNQUOTED([GPIOD_VERSION_STR],
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 02/16] bindings: cxx: doc: remove the gpiod_cxx doxygen group
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
2025-02-06 12:21 ` [PATCH libgpiod v3 01/16] build: set PACKAGE_URL Bartosz Golaszewski
@ 2025-02-06 12:21 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 03/16] bindings: python: doc: update the docstring for gpiod.request_lines() Bartosz Golaszewski
` (13 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:21 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Groups make sense for the C API as they allow us to nicely order
interfaces manipulating a given structure thematically but for C++ they
make less sense as methods are already typically part of a class.
Additionally for global functions, they seem to make it difficult for
breathe to look up the correct symbols.
Remove the gpiod_cxx group from Doxygen comments.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
bindings/cxx/gpiod.hpp | 6 ------
bindings/cxx/gpiodcxx/chip-info.hpp | 9 ---------
bindings/cxx/gpiodcxx/chip.hpp | 9 ---------
bindings/cxx/gpiodcxx/edge-event-buffer.hpp | 9 ---------
bindings/cxx/gpiodcxx/edge-event.hpp | 9 ---------
bindings/cxx/gpiodcxx/exception.hpp | 9 ---------
bindings/cxx/gpiodcxx/info-event.hpp | 9 ---------
bindings/cxx/gpiodcxx/line-config.hpp | 9 ---------
bindings/cxx/gpiodcxx/line-info.hpp | 9 ---------
bindings/cxx/gpiodcxx/line-request.hpp | 9 ---------
bindings/cxx/gpiodcxx/line-settings.hpp | 9 ---------
bindings/cxx/gpiodcxx/line.hpp | 9 ---------
bindings/cxx/gpiodcxx/misc.hpp | 9 ---------
bindings/cxx/gpiodcxx/request-builder.hpp | 9 ---------
bindings/cxx/gpiodcxx/request-config.hpp | 9 ---------
bindings/cxx/gpiodcxx/timestamp.hpp | 9 ---------
16 files changed, 141 deletions(-)
diff --git a/bindings/cxx/gpiod.hpp b/bindings/cxx/gpiod.hpp
index 91e41a5..606994d 100644
--- a/bindings/cxx/gpiod.hpp
+++ b/bindings/cxx/gpiod.hpp
@@ -8,12 +8,6 @@
#ifndef __LIBGPIOD_GPIOD_CXX_HPP__
#define __LIBGPIOD_GPIOD_CXX_HPP__
-/**
- * @defgroup gpiod_cxx C++ bindings
- *
- * C++ bindings for libgpiod.
- */
-
/**
* @cond
*/
diff --git a/bindings/cxx/gpiodcxx/chip-info.hpp b/bindings/cxx/gpiodcxx/chip-info.hpp
index e740e94..61c0b78 100644
--- a/bindings/cxx/gpiodcxx/chip-info.hpp
+++ b/bindings/cxx/gpiodcxx/chip-info.hpp
@@ -19,11 +19,6 @@ namespace gpiod {
class chip;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Represents an immutable snapshot of GPIO chip information.
*/
@@ -96,10 +91,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const chip_info& chip);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_CHIP_INFO_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/chip.hpp b/bindings/cxx/gpiodcxx/chip.hpp
index 4d67476..8a1389e 100644
--- a/bindings/cxx/gpiodcxx/chip.hpp
+++ b/bindings/cxx/gpiodcxx/chip.hpp
@@ -30,11 +30,6 @@ class line_request;
class request_builder;
class request_config;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Represents a GPIO chip.
*/
@@ -173,10 +168,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const chip& chip);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_CHIP_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/edge-event-buffer.hpp b/bindings/cxx/gpiodcxx/edge-event-buffer.hpp
index 2482e8a..083c2e1 100644
--- a/bindings/cxx/gpiodcxx/edge-event-buffer.hpp
+++ b/bindings/cxx/gpiodcxx/edge-event-buffer.hpp
@@ -22,11 +22,6 @@ namespace gpiod {
class edge_event;
class line_request;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Object into which edge events are read for better performance.
*
@@ -120,10 +115,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const edge_event_buffer& buf);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_EDGE_EVENT_BUFFER_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/edge-event.hpp b/bindings/cxx/gpiodcxx/edge-event.hpp
index 47c256a..acbe7af 100644
--- a/bindings/cxx/gpiodcxx/edge-event.hpp
+++ b/bindings/cxx/gpiodcxx/edge-event.hpp
@@ -22,11 +22,6 @@ namespace gpiod {
class edge_event_buffer;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Immutable object containing data about a single edge event.
*/
@@ -128,10 +123,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const edge_event& event);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_EDGE_EVENT_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/exception.hpp b/bindings/cxx/gpiodcxx/exception.hpp
index 34737d2..b753af0 100644
--- a/bindings/cxx/gpiodcxx/exception.hpp
+++ b/bindings/cxx/gpiodcxx/exception.hpp
@@ -17,11 +17,6 @@
namespace gpiod {
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Exception thrown when an already closed chip is used.
*/
@@ -149,10 +144,6 @@ public:
~bad_mapping();
};
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_EXCEPTION_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/info-event.hpp b/bindings/cxx/gpiodcxx/info-event.hpp
index 69b88b6..ee01651 100644
--- a/bindings/cxx/gpiodcxx/info-event.hpp
+++ b/bindings/cxx/gpiodcxx/info-event.hpp
@@ -23,11 +23,6 @@ namespace gpiod {
class chip;
class line_info;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Immutable object containing data about a single line info event.
*/
@@ -114,10 +109,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const info_event& event);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_INFO_EVENT_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/line-config.hpp b/bindings/cxx/gpiodcxx/line-config.hpp
index 58c9d87..b3b9aba 100644
--- a/bindings/cxx/gpiodcxx/line-config.hpp
+++ b/bindings/cxx/gpiodcxx/line-config.hpp
@@ -21,11 +21,6 @@ class chip;
class line_request;
class line_settings;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Contains a set of line config options used in line requests and
* reconfiguration.
@@ -111,10 +106,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const line_config& config);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_LINE_CONFIG_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/line-info.hpp b/bindings/cxx/gpiodcxx/line-info.hpp
index 8b10dc4..bf02ba1 100644
--- a/bindings/cxx/gpiodcxx/line-info.hpp
+++ b/bindings/cxx/gpiodcxx/line-info.hpp
@@ -22,11 +22,6 @@ namespace gpiod {
class chip;
class info_event;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Contains an immutable snapshot of the line's state at the
* time when the object of this class was instantiated.
@@ -167,10 +162,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const line_info& info);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_LINE_INFO_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/line-request.hpp b/bindings/cxx/gpiodcxx/line-request.hpp
index fcc4e0e..9605019 100644
--- a/bindings/cxx/gpiodcxx/line-request.hpp
+++ b/bindings/cxx/gpiodcxx/line-request.hpp
@@ -26,11 +26,6 @@ class edge_event;
class edge_event_buffer;
class line_config;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Stores the context of a set of requested GPIO lines.
*/
@@ -227,10 +222,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const line_request& request);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_LINE_REQUEST_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/line-settings.hpp b/bindings/cxx/gpiodcxx/line-settings.hpp
index 1004ccd..89d79f8 100644
--- a/bindings/cxx/gpiodcxx/line-settings.hpp
+++ b/bindings/cxx/gpiodcxx/line-settings.hpp
@@ -21,11 +21,6 @@ namespace gpiod {
class line_config;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Stores GPIO line settings.
*/
@@ -193,10 +188,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const line_settings& settings);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_LINE_SETTINGS_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/line.hpp b/bindings/cxx/gpiodcxx/line.hpp
index 2810571..c58bf11 100644
--- a/bindings/cxx/gpiodcxx/line.hpp
+++ b/bindings/cxx/gpiodcxx/line.hpp
@@ -23,11 +23,6 @@ namespace gpiod {
*/
namespace line {
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Wrapper around unsigned int for representing line offsets.
*/
@@ -265,10 +260,6 @@ using value_mappings = ::std::vector<value_mapping>;
*/
::std::ostream& operator<<(::std::ostream& out, const value_mappings& mappings);
-/**
- * @}
- */
-
} /* namespace line */
} /* namespace gpiod */
diff --git a/bindings/cxx/gpiodcxx/misc.hpp b/bindings/cxx/gpiodcxx/misc.hpp
index eab8eba..cb56b92 100644
--- a/bindings/cxx/gpiodcxx/misc.hpp
+++ b/bindings/cxx/gpiodcxx/misc.hpp
@@ -16,11 +16,6 @@
namespace gpiod {
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Check if the file pointed to by path is a GPIO chip character device.
* @param path Path to check.
@@ -35,10 +30,6 @@ bool is_gpiochip_device(const ::std::filesystem::path& path);
*/
const ::std::string& api_version();
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_MISC_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/request-builder.hpp b/bindings/cxx/gpiodcxx/request-builder.hpp
index 192bd91..62597b4 100644
--- a/bindings/cxx/gpiodcxx/request-builder.hpp
+++ b/bindings/cxx/gpiodcxx/request-builder.hpp
@@ -22,11 +22,6 @@ class line_config;
class line_request;
class request_config;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Intermediate object storing the configuration for a line request.
*/
@@ -148,10 +143,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const request_builder& builder);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_REQUEST_BUILDER_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/request-config.hpp b/bindings/cxx/gpiodcxx/request-config.hpp
index 6ebbf99..96f0262 100644
--- a/bindings/cxx/gpiodcxx/request-config.hpp
+++ b/bindings/cxx/gpiodcxx/request-config.hpp
@@ -23,11 +23,6 @@ namespace gpiod {
class chip;
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Stores a set of options passed to the kernel when making a line
* request.
@@ -105,10 +100,6 @@ private:
*/
::std::ostream& operator<<(::std::ostream& out, const request_config& config);
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_REQUEST_CONFIG_HPP__ */
diff --git a/bindings/cxx/gpiodcxx/timestamp.hpp b/bindings/cxx/gpiodcxx/timestamp.hpp
index fcb4d8d..dc44eb7 100644
--- a/bindings/cxx/gpiodcxx/timestamp.hpp
+++ b/bindings/cxx/gpiodcxx/timestamp.hpp
@@ -17,11 +17,6 @@
namespace gpiod {
-/**
- * @ingroup gpiod_cxx
- * @{
- */
-
/**
* @brief Stores the edge and info event timestamps as returned by the kernel
* and allows to convert them to std::chrono::time_point.
@@ -114,10 +109,6 @@ private:
::std::uint64_t _m_ns;
};
-/**
- * @}
- */
-
} /* namespace gpiod */
#endif /* __LIBGPIOD_CXX_TIMESTAMP_HPP__ */
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 03/16] bindings: python: doc: update the docstring for gpiod.request_lines()
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
2025-02-06 12:21 ` [PATCH libgpiod v3 01/16] build: set PACKAGE_URL Bartosz Golaszewski
2025-02-06 12:21 ` [PATCH libgpiod v3 02/16] bindings: cxx: doc: remove the gpiod_cxx doxygen group Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 04/16] bindings: python: doc: make code examples appear as such in sphinx Bartosz Golaszewski
` (12 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
The global request_lines() function was updated to take explicitly typed
arguments instead of just passing *args and **kwargs down to
Chip.request_lines(). However, the doc remained unchanged. Update it now
to reflect the actual function parameters.
Reviewed-by: Vincent Fazio <vfazio@xes-inc.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
bindings/python/gpiod/__init__.py | 15 ++++++++++++---
1 file changed, 12 insertions(+), 3 deletions(-)
diff --git a/bindings/python/gpiod/__init__.py b/bindings/python/gpiod/__init__.py
index 817c755..854e41f 100644
--- a/bindings/python/gpiod/__init__.py
+++ b/bindings/python/gpiod/__init__.py
@@ -99,9 +99,18 @@ def request_lines(
Args:
path
Path to the GPIO character device file.
- *args
- **kwargs
- See Chip.request_lines() for configuration arguments.
+ config:
+ Dictionary mapping offsets or names (or tuples thereof) to
+ LineSettings. If None is passed as the value of the mapping,
+ default settings are used.
+ consumer:
+ Consumer string to use for this request.
+ event_buffer_size:
+ Size of the kernel edge event buffer to configure for this request.
+ output_values:
+ Dictionary mapping offsets or names to line.Value. This can be used
+ to set the desired output values globally while reusing LineSettings
+ for more lines.
Returns:
Returns a new LineRequest object.
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 04/16] bindings: python: doc: make code examples appear as such in sphinx
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (2 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 03/16] bindings: python: doc: update the docstring for gpiod.request_lines() Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 05/16] bindings: python: doc: describe undocumented members Bartosz Golaszewski
` (11 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
In order for code examples inside docstrings to be interpreted as such
by sphinx, we need to use a double colon ("Example::").
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
bindings/python/gpiod/chip.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/bindings/python/gpiod/chip.py b/bindings/python/gpiod/chip.py
index ddd07b8..5641343 100644
--- a/bindings/python/gpiod/chip.py
+++ b/bindings/python/gpiod/chip.py
@@ -39,7 +39,7 @@ class Chip:
Callers must close the chip by calling the close() method when it's no longer
used.
- Example:
+ Example::
chip = gpiod.Chip(\"/dev/gpiochip0\")
do_something(chip)
@@ -47,7 +47,7 @@ class Chip:
The gpiod.Chip class also supports controlled execution ('with' statement).
- Example:
+ Example::
with gpiod.Chip(path="/dev/gpiochip0") as chip:
do_something(chip)
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 05/16] bindings: python: doc: describe undocumented members
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (3 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 04/16] bindings: python: doc: make code examples appear as such in sphinx Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 06/16] bindings: glib: add the configuration file for gi-docgen Bartosz Golaszewski
` (10 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
There are several public members in python bindings that are missing
docstrings. Document them for completeness.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
bindings/python/gpiod/chip_info.py | 5 +++++
bindings/python/gpiod/edge_event.py | 9 +++++++++
bindings/python/gpiod/info_event.py | 8 ++++++++
bindings/python/gpiod/line.py | 20 ++++++++++++++++++++
bindings/python/gpiod/line_info.py | 12 ++++++++++++
bindings/python/gpiod/line_settings.py | 8 ++++++++
6 files changed, 62 insertions(+)
diff --git a/bindings/python/gpiod/chip_info.py b/bindings/python/gpiod/chip_info.py
index 3306af2..737a45e 100644
--- a/bindings/python/gpiod/chip_info.py
+++ b/bindings/python/gpiod/chip_info.py
@@ -14,8 +14,13 @@ class ChipInfo:
"""
name: str
+ """Name of the chip."""
+
label: str
+ """Label of the chip."""
+
num_lines: int
+ """Number of lines exposed by the chip."""
def __str__(self) -> str:
return f'<ChipInfo name="{self.name}" label="{self.label}" num_lines={self.num_lines}>'
diff --git a/bindings/python/gpiod/edge_event.py b/bindings/python/gpiod/edge_event.py
index 7f5cd4d..c888cb2 100644
--- a/bindings/python/gpiod/edge_event.py
+++ b/bindings/python/gpiod/edge_event.py
@@ -16,14 +16,23 @@ class EdgeEvent:
"""
class Type(Enum):
+ """Possible edge event types."""
+
RISING_EDGE = _ext.EDGE_EVENT_TYPE_RISING
+ """Rising edge event."""
FALLING_EDGE = _ext.EDGE_EVENT_TYPE_FALLING
+ """Falling edge event."""
event_type: Type
+ """Edge event type."""
timestamp_ns: int
+ """Timestamp of the event in nanoseconds."""
line_offset: int
+ """Offset of the line on which this event was registered."""
global_seqno: int
+ """Global sequence number of this event."""
line_seqno: int
+ """Event sequence number specific to the concerned line."""
def __init__(
self,
diff --git a/bindings/python/gpiod/info_event.py b/bindings/python/gpiod/info_event.py
index 4a86697..cd2785e 100644
--- a/bindings/python/gpiod/info_event.py
+++ b/bindings/python/gpiod/info_event.py
@@ -17,13 +17,21 @@ class InfoEvent:
"""
class Type(Enum):
+ """Line status change event types."""
+
LINE_REQUESTED = _ext.INFO_EVENT_TYPE_LINE_REQUESTED
+ """Line has been requested."""
LINE_RELEASED = _ext.INFO_EVENT_TYPE_LINE_RELEASED
+ """Previously requested line has been released."""
LINE_CONFIG_CHANGED = _ext.INFO_EVENT_TYPE_LINE_CONFIG_CHANGED
+ """Line configuration has changed."""
event_type: Type
+ """Event type of the status change event."""
timestamp_ns: int
+ """Timestamp of the event."""
line_info: LineInfo
+ """Snapshot of line-info associated with the event."""
def __init__(self, event_type: int, timestamp_ns: int, line_info: LineInfo):
object.__setattr__(self, "event_type", InfoEvent.Type(event_type))
diff --git a/bindings/python/gpiod/line.py b/bindings/python/gpiod/line.py
index 33c7368..0cfc854 100644
--- a/bindings/python/gpiod/line.py
+++ b/bindings/python/gpiod/line.py
@@ -13,7 +13,9 @@ class Value(Enum):
"""Logical line states."""
INACTIVE = _ext.VALUE_INACTIVE
+ """Line is logically inactive."""
ACTIVE = _ext.VALUE_ACTIVE
+ """Line is logically active."""
def __bool__(self) -> bool:
return self == self.ACTIVE
@@ -23,40 +25,58 @@ class Direction(Enum):
"""Direction settings."""
AS_IS = _ext.DIRECTION_AS_IS
+ """Request the line(s), but don't change direction."""
INPUT = _ext.DIRECTION_INPUT
+ """Direction is input - for reading the value of an externally driven GPIO line."""
OUTPUT = _ext.DIRECTION_OUTPUT
+ """Direction is output - for driving the GPIO line."""
class Bias(Enum):
"""Internal bias settings."""
AS_IS = _ext.BIAS_AS_IS
+ """Don't change the bias setting when applying line config."""
UNKNOWN = _ext.BIAS_UNKNOWN
+ """The internal bias state is unknown."""
DISABLED = _ext.BIAS_DISABLED
+ """The internal bias is disabled."""
PULL_UP = _ext.BIAS_PULL_UP
+ """The internal pull-up bias is enabled."""
PULL_DOWN = _ext.BIAS_PULL_DOWN
+ """The internal pull-down bias is enabled."""
class Drive(Enum):
"""Drive settings."""
PUSH_PULL = _ext.DRIVE_PUSH_PULL
+ """Drive setting is push-pull."""
OPEN_DRAIN = _ext.DRIVE_OPEN_DRAIN
+ """Line output is open-drain."""
OPEN_SOURCE = _ext.DRIVE_OPEN_SOURCE
+ """Line output is open-source."""
class Edge(Enum):
"""Edge detection settings."""
NONE = _ext.EDGE_NONE
+ """Line edge detection is disabled."""
RISING = _ext.EDGE_RISING
+ """Line detects rising edge events."""
FALLING = _ext.EDGE_FALLING
+ """Line detects falling edge events."""
BOTH = _ext.EDGE_BOTH
+ """Line detects both rising and falling edge events."""
class Clock(Enum):
"""Event clock settings."""
MONOTONIC = _ext.CLOCK_MONOTONIC
+ """Line uses the monotonic clock for edge event timestamps."""
REALTIME = _ext.CLOCK_REALTIME
+ """Line uses the realtime clock for edge event timestamps."""
HTE = _ext.CLOCK_HTE
+ """Line uses the hardware timestamp engine for event timestamps."""
diff --git a/bindings/python/gpiod/line_info.py b/bindings/python/gpiod/line_info.py
index 1aca142..d31565e 100644
--- a/bindings/python/gpiod/line_info.py
+++ b/bindings/python/gpiod/line_info.py
@@ -16,17 +16,29 @@ class LineInfo:
"""
offset: int
+ """Offset of the line."""
name: str
+ """Name of the line."""
used: bool
+ """Indicates whether line is in use."""
consumer: str
+ """Name of the consumer of the line."""
direction: Direction
+ """Direction setting of the line."""
active_low: bool
+ """Active-low setting of the line."""
bias: Bias
+ """Bias setting of the line."""
drive: Drive
+ """Drive setting of the line."""
edge_detection: Edge
+ """Edge detection setting of the line."""
event_clock: Clock
+ """Event clock setting used for edge event timestamps for the line."""
debounced: bool
+ """Indicates whether line is debounced."""
debounce_period: timedelta
+ """Debounce period of the line."""
def __init__(
self,
diff --git a/bindings/python/gpiod/line_settings.py b/bindings/python/gpiod/line_settings.py
index 2aca71c..3752acd 100644
--- a/bindings/python/gpiod/line_settings.py
+++ b/bindings/python/gpiod/line_settings.py
@@ -17,13 +17,21 @@ class LineSettings:
"""
direction: Direction = Direction.AS_IS
+ """Line direction."""
edge_detection: Edge = Edge.NONE
+ """Edge detection setting."""
bias: Bias = Bias.AS_IS
+ """Line bias setting."""
drive: Drive = Drive.PUSH_PULL
+ """Line drive setting."""
active_low: bool = False
+ """Active-low switch."""
debounce_period: timedelta = timedelta()
+ """Debounce period of the line."""
event_clock: Clock = Clock.MONOTONIC
+ """Edge event timestamping clock setting."""
output_value: Value = Value.INACTIVE
+ """Output value of the line."""
# __repr__ generated by @dataclass uses repr for enum members resulting in
# an unusable representation as those are of the form: <NAME: $value>
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 06/16] bindings: glib: add the configuration file for gi-docgen
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (4 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 05/16] bindings: python: doc: describe undocumented members Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 07/16] dbus: daemon: add a more detailed description to help text Bartosz Golaszewski
` (9 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Without the gi-docgen configuration file, the GObject docs don't
contain information such as library version, author, license, etc. Add a
simple .toml to add missing bits and update the command in Makefile.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
bindings/glib/.gitignore | 1 +
bindings/glib/Makefile.am | 6 ++++--
bindings/glib/gi-docgen.toml.in | 9 +++++++++
configure.ac | 1 +
4 files changed, 15 insertions(+), 2 deletions(-)
diff --git a/bindings/glib/.gitignore b/bindings/glib/.gitignore
index aa399b8..5d6fe20 100644
--- a/bindings/glib/.gitignore
+++ b/bindings/glib/.gitignore
@@ -4,3 +4,4 @@
*.gir
*.typelib
Gpiodglib-1.0
+gi-docgen.toml
diff --git a/bindings/glib/Makefile.am b/bindings/glib/Makefile.am
index 6ecef94..f0241e8 100644
--- a/bindings/glib/Makefile.am
+++ b/bindings/glib/Makefile.am
@@ -124,8 +124,10 @@ endif
if HAS_GI_DOCGEN
-doc: Gpiodglib-1.0.gir
- $(AM_V_GEN)gi-docgen generate Gpiodglib-1.0.gir
+doc: Gpiodglib-1.0.gir gi-docgen.toml
+ $(AM_V_GEN)gi-docgen generate --config gi-docgen.toml Gpiodglib-1.0.gir
.PHONY: doc
+EXTRA_DIST += gi-docgen.toml
+
endif
diff --git a/bindings/glib/gi-docgen.toml.in b/bindings/glib/gi-docgen.toml.in
new file mode 100644
index 0000000..5550a31
--- /dev/null
+++ b/bindings/glib/gi-docgen.toml.in
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+[library]
+description = "GObject bindings to libgpiod"
+version = "@PACKAGE_VERSION@"
+authors = "Bartosz Golaszewski"
+license = "LGPL-2.1-or-later"
+website_url = "@PACKAGE_URL@"
diff --git a/configure.ac b/configure.ac
index 34de870..5a7e01c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -307,6 +307,7 @@ then
fi
fi
AM_CONDITIONAL([HAS_GI_DOCGEN], [test "x$has_gi_docgen" = xtrue])
+AM_COND_IF([HAS_GI_DOCGEN], [AC_CONFIG_FILES([bindings/glib/gi-docgen.toml])])
# GObject-introspection
found_introspection=no
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 07/16] dbus: daemon: add a more detailed description to help text
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (5 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 06/16] bindings: glib: add the configuration file for gi-docgen Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 08/16] dbus: client: tweak " Bartosz Golaszewski
` (8 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
In preparation for adding man pages for the daemon and the command-line
client, add a detailed description of what gpio-manager is and does to
the output presented to user when they pass --help as argument.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
dbus/manager/gpio-manager.c | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/dbus/manager/gpio-manager.c b/dbus/manager/gpio-manager.c
index d34c7ea..03ca7ab 100644
--- a/dbus/manager/gpio-manager.c
+++ b/dbus/manager/gpio-manager.c
@@ -85,6 +85,14 @@ static void print_version_and_exit(void)
static void parse_opts(int argc, char **argv)
{
+ static const char *const description =
+"The gpio-manager is the reference implementation of the GPIO D-Bus API\n"
+"built on top of libgpiod. It serves as the central authority managing GPIO\n"
+"chips and lines, exposing their functionalities to other applications\n"
+"through the D-Bus interface. It supports operations such as requesting,\n"
+"releasing, and setting line values, as well as monitoring events like rising\n"
+"or falling edges and line property changes.";
+
gboolean ret, opt_debug = FALSE, opt_version = FALSE;
g_autoptr(GOptionContext) ctx = NULL;
g_auto(GStrv) remaining = NULL;
@@ -118,6 +126,7 @@ static void parse_opts(int argc, char **argv)
ctx = g_option_context_new(NULL);
g_option_context_set_summary(ctx, "D-Bus daemon managing GPIOs.");
+ g_option_context_set_description(ctx, description);
g_option_context_add_main_entries(ctx, opts, NULL);
ret = g_option_context_parse(ctx, &argc, &argv, &err);
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 08/16] dbus: client: tweak help text
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (6 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 07/16] dbus: daemon: add a more detailed description to help text Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 09/16] dbus: improve comments in API xml Bartosz Golaszewski
` (7 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
help2man struggles to generate correct output with current help-text for
the sub-commands section. It doesn't break the lines correctly and the
resulting .rst generated with pandoc looks just as bad. Tweak the output
a bit to generate better man pages with correctly broken lines.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
dbus/client/gpiocli.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/dbus/client/gpiocli.c b/dbus/client/gpiocli.c
index e9ab380..26d641b 100644
--- a/dbus/client/gpiocli.c
+++ b/dbus/client/gpiocli.c
@@ -107,7 +107,7 @@ static gchar *make_description(void)
const GPIOCliCmd *cmd;
for (cmd = &cli_cmds[0]; cmd->name; cmd++)
- g_string_append_printf(descr, " %s - %s\n",
+ g_string_append_printf(descr, " - %s:\n\t%s\n",
cmd->name, cmd->descr);
g_string_truncate(descr, descr->len - 1);
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 09/16] dbus: improve comments in API xml
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (7 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 08/16] dbus: client: tweak " Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 10/16] doc: create man entries for gpio-manager and gpiocli Bartosz Golaszewski
` (6 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
The current comments don't follow any particular formatting so the
resulting .rst generated with gdbus-codegen is all mangled up. Use
proper .rst formatting to make docs better.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
dbus/lib/io.gpiod1.xml | 98 ++++++++++++++++++++++++++------------------------
1 file changed, 52 insertions(+), 46 deletions(-)
diff --git a/dbus/lib/io.gpiod1.xml b/dbus/lib/io.gpiod1.xml
index ace7d72..411ea6e 100644
--- a/dbus/lib/io.gpiod1.xml
+++ b/dbus/lib/io.gpiod1.xml
@@ -1,5 +1,5 @@
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
-<!-- SPDX-FileCopyrightText: 2022-2024 Bartosz Golaszewski <bartosz.golaszewski@linaro.org> -->
+<!-- SPDX-FileCopyrightText: 2022-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org> -->
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
@@ -54,58 +54,60 @@
contains the list of default output values which are only used in output
mode.
- Available line config options:
+ **Available line config options:**
- "direction" => String representing the line direction. Accepts the
- following values: "input", "output".
- "edge" => String representing the edge detection setting. Accepts the
- following values: "falling", "rising", "both".
- "active-low" => Boolean representing the active-low setting.
- "drive" => String representing the drive settings. Accepts the
- following values: "push-pull", "open-drain", "open-source".
- "bias" => String representing the internal bias settings. Accepts the
- following values: "disabled", "pull-up", "pull-down", "as-is".
- "debounce-period" => Debounce period in microseconds represented as a
- signed, 64-bit integer.
- "event-clock" => String representing the clock used to timestamp edge
- events. Accepts the following values: "monotonic",
- "realtime", "hte".
+ - **"direction"**: String representing the line direction.
+ Accepts the following values: "input", "output".
+ - **"edge"**: String representing the edge detection setting.
+ Accepts the following values: "falling", "rising", "both".
+ - **"active-low"**: Boolean representing the active-low setting.
+ - **"drive"**: String representing the drive settings.
+ Accepts the following values: "push-pull", "open-drain", "open-source".
+ - **"bias"**: String representing the internal bias settings.
+ Accepts the following values: "disabled", "pull-up", "pull-down", "as-is".
+ - **"debounce-period"**: Debounce period in microseconds, represented as a
+ signed 64-bit integer.
+ - **"event-clock"**: String representing the clock used to timestamp edge
+ events.
+ Accepts the following values: "monotonic", "realtime", "hte".
Output values are applied to the lines in the order they appear in the
settings mappings.
- Example variant that allows to request lines at offsets 1, 5 and 11 in
- output, push-pull and active-low modes and specifies the output values
- as active (as visualized with g_variant_print()):
+ **Example variant** that allows requesting lines at offsets 1, 5, and 11
+ in output, push-pull, and active-low modes, and specifies the output
+ values as active (as visualized with `g_variant_print()`):
- // Line config tuple
- (
- // Array of line settings mappings
- [
- // Single mapping tuple
- (
- // Offsets to map
- [1, 5, 11],
- // Line settings dict
- {
- 'direction': <'output'>,
- 'drive': <'push-pull'>,
- 'active-low': <true>
- }
- )
- ],
- // Output values
- [1, 1, 1]
- )
+ .. code-block:: none
+
+ // Line config tuple
+ (
+ // Array of line settings mappings
+ [
+ // Single mapping tuple
+ (
+ // Offsets to map
+ [1, 5, 11],
+ // Line settings dict
+ {
+ 'direction': <'output'>,
+ 'drive': <'push-pull'>,
+ 'active-low': <true>
+ }
+ )
+ ],
+ // Output values
+ [1, 1, 1]
+ )
Request configuration is a hashmap mapping names of the available config
options to their values wrapped in a variant.
- Available request config options:
+ **Available request config options:**
- "consumer" => Consumer name as a string
- "event-buffer-size" => Requested size of the in-kernel edge event
- buffer as an unsigned 32-bit integer.
+ - **"consumer"**: Consumer name as a string.
+ - **"event-buffer-size"**: Requested size of the in-kernel edge event buffer,
+ as an unsigned 32-bit integer.
The object path to the new request is returned on success. The user
should wait for it to appear before trying to use the requested lines in
@@ -239,8 +241,7 @@
<!--
EdgeEvent:
- @event_data: Contains the edge (1 for rising, 0 for falling), timestamp
- in nanoseconds and the global & line-local sequence numbers.
+ @event_data: Edge, timestamp and the global & line-local sequence numbers.
If the line is managed by the gpio-manager and is requested with edge
detection enabled then this signal will be emitted for every edge event
@@ -249,6 +250,9 @@
D-Bus EdgeEvent signals are designed for low-to-medium frequency
interrupts. If you performance better than the order of tens of HZ, you
should probably access the line directly using the kernel uAPI.
+
+ The edge contains 1 for rising and 0 for falling. The timestamp is
+ expressed in nanoseconds.
-->
<signal name='EdgeEvent'>
<arg name='event_data' type='(ittt)'/>
@@ -287,11 +291,13 @@
<!--
ReconfigureLines:
- @line_config: Line configuration. Refer to the RequestLines method of
- the io.gpiod1.Chip interface for details.
+ @line_config: Line configuration.
Change the configuration of lines held by this request object without
releasing them.
+
+ Refer to the RequestLines method of the io.gpiod1.Chip interface for
+ details on line configuration.
-->
<method name='ReconfigureLines'>
<arg name='line_config' direction='in' type='(a(aua{sv})ai)'/>
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 10/16] doc: create man entries for gpio-manager and gpiocli
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (8 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 09/16] dbus: improve comments in API xml Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings Bartosz Golaszewski
` (5 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Extend the build files under man/ to also generate man pages for
gpio-manager, gpiocli and each of the former's sub-commands.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
Makefile.am | 8 ++++++-
man/Makefile.am | 72 +++++++++++++++++++++++++++++++++++++++++++++++----------
2 files changed, 67 insertions(+), 13 deletions(-)
diff --git a/Makefile.am b/Makefile.am
index c824dc4..d310e17 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -24,7 +24,7 @@ endif
if WITH_TOOLS
-SUBDIRS += tools man
+SUBDIRS += tools
endif
@@ -44,6 +44,12 @@ SUBDIRS += dbus
endif
+if WITH_MANPAGES
+
+SUBDIRS += man
+
+endif
+
if HAS_DOXYGEN
doc: Doxyfile
diff --git a/man/Makefile.am b/man/Makefile.am
index ddd0628..8d8bc46 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,22 +1,70 @@
# SPDX-License-Identifier: GPL-2.0-or-later
# SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <bartekgola@gmail.com>
+# SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
-if WITH_MANPAGES
+MAN_ENTRIES =
+MAN_DEPS =
-dist_man1_MANS = \
- gpiodetect.man \
- gpioinfo.man \
- gpioget.man \
- gpioset.man \
- gpiomon.man \
- gpionotify.man
+if WITH_TOOLS
-%.man: $(top_builddir)/tools/$(*F)
- $(AM_V_GEN)help2man $(top_builddir)/tools/$(*F) --include=$(srcdir)/template --output=$(builddir)/$@ --no-info
+TOOLS = \
+ gpiodetect \
+ gpioinfo \
+ gpioget \
+ gpioset \
+ gpiomon \
+ gpionotify
+
+MAN_ENTRIES += $(TOOLS)
+MAN_DEPS += $(foreach dep,$(TOOLS),$(top_builddir)/tools/$(dep))
+
+endif
+
+if WITH_DBUS
+
+GPIOCLI_CMDS = \
+ detect \
+ find \
+ info \
+ get \
+ monitor \
+ notify \
+ reconfigure \
+ release \
+ request \
+ requests \
+ set \
+ wait
+
+MAN_ENTRIES += \
+ gpio-manager \
+ gpiocli \
+ $(foreach cmd,$(GPIOCLI_CMDS),gpiocli-$(cmd))
+
+MAN_DEPS += \
+ $(top_builddir)/dbus/manager/gpio-manager
+ $(top_builddir)/dbus/client/gpiocli
+
+endif
+
+dist_man1_MANS := $(foreach entry,$(MAN_ENTRIES),$(entry).man)
+
+%.man: $(MAN_DEPS)
+ $(AM_V_GEN)export PATH=$(top_builddir)/dbus/manager/:$(top_builddir)/dbus/client/:$(top_builddir)/tools/:$$PATH; \
+ if [ "$(*F)" = "gpio-manager" ]; then \
+ EXEC=$(*F); \
+ NAME="libgpiod D-Bus daemon"; \
+ HELP=--help-option=--help; \
+ else \
+ EXEC=$(if $(findstring -,$(*F)),$(word 1,$(subst -, ,$(*F))),$(*F)); \
+ NAME=$(if $(findstring -,$(*F)),$(word 2,$(subst -, ,$(*F))),"libgpiod command-line utility"); \
+ HELP=$(if $(findstring -,$(*F)),--help-option="$(word 2,$(subst -, ,$(*F))) --help",--help-option=--help); \
+ fi; \
+ help2man $$EXEC \
+ --include=$(srcdir)/template --output=$(builddir)/$@ --no-info \
+ --name="$$NAME" "$$HELP" --manual=$(*F)
clean-local:
rm -f $(dist_man1_MANS)
-endif
-
EXTRA_DIST = template
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (9 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 10/16] doc: create man entries for gpio-manager and gpiocli Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-10 14:53 ` [External] - " Vincent Fazio
2025-02-06 12:22 ` [PATCH libgpiod v3 12/16] doc: add documentation for python bindings Bartosz Golaszewski
` (4 subsequent siblings)
15 siblings, 1 reply; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Current sphinx/ contents are mostly WiP. Let's beat them into shape for
publishing on ReadTheDocs.
Integrate the API documentation generated with doxygen for the core C
API and C++ bindings into sphinx using breathe.
Update configure.ac to check for sphinx-build in addition to doxygen and
make the main Makefile trigger a sphinx build on `make doc` (although
the docs can also be generated without starting the build system by
running: `sphinx-build ./doc/ doc/sphinx-output`).
Move the introduction text from the main header into the relevant .rst
file.
Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where
all the documentation now lives.
Update .gitignore where needed.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
.gitignore | 2 -
.readthedocs.yaml | 16 +++----
Doxyfile.in | 105 -----------------------------------------
Makefile.am | 12 ++---
README | 12 ++---
configure.ac | 9 +++-
docs/.gitignore | 5 ++
docs/Doxyfile | 12 +++++
docs/Makefile.am | 45 ++++++++++++++++++
docs/bindings.rst | 20 ++++++++
docs/conf.py | 53 +++++++++++++++++++++
docs/core_api.rst | 62 ++++++++++++++++++++++++
docs/core_chip_info.rst | 11 +++++
docs/core_chips.rst | 11 +++++
docs/core_edge_event.rst | 11 +++++
docs/core_line_config.rst | 11 +++++
docs/core_line_defs.rst | 11 +++++
docs/core_line_info.rst | 11 +++++
docs/core_line_request.rst | 11 +++++
docs/core_line_settings.rst | 11 +++++
docs/core_line_watch.rst | 11 +++++
docs/core_misc.rst | 11 +++++
docs/core_request_config.rst | 11 +++++
docs/cpp_api.rst | 34 +++++++++++++
docs/cpp_chip.rst | 12 +++++
docs/cpp_chip_info.rst | 12 +++++
docs/cpp_edge_event.rst | 12 +++++
docs/cpp_edge_event_buffer.rst | 12 +++++
docs/cpp_exceptions.rst | 18 +++++++
docs/cpp_info_event.rst | 12 +++++
docs/cpp_line.rst | 24 ++++++++++
docs/cpp_line_config.rst | 12 +++++
docs/cpp_line_info.rst | 12 +++++
docs/cpp_line_request.rst | 15 ++++++
docs/cpp_line_settings.rst | 12 +++++
docs/cpp_misc.rst | 16 +++++++
docs/cpp_request_config.rst | 12 +++++
docs/index.rst | 28 +++++++++++
docs/requirements.txt | 5 ++
include/gpiod.h | 36 --------------
sphinx/conf.py | 68 --------------------------
sphinx/contents.rst | 24 ----------
42 files changed, 590 insertions(+), 260 deletions(-)
diff --git a/.gitignore b/.gitignore
index c3a29d8..7b5fa15 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,6 @@
*.la
generated-*.c
generated-*.h
-doc
*.pc
*.tar.gz
*.patch
@@ -16,7 +15,6 @@ tags
# autotools stuff
.deps/
.libs/
-Doxyfile
Makefile
Makefile.in
aclocal.m4
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index f40e95f..510b5c1 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,5 +1,6 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# SPDX-FileCopyrightText: 2022 Kent Gibson <warthog618@gmail.com>
+# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
#
# This file is part of libgpiod.
@@ -12,16 +13,15 @@ version: 2
build:
os: ubuntu-22.04
tools:
- python: "3.11"
- # doxygen is available by default, but just in case.
- # others are definitely missing.
+ python: "3.12"
apt_packages:
- - autoconf
- - autoconf-archive
- - libtool
- - m4
+ # doxygen is available by default, but just in case.
- doxygen
- graphviz
sphinx:
- configuration: sphinx/conf.py
+ configuration: docs/conf.py
+
+python:
+ install:
+ - requirements: docs/requirements.txt
diff --git a/Doxyfile.in b/Doxyfile.in
deleted file mode 100644
index 9c85e21..0000000
--- a/Doxyfile.in
+++ /dev/null
@@ -1,105 +0,0 @@
-# SPDX-License-Identifier: GPL-2.0-or-later
-# SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <bartekgola@gmail.com>
-
-# libgpiod doxygen configuration
-
-# General configuration
-PROJECT_NAME = libgpiod
-PROJECT_NUMBER = @VERSION_STR@
-OUTPUT_DIRECTORY = doc
-OUTPUT_LANGUAGE = English
-EXTRACT_ALL = NO
-EXTRACT_PRIVATE = NO
-EXTRACT_STATIC = YES
-HIDE_UNDOC_MEMBERS = NO
-HIDE_UNDOC_CLASSES = NO
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = YES
-ALWAYS_DETAILED_SEC = NO
-FULL_PATH_NAMES = NO
-STRIP_FROM_PATH = @top_srcdir@
-INTERNAL_DOCS = NO
-STRIP_CODE_COMMENTS = YES
-CASE_SENSE_NAMES = YES
-SHORT_NAMES = NO
-HIDE_SCOPE_NAMES = NO
-VERBATIM_HEADERS = YES
-SHOW_INCLUDE_FILES = YES
-JAVADOC_AUTOBRIEF = YES
-INHERIT_DOCS = YES
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = YES
-DISTRIBUTE_GROUP_DOC = NO
-TAB_SIZE = 8
-GENERATE_TODOLIST = YES
-GENERATE_TESTLIST = YES
-GENERATE_BUGLIST = YES
-ALIASES =
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-OPTIMIZE_OUTPUT_FOR_C = YES
-SHOW_USED_FILES = YES
-QUIET = YES
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_FORMAT =
-WARN_LOGFILE =
-INPUT = @top_srcdir@/include/gpiod.h \
- @top_srcdir@/bindings/cxx/gpiod.hpp \
- @top_srcdir@/bindings/cxx/gpiodcxx/
-SOURCE_BROWSER = YES
-INLINE_SOURCES = NO
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION = YES
-ALPHABETICAL_INDEX = NO
-IGNORE_PREFIX =
-SEARCHENGINE = NO
-ENABLE_PREPROCESSING = YES
-
-# HTML output
-GENERATE_HTML = YES
-HTML_OUTPUT =
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-GENERATE_HTMLHELP = NO
-GENERATE_CHI = NO
-BINARY_TOC = NO
-TOC_EXPAND = NO
-DISABLE_INDEX = NO
-ENUM_VALUES_PER_LINE = 4
-GENERATE_TREEVIEW = NO
-TREEVIEW_WIDTH = 250
-
-# LaTeX output
-GENERATE_LATEX = NO
-LATEX_OUTPUT =
-COMPACT_LATEX = NO
-PAPER_TYPE = a4
-EXTRA_PACKAGES =
-LATEX_HEADER =
-PDF_HYPERLINKS = NO
-USE_PDFLATEX = NO
-LATEX_BATCHMODE = NO
-
-# RTF output
-GENERATE_RTF = NO
-RTF_OUTPUT =
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-
-# Man page output
-GENERATE_MAN = YES
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_LINKS = YES
-
-# XML output
-GENERATE_XML = YES
-
-# External references
-TAGFILES =
-GENERATE_TAGFILE =
-ALLEXTERNALS = NO
diff --git a/Makefile.am b/Makefile.am
index d310e17..ae58605 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -50,15 +50,11 @@ SUBDIRS += man
endif
-if HAS_DOXYGEN
+if WITH_DOCS
-doc: Doxyfile
- $(AM_V_GEN)doxygen Doxyfile
-.PHONY: doc
+docs:
+ $(MAKE) -C docs docs
-clean-local:
- rm -rf doc
-
-EXTRA_DIST += Doxyfile
+.PHONY: docs
endif
diff --git a/README b/README
index 80ad939..28a3dfd 100644
--- a/README
+++ b/README
@@ -333,14 +333,12 @@ bindings use the standard tests module layout and the #[test] attribute.
DOCUMENTATION
-------------
-All API symbols exposed by the core C API and C++ bindings are documented with
-doxygen markup blocks. Doxygen documentation can be generated by executing
-'make doc' given that the doxygen executable is available in the system.
+The project uses sphinx to automatically generate the documentation. The system
+needs to provide doxygen and sphinx-build programs. With those in place, the
+build can be invoked with 'make docs'. This generates documentation for the
+core C API as well as C++ and python bindings.
-Python bindings contain help strings that can be accessed with the help
-builtin.
-
-Rust bindings use rustdoc.
+Rust bindings use rustdoc, GLib bindings use gi-docgen.
Man pages for command-line programs are generated automatically if gpio-tools
were selected and help2man is available in the system.
diff --git a/configure.ac b/configure.ac
index 5a7e01c..8eec855 100644
--- a/configure.ac
+++ b/configure.ac
@@ -328,12 +328,16 @@ then
fi
AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false])
-AM_CONDITIONAL([HAS_DOXYGEN], [test "x$has_doxygen" = xtrue])
+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
-AM_COND_IF([HAS_DOXYGEN], [AC_CONFIG_FILES([Doxyfile])])
+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
@@ -350,6 +354,7 @@ AC_CONFIG_FILES([Makefile
lib/Makefile
lib/libgpiod.pc
contrib/Makefile
+ docs/Makefile
examples/Makefile
tools/Makefile
tests/Makefile
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..86f8cfd
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+doxygen-output
+sphinx-output
diff --git a/docs/Doxyfile b/docs/Doxyfile
new file mode 100644
index 0000000..8c5b5df
--- /dev/null
+++ b/docs/Doxyfile
@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: CC-BY-SA-4.0
+# SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+PROJECT_NAME = libgpiod
+OUTPUT_DIRECTORY = doxygen-output
+INPUT = ../include/gpiod.h \
+ ../bindings/cxx/gpiod.hpp \
+ ../bindings/cxx/gpiodcxx/
+GENERATE_XML = YES
+WARN_IF_UNDOCUMENTED = YES
+QUIET = YES
+EXTRACT_ALL = YES
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..b8cf010
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+DOCS_DEPS = \
+ bindings.rst \
+ conf.py \
+ core_api.rst \
+ core_chip_info.rst \
+ core_chips.rst \
+ core_edge_event.rst \
+ core_line_config.rst \
+ core_line_defs.rst \
+ core_line_info.rst \
+ core_line_request.rst \
+ core_line_settings.rst \
+ core_line_watch.rst \
+ core_misc.rst \
+ core_request_config.rst \
+ cpp_api.rst \
+ cpp_chip_info.rst \
+ cpp_chip.rst \
+ cpp_edge_event_buffer.rst \
+ cpp_edge_event.rst \
+ cpp_exceptions.rst \
+ cpp_info_event.rst \
+ cpp_line_config.rst \
+ cpp_line_info.rst \
+ cpp_line_request.rst \
+ cpp_line.rst \
+ cpp_line_settings.rst \
+ cpp_misc.rst \
+ cpp_request_config.rst \
+ Doxyfile \
+ index.rst
+
+docs: $(DOCS_DEPS)
+ sphinx-build ./ ./sphinx-output
+
+.PHONY: docs
+
+clean-local:
+ rm -rf docs/sphinx-output
+ rm -rf docs/doxygen-output
+
+EXTRA_DIST = $(DOCS_DEPS) requirements.txt
diff --git a/docs/bindings.rst b/docs/bindings.rst
new file mode 100644
index 0000000..069fc8f
--- /dev/null
+++ b/docs/bindings.rst
@@ -0,0 +1,20 @@
+..
+ 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 high-level language bindings
+
+High-level language bindings to libgpiod
+========================================
+
+The bindings provide a more straightforward interface to the base, low-level
+C library.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ cpp_api
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..04c8c3b
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+# This file is part of libgpiod.
+#
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import re
+import subprocess
+import sys
+
+project = "libgpiod"
+copyright = "2017-2025, Bartosz Golaszewski"
+author = "Bartosz Golaszewski"
+
+master_doc = "index"
+source_suffix = ".rst"
+
+# Extract the full version from configure.ac (including -devel, -rc and other
+# tags).
+with open("../configure.ac", "r") as fd:
+ version = ""
+ extra = ""
+ for line in fd.readlines():
+ match = re.search(r"AC_INIT\(\[libgpiod\], \[(.*?)\]\)", line)
+ if match:
+ version = match.group(1)
+ continue
+
+ match = re.search(r"AC_SUBST\(EXTRA_VERSION, \[(.*?)\]\)", line)
+ if match:
+ extra = match.group(1)
+
+ release = f"{version}{extra}"
+
+extensions = ["breathe"]
+
+breathe_projects = {"libgpiod": "./doxygen-output/xml"}
+breathe_default_project = "libgpiod"
+
+# Use the RTD theme if available
+sphinx_rtd_theme = None
+try:
+ import sphinx_rtd_theme
+
+ extensions.append("sphinx_rtd_theme")
+except ImportError:
+ pass
+
+html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
+
+subprocess.run(["doxygen", "Doxyfile"])
diff --git a/docs/core_api.rst b/docs/core_api.rst
new file mode 100644
index 0000000..9424fcd
--- /dev/null
+++ b/docs/core_api.rst
@@ -0,0 +1,62 @@
+..
+ 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 core API documentation
+
+libgpiod core API
+=================
+
+This is the complete documentation of the public API made available to users of
+**libgpiod**.
+
+The API is logically split into several sections. For each opaque data class,
+there's a set of functions for manipulating it. Together they can be thought
+of as objects and their methods in OOP parlance.
+
+.. note::
+ General note on error handling: all functions exported by libgpiod that can
+ fail, set errno to one of the error values defined in errno.h upon failure.
+ The way of notifying the caller that an error occurred varies between
+ functions, but in general a function that returns an ``int``, returns ``-1``
+ on error, while a function returning a pointer indicates an error condition
+ by returning a **NULL pointer**. It's not practical to list all possible
+ error codes for every function as they propagate errors from the underlying
+ libc functions.
+
+In general libgpiod functions are **NULL-aware**. For functions that are
+logically methods of data classes - ones that take a pointer to the object of
+that class as the first argument - passing a NULL-pointer will result in the
+program aborting the execution. For non-methods, init functions and methods
+that take a pointer as any of the subsequent arguments, the handling of a
+NULL-pointer depends on the implementation and may range from gracefully
+handling it, ignoring it or returning an error.
+
+**libgpiod** is **thread-aware** but does not provide any further thread-safety
+guarantees. This requires the user to ensure that at most one thread may work
+with an object at any time. Sharing objects across threads is allowed if
+a suitable synchronization mechanism serializes the access. Different,
+standalone objects can safely be used concurrently.
+
+.. note::
+ Most libgpiod objects are standalone. Exceptions - such as events allocated
+ in buffers - exist and are noted in the documentation.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ core_chips
+ core_chip_info
+ core_line_defs
+ core_line_info
+ core_line_watch
+ core_line_settings
+ core_line_config
+ core_request_config
+ core_line_request
+ core_edge_event
+ core_misc
diff --git a/docs/core_chip_info.rst b/docs/core_chip_info.rst
new file mode 100644
index 0000000..00d06ca
--- /dev/null
+++ b/docs/core_chip_info.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip info
+==============
+
+.. doxygengroup:: chip_info
diff --git a/docs/core_chips.rst b/docs/core_chips.rst
new file mode 100644
index 0000000..cd6eaac
--- /dev/null
+++ b/docs/core_chips.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip
+=========
+
+.. doxygengroup:: chips
diff --git a/docs/core_edge_event.rst b/docs/core_edge_event.rst
new file mode 100644
index 0000000..2ec05b8
--- /dev/null
+++ b/docs/core_edge_event.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO edge event
+===============
+
+.. doxygengroup:: edge_event
diff --git a/docs/core_line_config.rst b/docs/core_line_config.rst
new file mode 100644
index 0000000..b217ee1
--- /dev/null
+++ b/docs/core_line_config.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line configuration
+=======================
+
+.. doxygengroup:: line_config
diff --git a/docs/core_line_defs.rst b/docs/core_line_defs.rst
new file mode 100644
index 0000000..898f2a9
--- /dev/null
+++ b/docs/core_line_defs.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line definitions
+=====================
+
+.. doxygengroup:: line_defs
diff --git a/docs/core_line_info.rst b/docs/core_line_info.rst
new file mode 100644
index 0000000..403c3bb
--- /dev/null
+++ b/docs/core_line_info.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line information
+=====================
+
+.. doxygengroup:: line_info
diff --git a/docs/core_line_request.rst b/docs/core_line_request.rst
new file mode 100644
index 0000000..74e477d
--- /dev/null
+++ b/docs/core_line_request.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line request
+==================
+
+.. doxygengroup:: line_request
diff --git a/docs/core_line_settings.rst b/docs/core_line_settings.rst
new file mode 100644
index 0000000..e557f19
--- /dev/null
+++ b/docs/core_line_settings.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line settings
+==================
+
+.. doxygengroup:: line_settings
diff --git a/docs/core_line_watch.rst b/docs/core_line_watch.rst
new file mode 100644
index 0000000..8f078cb
--- /dev/null
+++ b/docs/core_line_watch.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line watch
+===============
+
+.. doxygengroup:: line_watch
diff --git a/docs/core_misc.rst b/docs/core_misc.rst
new file mode 100644
index 0000000..34c327f
--- /dev/null
+++ b/docs/core_misc.rst
@@ -0,0 +1,11 @@
+..
+ 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 misc interfaces
+========================
+
+.. doxygengroup:: misc
diff --git a/docs/core_request_config.rst b/docs/core_request_config.rst
new file mode 100644
index 0000000..328063c
--- /dev/null
+++ b/docs/core_request_config.rst
@@ -0,0 +1,11 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO request configuration
+==========================
+
+.. doxygengroup:: request_config
diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst
new file mode 100644
index 0000000..83a6aa4
--- /dev/null
+++ b/docs/cpp_api.rst
@@ -0,0 +1,34 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+ libgpiodcxx API documentation
+
+libgpiod C++ bindings API
+=========================
+
+The **C++ bindings** for **libgpiod** provide a modern C++ wrapper around the
+core C API. These bindings make it easier to work with GPIO lines in C++ by
+offering an **object-oriented** approach and **RAII** (Resource Acquisition
+Is Initialization) principles for managing resources.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ cpp_chip
+ cpp_chip_info
+ cpp_edge_event
+ cpp_edge_event_buffer
+ cpp_exceptions
+ cpp_info_event
+ cpp_line
+ cpp_line_info
+ cpp_line_config
+ cpp_line_settings
+ cpp_request_config
+ cpp_line_request
+ cpp_misc
diff --git a/docs/cpp_chip.rst b/docs/cpp_chip.rst
new file mode 100644
index 0000000..c74ed66
--- /dev/null
+++ b/docs/cpp_chip.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip
+=========
+
+.. doxygenclass:: gpiod::chip
+ :members:
diff --git a/docs/cpp_chip_info.rst b/docs/cpp_chip_info.rst
new file mode 100644
index 0000000..e81c0d7
--- /dev/null
+++ b/docs/cpp_chip_info.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip info
+==============
+
+.. doxygenclass:: gpiod::chip_info
+ :members:
diff --git a/docs/cpp_edge_event.rst b/docs/cpp_edge_event.rst
new file mode 100644
index 0000000..c01e01d
--- /dev/null
+++ b/docs/cpp_edge_event.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO edge event
+===============
+
+.. doxygenclass:: gpiod::edge_event
+ :members:
diff --git a/docs/cpp_edge_event_buffer.rst b/docs/cpp_edge_event_buffer.rst
new file mode 100644
index 0000000..c792776
--- /dev/null
+++ b/docs/cpp_edge_event_buffer.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO edge event buffer
+======================
+
+.. doxygenclass:: gpiod::edge_event_buffer
+ :members:
diff --git a/docs/cpp_exceptions.rst b/docs/cpp_exceptions.rst
new file mode 100644
index 0000000..96eb815
--- /dev/null
+++ b/docs/cpp_exceptions.rst
@@ -0,0 +1,18 @@
+..
+ 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 exceptions
+===================
+
+.. doxygenclass:: gpiod::chip_closed
+ :members:
+
+.. doxygenclass:: gpiod::request_released
+ :members:
+
+.. doxygenclass:: gpiod::bad_mapping
+ :members:
diff --git a/docs/cpp_info_event.rst b/docs/cpp_info_event.rst
new file mode 100644
index 0000000..cb8256c
--- /dev/null
+++ b/docs/cpp_info_event.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO info event
+===============
+
+.. doxygenclass:: gpiod::info_event
+ :members:
diff --git a/docs/cpp_line.rst b/docs/cpp_line.rst
new file mode 100644
index 0000000..f7a483b
--- /dev/null
+++ b/docs/cpp_line.rst
@@ -0,0 +1,24 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+libgpiodcxx line definitions
+============================
+
+.. doxygenclass:: gpiod::line::offset
+ :members:
+
+.. doxygenenum:: gpiod::line::value
+
+.. doxygenenum:: gpiod::line::direction
+
+.. doxygenenum:: gpiod::line::edge
+
+.. doxygenenum:: gpiod::line::bias
+
+.. doxygenenum:: gpiod::line::drive
+
+.. doxygenenum:: gpiod::line::clock
diff --git a/docs/cpp_line_config.rst b/docs/cpp_line_config.rst
new file mode 100644
index 0000000..51b5374
--- /dev/null
+++ b/docs/cpp_line_config.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line configuration
+=======================
+
+.. doxygenclass:: gpiod::line_config
+ :members:
diff --git a/docs/cpp_line_info.rst b/docs/cpp_line_info.rst
new file mode 100644
index 0000000..7c9c59b
--- /dev/null
+++ b/docs/cpp_line_info.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line info
+==============
+
+.. doxygenclass:: gpiod::line_info
+ :members:
diff --git a/docs/cpp_line_request.rst b/docs/cpp_line_request.rst
new file mode 100644
index 0000000..0e356f5
--- /dev/null
+++ b/docs/cpp_line_request.rst
@@ -0,0 +1,15 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line request
+=================
+
+.. doxygenclass:: gpiod::request_builder
+ :members:
+
+.. doxygenclass:: gpiod::line_request
+ :members:
diff --git a/docs/cpp_line_settings.rst b/docs/cpp_line_settings.rst
new file mode 100644
index 0000000..1892d59
--- /dev/null
+++ b/docs/cpp_line_settings.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line settings
+==================
+
+.. doxygenclass:: gpiod::line_settings
+ :members:
diff --git a/docs/cpp_misc.rst b/docs/cpp_misc.rst
new file mode 100644
index 0000000..ed57fbc
--- /dev/null
+++ b/docs/cpp_misc.rst
@@ -0,0 +1,16 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+libgpiodcxx misc interfaces
+===========================
+
+.. doxygenclass:: gpiod::timestamp
+ :members:
+
+.. doxygenfunction:: gpiod::is_gpiochip_device
+
+.. doxygenfunction:: gpiod::api_version
diff --git a/docs/cpp_request_config.rst b/docs/cpp_request_config.rst
new file mode 100644
index 0000000..26f4388
--- /dev/null
+++ b/docs/cpp_request_config.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO request configuration
+==========================
+
+.. doxygenclass:: gpiod::request_config
+ :members:
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..8dcea20
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,28 @@
+..
+ 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 documentation master file.
+
+Welcome to libgpiod's documentation!
+====================================
+
+The **libgpiod** project provides a low-level C library, bindings to high-level
+languages and tools for interacting with the GPIO (General Purpose Input/Output)
+lines on Linux systems.
+
+It replaces the older, legacy GPIO sysfs interface, which has been deprecated
+in the Linux kernel. The newer GPIO character device interface (introduced in
+Linux kernel version 4.8) provides a more flexible and efficient way to
+interact with GPIO lines, and libgpiod is the primary tool for working with
+this interface.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ core_api
+ bindings
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..9866547
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+breathe==4.35.0
+sphinx-rtd-theme==3.0.2
diff --git a/include/gpiod.h b/include/gpiod.h
index 75c55d9..6d40275 100644
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -16,42 +16,6 @@
extern "C" {
#endif
-/**
- * @mainpage libgpiod public API
- *
- * This is the complete documentation of the public API made available to
- * users of libgpiod.
- *
- * The API is logically split into several sections. For each opaque data
- * class, there's a set of functions for manipulating it. Together they can be
- * thought of as objects and their methods in OOP parlance.
- *
- * General note on error handling: all functions exported by libgpiod that
- * can fail, set errno to one of the error values defined in errno.h upon
- * failure. The way of notifying the caller that an error occurred varies
- * between functions, but in general a function that returns an int, returns -1
- * on error, while a function returning a pointer indicates an error condition
- * by returning a NULL pointer. It's not practical to list all possible error
- * codes for every function as they propagate errors from the underlying libc
- * functions.
- *
- * In general libgpiod functions are NULL-aware. For functions that are
- * logically methods of data classes - ones that take a pointer to the object
- * of that class as the first argument - passing a NULL pointer will result in
- * the program aborting the execution. For non-methods, init functions and
- * methods that take a pointer as any of the subsequent arguments, the handling
- * of a NULL-pointer depends on the implementation and may range from gracefully
- * handling it, ignoring it or returning an error.
- *
- * libgpiod is thread-aware but does not provide any further thread-safety
- * guarantees. This requires the user to ensure that at most one thread may
- * work with an object at any time. Sharing objects across threads is allowed
- * if a suitable synchronization mechanism serializes the access. Different,
- * standalone objects can safely be used concurrently. Most libgpiod objects
- * are standalone. Exceptions - such as events allocated in buffers - exist and
- * are noted in the documentation.
- */
-
/**
* @struct gpiod_chip
* @{
diff --git a/sphinx/conf.py b/sphinx/conf.py
deleted file mode 100644
index 790c884..0000000
--- a/sphinx/conf.py
+++ /dev/null
@@ -1,68 +0,0 @@
-# SPDX-License-Identifier: LGPL-2.1-or-later
-# SPDX-FileCopyrightText: 2022 Kent Gibson <warthog618@gmail.com>
-
-# This file is part of libgpiod.
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-import subprocess
-
-subprocess.run("cd .. ; ./autogen.sh ; make doc", shell=True)
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-# -- Project information -----------------------------------------------------
-
-project = "libgpiod"
-copyright = "2022, Bartosz Golaszewski"
-author = "Bartosz Golaszewski"
-
-# The full version, including alpha/beta/rc tags
-release = (
- subprocess.run(["git", "describe", "--dirty"], capture_output=True)
- .stdout.decode()
- .strip()
-)
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = []
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = []
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
-
-# -- Options for HTML output -------------------------------------------------
-
-root_doc = "contents"
-
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-#
-html_theme = "alabaster"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
-
-html_extra_path = ["../doc/html"]
diff --git a/sphinx/contents.rst b/sphinx/contents.rst
deleted file mode 100644
index c26d068..0000000
--- a/sphinx/contents.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-..
- SPDX-License-Identifier: LGPL-2.1-or-later
- SPDX-FileCopyrightText: 2022 Kent Gibson <warthog618@gmail.com>
-
-..
- This file is part of libgpiod.
-
- libgpiod documentation master file.
-
-Welcome to libgpiod's documentation!
-====================================
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* RE: [External] - [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings
2025-02-06 12:22 ` [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings Bartosz Golaszewski
@ 2025-02-10 14:53 ` Vincent Fazio
2025-02-11 12:19 ` Bartosz Golaszewski
0 siblings, 1 reply; 23+ messages in thread
From: Vincent Fazio @ 2025-02-10 14:53 UTC (permalink / raw)
To: Bartosz Golaszewski, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio@vger.kernel.org
> -----Original Message-----
> From: Bartosz Golaszewski <brgl@bgdev.pl>
> Sent: Thursday, February 6, 2025 6:22 AM
> To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson
> <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik
> Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>;
> Viresh Kumar <viresh.kumar@linaro.org>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux-
> gpio@vger.kernel.org
> Subject: [External] - [PATCH libgpiod v3 11/16] doc: provide sphinx docs for
> the core C API and C++ bindings
>
> From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
>
> Current sphinx/ contents are mostly WiP. Let's beat them into shape for
> publishing on ReadTheDocs.
>
> Integrate the API documentation generated with doxygen for the core C API
> and C++ bindings into sphinx using breathe.
>
> Update configure.ac to check for sphinx-build in addition to doxygen and
> make the main Makefile trigger a sphinx build on `make doc` (although the
> docs can also be generated without starting the build system by
> running: `sphinx-build ./doc/ doc/sphinx-output`).
Should probably be "docs"? sphinx-build ./docs/ docs/sphinx-output
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [External] - [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings
2025-02-10 14:53 ` [External] - " Vincent Fazio
@ 2025-02-11 12:19 ` Bartosz Golaszewski
0 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-11 12:19 UTC (permalink / raw)
To: Vincent Fazio
Cc: Kent Gibson, Linus Walleij, Erik Schilling, Phil Howard,
Viresh Kumar, Bartosz Golaszewski, linux-gpio@vger.kernel.org
On Mon, Feb 10, 2025 at 3:53 PM Vincent Fazio <vfazio@xes-inc.com> wrote:
> >
> > Update configure.ac to check for sphinx-build in addition to doxygen and
> > make the main Makefile trigger a sphinx build on `make doc` (although the
> > docs can also be generated without starting the build system by
> > running: `sphinx-build ./doc/ doc/sphinx-output`).
>
> Should probably be "docs"? sphinx-build ./docs/ docs/sphinx-output
>
Yes, thanks!
Bart
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH libgpiod v3 12/16] doc: add documentation for python bindings
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (10 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 11/16] doc: provide sphinx docs for the core C API and C++ bindings Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings Bartosz Golaszewski
` (3 subsequent siblings)
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Integrate python docs with sphinx using autodoc and the import mock
feature which allows us to avoid having to build the C extension.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
docs/Makefile.am | 13 ++++++++++++-
docs/bindings.rst | 1 +
docs/conf.py | 18 +++++++++++++++++-
docs/python_api.rst | 33 +++++++++++++++++++++++++++++++++
docs/python_chip.rst | 12 ++++++++++++
docs/python_chip_info.rst | 12 ++++++++++++
docs/python_edge_event.rst | 12 ++++++++++++
docs/python_exceptions.rst | 17 +++++++++++++++++
docs/python_info_event.rst | 12 ++++++++++++
docs/python_line.rst | 27 +++++++++++++++++++++++++++
docs/python_line_info.rst | 12 ++++++++++++
docs/python_line_request.rst | 12 ++++++++++++
docs/python_line_settings.rst | 12 ++++++++++++
docs/python_misc.rst | 13 +++++++++++++
14 files changed, 204 insertions(+), 2 deletions(-)
diff --git a/docs/Makefile.am b/docs/Makefile.am
index b8cf010..dd3e6ac 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -31,7 +31,18 @@ DOCS_DEPS = \
cpp_misc.rst \
cpp_request_config.rst \
Doxyfile \
- index.rst
+ index.rst \
+ python_api.rst \
+ python_chip_info.rst \
+ python_chip.rst \
+ python_edge_event.rst \
+ python_exceptions.rst \
+ python_info_event.rst \
+ python_line_info.rst \
+ python_line_request.rst \
+ python_line.rst \
+ python_line_settings.rst \
+ python_misc.rst
docs: $(DOCS_DEPS)
sphinx-build ./ ./sphinx-output
diff --git a/docs/bindings.rst b/docs/bindings.rst
index 069fc8f..ed7ec69 100644
--- a/docs/bindings.rst
+++ b/docs/bindings.rst
@@ -18,3 +18,4 @@ C library.
:caption: Contents
cpp_api
+ python_api
diff --git a/docs/conf.py b/docs/conf.py
index 04c8c3b..3d0209a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,6 +9,7 @@ import os
import re
import subprocess
import sys
+from pathlib import Path
project = "libgpiod"
copyright = "2017-2025, Bartosz Golaszewski"
@@ -34,11 +35,14 @@ with open("../configure.ac", "r") as fd:
release = f"{version}{extra}"
-extensions = ["breathe"]
+extensions = ["breathe", "sphinx.ext.autodoc"]
breathe_projects = {"libgpiod": "./doxygen-output/xml"}
breathe_default_project = "libgpiod"
+sys.path.insert(0, str(Path("../bindings/python").resolve()))
+autodoc_mock_imports = ["gpiod._ext"]
+
# Use the RTD theme if available
sphinx_rtd_theme = None
try:
@@ -50,4 +54,16 @@ except ImportError:
html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default"
+
+def autodoc_skip_init(app, what, name, obj, would_skip, options):
+ if name == "__init__":
+ return False
+
+ return would_skip
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", autodoc_skip_init)
+
+
subprocess.run(["doxygen", "Doxyfile"])
diff --git a/docs/python_api.rst b/docs/python_api.rst
new file mode 100644
index 0000000..00b30cb
--- /dev/null
+++ b/docs/python_api.rst
@@ -0,0 +1,33 @@
+..
+ 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 python bindings documentation
+
+libgpiod Python bindings API
+============================
+
+The **libgpiod Python bindings** provide an interface to control and interact
+with GPIO (General-Purpose Input/Output) lines on Linux systems using the
+libgpiod library. The Python bindings allow developers to manage GPIO pins
+easily through Python scripts, enabling tasks such as reading input values,
+setting outputs, monitoring events, and configuring more fine-grained pin
+options.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ python_chip
+ python_chip_info
+ python_exceptions
+ python_line
+ python_line_info
+ python_info_event
+ python_edge_event
+ python_line_settings
+ python_line_request
+ python_misc
diff --git a/docs/python_chip.rst b/docs/python_chip.rst
new file mode 100644
index 0000000..8f56004
--- /dev/null
+++ b/docs/python_chip.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip
+=========
+
+.. autoclass:: gpiod.Chip
+ :members:
diff --git a/docs/python_chip_info.rst b/docs/python_chip_info.rst
new file mode 100644
index 0000000..c6db865
--- /dev/null
+++ b/docs/python_chip_info.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO chip info
+==============
+
+.. autoclass:: gpiod.ChipInfo
+ :members:
diff --git a/docs/python_edge_event.rst b/docs/python_edge_event.rst
new file mode 100644
index 0000000..b316665
--- /dev/null
+++ b/docs/python_edge_event.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO edge event
+===============
+
+.. autoclass:: gpiod.EdgeEvent
+ :members:
diff --git a/docs/python_exceptions.rst b/docs/python_exceptions.rst
new file mode 100644
index 0000000..260dc3d
--- /dev/null
+++ b/docs/python_exceptions.rst
@@ -0,0 +1,17 @@
+..
+ 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 python errors
+======================
+
+.. autoclass:: gpiod.ChipClosedError
+ :members:
+ :show-inheritance:
+
+.. autoclass:: gpiod.RequestReleasedError
+ :members:
+ :show-inheritance:
diff --git a/docs/python_info_event.rst b/docs/python_info_event.rst
new file mode 100644
index 0000000..b89cdfa
--- /dev/null
+++ b/docs/python_info_event.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO info event
+===============
+
+.. autoclass:: gpiod.InfoEvent
+ :members:
diff --git a/docs/python_line.rst b/docs/python_line.rst
new file mode 100644
index 0000000..ec8f09f
--- /dev/null
+++ b/docs/python_line.rst
@@ -0,0 +1,27 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line definitions
+=====================
+
+.. autoclass:: gpiod.line.Value
+ :members:
+
+.. autoclass:: gpiod.line.Direction
+ :members:
+
+.. autoclass:: gpiod.line.Bias
+ :members:
+
+.. autoclass:: gpiod.line.Drive
+ :members:
+
+.. autoclass:: gpiod.line.Edge
+ :members:
+
+.. autoclass:: gpiod.line.Clock
+ :members:
diff --git a/docs/python_line_info.rst b/docs/python_line_info.rst
new file mode 100644
index 0000000..06f526f
--- /dev/null
+++ b/docs/python_line_info.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line info
+==============
+
+.. autoclass:: gpiod.LineInfo
+ :members:
diff --git a/docs/python_line_request.rst b/docs/python_line_request.rst
new file mode 100644
index 0000000..2d78b4c
--- /dev/null
+++ b/docs/python_line_request.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line request
+=================
+
+.. autoclass:: gpiod.LineRequest
+ :members:
diff --git a/docs/python_line_settings.rst b/docs/python_line_settings.rst
new file mode 100644
index 0000000..b1d594e
--- /dev/null
+++ b/docs/python_line_settings.rst
@@ -0,0 +1,12 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+GPIO line settings
+==================
+
+.. autoclass:: gpiod.LineSettings
+ :members:
diff --git a/docs/python_misc.rst b/docs/python_misc.rst
new file mode 100644
index 0000000..3ba1e2d
--- /dev/null
+++ b/docs/python_misc.rst
@@ -0,0 +1,13 @@
+..
+ 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 python bindings misc
+=============================
+
+.. autofunction:: gpiod.is_gpiochip_device
+
+.. autofunction:: gpiod.request_lines
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (11 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 12/16] doc: add documentation for python bindings Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-10 15:10 ` [External] - " Vincent Fazio
2025-02-06 12:22 ` [PATCH libgpiod v3 14/16] doc: add documentation for gpio-tools Bartosz Golaszewski
` (2 subsequent siblings)
15 siblings, 1 reply; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
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 --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>`_
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* RE: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings
2025-02-06 12:22 ` [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings Bartosz Golaszewski
@ 2025-02-10 15:10 ` Vincent Fazio
2025-02-11 12:51 ` Bartosz Golaszewski
0 siblings, 1 reply; 23+ messages in thread
From: Vincent Fazio @ 2025-02-10 15:10 UTC (permalink / raw)
To: Bartosz Golaszewski, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio@vger.kernel.org
> -----Original Message-----
> From: Bartosz Golaszewski <brgl@bgdev.pl>
> Sent: Thursday, February 6, 2025 6:22 AM
> To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson
> <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik
> Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>;
> Viresh Kumar <viresh.kumar@linaro.org>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux-
> gpio@vger.kernel.org
> Subject: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for
> GLib bindings
>
> 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 --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 ""
Building via `sphinx-build ./docs/ docs/sphinx-output` seems to work ok but building via `make docs` does not, maybe due to `make -C docs docs ` changing directory and requiring the prefix be present?
Maybe we should always use the "../" prefix and expect callers from the top directory to: `pushd docs; sphinx-build . ./sphinx-output; popd`
(venv) root@9935cce25ae1:/work# make docs > /dev/null
autoreconf: export WARNINGS=
autoreconf: Entering directory '.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force -I m4
autoreconf: configure.ac: tracing
autoreconf: running: libtoolize --copy --force
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: aclocal --force -I m4
autoreconf: running: /usr/bin/autoconf --force
autoreconf: running: /usr/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
configure.ac:54: installing 'autostuff/compile'
configure.ac:40: installing 'autostuff/missing'
bindings/cxx/Makefile.am: installing 'autostuff/depcomp'
autoreconf: Leaving directory '.'
/work/venv/lib/python3.12/site-packages/breathe/project.py:116: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
self._default_build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
usage: gi-docgen generate [-h] [-q] [--fatal-warnings]
[--add-include-path INCLUDE_PATHS] [-C FILE]
[--dry-run] [--templates-dir TEMPLATES_DIR]
[--content-dir CONTENT_DIRS] [--theme-name THEME_NAME]
[--output-dir OUTPUT_DIR] [--no-namespace-dir]
[--section SECTIONS]
GIRFILE
gi-docgen generate: error: argument GIRFILE: can't open 'bindings/glib/Gpiodglib-1.0.gir': [Errno 2] No such file or directory: 'bindings/glib/Gpiodglib-1.0.gir'
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings
2025-02-10 15:10 ` [External] - " Vincent Fazio
@ 2025-02-11 12:51 ` Bartosz Golaszewski
0 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-11 12:51 UTC (permalink / raw)
To: Vincent Fazio
Cc: Kent Gibson, Linus Walleij, Erik Schilling, Phil Howard,
Viresh Kumar, Bartosz Golaszewski, linux-gpio@vger.kernel.org
On Mon, Feb 10, 2025 at 4:10 PM Vincent Fazio <vfazio@xes-inc.com> wrote:
>
>
>
> > -----Original Message-----
> > From: Bartosz Golaszewski <brgl@bgdev.pl>
> > Sent: Thursday, February 6, 2025 6:22 AM
> > To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson
> > <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik
> > Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>;
> > Viresh Kumar <viresh.kumar@linaro.org>
> > Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux-
> > gpio@vger.kernel.org
> > Subject: [External] - [PATCH libgpiod v3 13/16] doc: add documentation for
> > GLib bindings
> >
> > 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 --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 ""
>
> Building via `sphinx-build ./docs/ docs/sphinx-output` seems to work ok but building via `make docs` does not, maybe due to `make -C docs docs ` changing directory and requiring the prefix be present?
>
> Maybe we should always use the "../" prefix and expect callers from the top directory to: `pushd docs; sphinx-build . ./sphinx-output; popd`
>
> (venv) root@9935cce25ae1:/work# make docs > /dev/null
> autoreconf: export WARNINGS=
> autoreconf: Entering directory '.'
> autoreconf: configure.ac: not using Gettext
> autoreconf: running: aclocal --force -I m4
> autoreconf: configure.ac: tracing
> autoreconf: running: libtoolize --copy --force
> autoreconf: configure.ac: not using Intltool
> autoreconf: configure.ac: not using Gtkdoc
> autoreconf: running: aclocal --force -I m4
> autoreconf: running: /usr/bin/autoconf --force
> autoreconf: running: /usr/bin/autoheader --force
> autoreconf: running: automake --add-missing --copy --force-missing
> configure.ac:54: installing 'autostuff/compile'
> configure.ac:40: installing 'autostuff/missing'
> bindings/cxx/Makefile.am: installing 'autostuff/depcomp'
> autoreconf: Leaving directory '.'
> /work/venv/lib/python3.12/site-packages/breathe/project.py:116: RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
> self._default_build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep))
> usage: gi-docgen generate [-h] [-q] [--fatal-warnings]
> [--add-include-path INCLUDE_PATHS] [-C FILE]
> [--dry-run] [--templates-dir TEMPLATES_DIR]
> [--content-dir CONTENT_DIRS] [--theme-name THEME_NAME]
> [--output-dir OUTPUT_DIR] [--no-namespace-dir]
> [--section SECTIONS]
> GIRFILE
> gi-docgen generate: error: argument GIRFILE: can't open 'bindings/glib/Gpiodglib-1.0.gir': [Errno 2] No such file or directory: 'bindings/glib/Gpiodglib-1.0.gir'
>
>
I worked around it in docs/Makefile.am.
Bart
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH libgpiod v3 14/16] doc: add documentation for gpio-tools
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (12 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 13/16] doc: add documentation for GLib bindings Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 15/16] doc: add documentation for D-Bus API, daemon and command-line client Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs Bartosz Golaszewski
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
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 --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
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 15/16] doc: add documentation for D-Bus API, daemon and command-line client
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (13 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 14/16] doc: add documentation for gpio-tools Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-06 12:22 ` [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs Bartosz Golaszewski
15 siblings, 0 replies; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
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 --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
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs
2025-02-06 12:21 [PATCH libgpiod v3 00/16] doc: improvements for ReadTheDocs Bartosz Golaszewski
` (14 preceding siblings ...)
2025-02-06 12:22 ` [PATCH libgpiod v3 15/16] doc: add documentation for D-Bus API, daemon and command-line client Bartosz Golaszewski
@ 2025-02-06 12:22 ` Bartosz Golaszewski
2025-02-10 13:48 ` [External] - " Vincent Fazio
15 siblings, 1 reply; 23+ messages in thread
From: Bartosz Golaszewski @ 2025-02-06 12:22 UTC (permalink / raw)
To: Vincent Fazio, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio
From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
We now have comprehensive documentation available online on readthedocs.
Let's not duplicate docs in README - move all information into the
sphinx files.
While at it: make the remaining README use markdown.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
README | 384 --------------------------------------------------
README.md | 11 ++
docs/bindings.rst | 25 +++-
docs/building.rst | 74 ++++++++++
docs/contributing.rst | 45 ++++++
docs/cpp_api.rst | 3 +
docs/dbus.rst | 19 ++-
docs/glib_api.rst | 3 +
docs/gpio_tools.rst | 216 ++++++++++++++++++++++++++++
docs/gpiocli_top.rst | 81 +++++++++++
docs/index.rst | 23 ++-
docs/python_api.rst | 8 ++
docs/testing.rst | 46 ++++++
13 files changed, 544 insertions(+), 394 deletions(-)
diff --git a/README b/README
deleted file mode 100644
index 28a3dfd..0000000
--- a/README
+++ /dev/null
@@ -1,384 +0,0 @@
-# SPDX-License-Identifier: CC-BY-SA-4.0
-# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski <brgl@bgdev.pl>
-
-libgpiod
-========
-
- libgpiod - C library and tools for interacting with the linux GPIO
- character device (gpiod stands for GPIO device)
-
-Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use
-the character device instead. Version 2 of libgpiod requires GPIO character
-device uAPI v2 which was first released in linux 5.10. This library
-encapsulates the ioctl calls and data structures behind a straightforward API.
-
-RATIONALE
----------
-
-The new character device interface guarantees all allocated resources are
-freed after closing the device file descriptor and adds several new features
-that are not present in the obsolete sysfs interface (like event polling,
-setting/reading multiple values at once or open-source and open-drain GPIOs).
-
-Unfortunately interacting with the linux device file can no longer be done
-using only standard command-line tools. This is the reason for creating a
-library encapsulating the cumbersome, ioctl-based kernel-userspace interaction
-in a set of convenient functions and opaque data structures.
-
-Additionally this project contains a set of command-line tools that should
-allow an easy conversion of user scripts to using the character device.
-
-BUILDING
---------
-
-This is a pretty standard autotools project. The core C library does not have
-any external dependencies other than the standard C library with GNU extensions.
-
-The build system requires autotools, autoconf-archive, libtool and pkg-config
-to be installed on the host system for the basic build. Development files for
-additional libraries may be required depending on selected options. The
-configure script will report any missing additional required dependencies.
-
-The command-line tools optionally depend on libedit for the interactive feature.
-
-To build the project (including command-line utilities) run:
-
- ./autogen.sh --enable-tools=yes --prefix=<install path>
- make
- make install
-
-The autogen script will execute ./configure and pass all the command-line
-arguments to it.
-
-If building from release tarballs, the configure script is already provided and
-there's no need to invoke autogen.sh.
-
-For all configure features, see: ./configure --help.
-
-TOOLS
------
-
-There are currently six command-line tools available:
-
-* gpiodetect - list all gpiochips present on the system, their names, labels
- and number of GPIO lines
-
-* gpioinfo - list lines, their gpiochip, offset, name, and direction, and
- if in use then the consumer name and any other configured
- attributes, such as active state, bias, drive, edge detection
- and debounce period
-
-* gpioget - read values of specified GPIO lines
-
-* gpioset - set values of specified GPIO lines, holding the lines until the
- process is killed or otherwise exits
-
-* gpiomon - wait for edge events on GPIO lines, specify which edges to watch
- for, how many events to process before exiting, or if the events
- should be reported to the console
-
-* gpionotify - wait for changed to the info for GPIO lines, specify which
- changes to watch for, how many events to process before exiting,
- or if the events should be reported to the console
-
-Examples:
-
- (using a Raspberry Pi 4B)
-
- # Detect the available gpiochips.
- $ gpiodetect
- gpiochip0 [pinctrl-bcm2711] (58 lines)
- gpiochip1 [raspberrypi-exp-gpio] (8 lines)
-
- # Read the info for all the lines on a gpiochip.
- $ gpioinfo -c 1
- gpiochip1 - 8 lines:
- line 0: "BT_ON" output
- line 1: "WL_ON" output
- line 2: "PWR_LED_OFF" output active-low consumer="led1"
- line 3: "GLOBAL_RESET" output
- line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io"
- line 5: "CAM_GPIO" output consumer="cam1_regulator"
- line 6: "SD_PWR_ON" output consumer="sd_vcc_reg"
- line 7: "SD_OC_N" input
-
- # Read the info for particular lines.
- $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET
- gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0"
- gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1"
- gpiochip1 3 "GLOBAL_RESET" output
-
- # Read the value of a single GPIO line by name.
- $ gpioget RXD1
- "RXD1"=active
-
- # Read the value of a single GPIO line by chip and offset.
- $ gpioget -c 0 15
- "15"=active
-
- # Read the value of a single GPIO line as a numeric value.
- $ gpioget --numeric RXD1
- 1
-
- # Read two values at the same time. Set the active state of the lines
- # to low and without quoted names.
- $ gpioget --active-low --unquoted GPIO23 GPIO24
- GPIO23=active GPIO24=active
-
- # Set the value of a line and hold the line until killed.
- $ gpioset GPIO23=1
-
- # Set values of two lines, then daemonize and hold the lines.
- $ gpioset --daemonize GPIO23=1 GPIO24=0
-
- # Set the value of a single line, hold it for 20ms, then exit.
- $ gpioset --hold-period 20ms -t0 GPIO23=1
-
- # Blink an LED on GPIO22 at 1Hz
- $ gpioset -t500ms GPIO22=1
-
- # Blink an LED on GPIO22 at 1Hz with a 20% duty cycle
- $ gpioset -t200ms,800ms GPIO22=1
-
- # Set some lines interactively (requires --enable-gpioset-interactive)
- $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active
- gpioset> get
- GPIO23=inactive GPIO24=active
- gpioset> toggle
- gpioset> get
- GPIO23=active GPIO24=inactive
- gpioset> set GPIO24=1
- gpioset> get
- GPIO23=active GPIO24=active
- gpioset> toggle
- gpioset> get
- GPIO23=inactive GPIO24=inactive
- gpioset> toggle GPIO23
- gpioset> get
- GPIO23=active GPIO24=inactive
- gpioset> exit
-
- # Wait for three rising edge events on a single GPIO line, then exit.
- $ gpiomon --num-events=3 --edges=rising GPIO22
- 10002.907638045 rising "GPIO22"
- 10037.132562259 rising "GPIO22"
- 10047.179790748 rising "GPIO22"
-
- # Wait for three edge events on a single GPIO line, with time in local time
- # and with unquoted line name, then exit.
- $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22
- 2022-11-15T10:36:59.109615508 rising GPIO22
- 2022-11-15T10:36:59.129681898 falling GPIO22
- 2022-11-15T10:36:59.698971886 rising GPIO22
-
- # Wait for falling edge events with a custom output format.
- $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22
- 2 gpiochip0 22 GPIO22 10946.693481859
- 2 gpiochip0 22 GPIO22 10947.025347604
- 2 gpiochip0 22 GPIO22 10947.283716669
- 2 gpiochip0 22 GPIO22 10947.570109430
- ...
-
- # Block until an edge event occurs. Don't print anything.
- $ gpiomon --num-events=1 --quiet GPIO22
-
- # Monitor multiple lines, exit after the first edge event.
- $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17
-
- # Monitor a line for changes to info.
- $ gpionotify GPIO23
- 11571.816473718 requested "GPIO23"
- 11571.816535124 released "GPIO23"
- 11572.722894029 requested "GPIO23"
- 11572.722932843 released "GPIO23"
- 11573.222998598 requested "GPIO23"
- ...
-
- # Monitor a line for requests, reporting UTC time and unquoted line name.
- $ gpionotify --utc --unquoted GPIO23
- 2022-11-15T03:05:23.807090687Z requested GPIO23
- 2022-11-15T03:05:23.807151390Z released GPIO23
- 2022-11-15T03:05:24.784984280Z requested GPIO23
- 2022-11-15T03:05:24.785023873Z released GPIO23
- ...
-
- # Monitor multiple lines, exit after the first is requested.
- $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17
-
- # Block until a line is released.
- $ gpionotify --quiet --num-events=1 --event=released GPIO6
-
-BINDINGS
---------
-
-High-level, object-oriented bindings for C++, GLib, python3 and Rust are
-provided. They can be enabled by passing --enable-bindings-cxx,
---enable-bindings-glib, --enable-bindings-python and --enable-bindings-rust
-arguments respectively to configure.
-
-C++ bindings require C++11 support and autoconf-archive collection if building
-from git.
-
-GLib bindings requires GLib (as well as GObject, GIO and GIO-Unix) v2.54.
-
-Python bindings require python3 support and libpython development files. Please
-refer to bindings/python/README.md for more information.
-
-Rust bindings require cargo support. 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. Please refer to bindings/rust/libgpiod/README.md
-for more information.
-
-DBUS
-----
-
-A commonly requested feature for the GPIO character device was state persistence
-after releasing the lines (as a kernel feature) or providing a central authority
-(in user-space) that would be in charge of keeping the lines requested and in a
-certain state (similarily to how the sysfs ABI works). DBus API has been
-provided to address this requirement. We define an interface covering the
-majority of the GPIO chardev's functionality and implement it from both the
-server and client sides in the form of the gpio-manager daemon and the gpiocli
-command-line utility for talking to the manager.
-
-DBus support can be built by passing --enable-dbus to configure. The daemon
-is bundled with a systemd unit file and an example configuration file for the
-io.gpiod1 interface that allows all users to access basic information about the
-GPIOs in the system but only root to request lines or change their values.
-
-With the manager running the user can run gpiocli to control GPIOs by asking
-gpio-manager to act on their behalf:
-
- # Detect chips in the system.
- $ gpiocli detect
- gpiochip0 [INT34C6:00] (463 lines)
-
- # Request a set of lines. Note that gpiocli exits immediately but the
- # state of the lines is retained because it's the gpio-manager that
- # requested them.
- $ gpiocli request --output foo=active
- request0
-
- # Previous invocation printed out the name of the request by which the
- # caller can refer to it later. All active requests can also be inspected
- # at any time.
- $ gpiocli requests
- request0 (gpiochip1) Offsets: [5]
-
- # We can print the information about the requested line using the
- # information above.
- $ gpiocli info --chip=gpiochip1 5
- gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull]
-
- # We can now change the value of the line.
- $ gpiocli set foo=inactive
-
- # And read it.
- $ gpiocli get foo
- "foo"=inactive
-
- # We can even reconfigure it to input and enable edge-detection.
- $ gpiocli reconfigure --input --both-edges request0
-
- # And wait for edge events.
- $ gpiocli monitor cos
- 21763952894920 rising "foo"
-
- # And finally release the request.
- $ gpiocli release request0
-
-For more information please refer to the output of gpiocli --help as well as
-gpiocli <command> --help which prints detailed info on every available command.
-
-Of course - this being DBus - users can talk to gpio-manager using any DBus
-library available and are not limited to the provided client.
-
-TESTING
--------
-
-A comprehensive testing framework is included with the library and can be
-used to test both the core library code as well as the kernel-to-user-space
-interface.
-
-The minimum kernel version required to run the tests can be checked in the
-tests/gpiod-test.c source file (it's subject to change if new features are
-added to the kernel). The tests work together with the gpio-sim kernel module
-which must either be built-in or available for loading using kmod. A helper
-library - libgpiosim - is included to enable straightforward interaction with
-the module.
-
-To build the testing executable add the '--enable-tests' option when running
-the configure script. If enabled, the tests will be installed next to
-gpio-tools.
-
-As opposed to standard autotools projects, libgpiod doesn't execute any tests
-when invoking 'make check'. Instead the user must run them manually with
-superuser privileges.
-
-The testing framework uses the GLib unit testing library so development package
-for GLib must be installed.
-
-The gpio-tools programs can be tested separately using the gpio-tools-test.bash
-script. It requires shunit2[1] to run and assumes that the tested executables are
-in the same directory as the script.
-
-C++, Rust and Python bindings also include their own test-suites. All three
-reuse the libgpiosim library to avoid code duplication when interacting with
-gpio-sim.
-
-Python test-suite uses the standard unittest package. C++ tests use an external
-testing framework - Catch2 - which must be installed in the system. Rust
-bindings use the standard tests module layout and the #[test] attribute.
-
-DOCUMENTATION
--------------
-
-The project uses sphinx to automatically generate the documentation. The system
-needs to provide doxygen and sphinx-build programs. With those in place, the
-build can be invoked with 'make docs'. This generates documentation for the
-core C API as well as C++ and python bindings.
-
-Rust bindings use rustdoc, GLib bindings use gi-docgen.
-
-Man pages for command-line programs are generated automatically if gpio-tools
-were selected and help2man is available in the system.
-
-CONTRIBUTING
-------------
-
-Contributions are welcome - please send questions, patches and bug reports
-to the linux-gpio mailing list[2] by e-mailing to linux-gpio@vger.kernel.org
-(add the [libgpiod] prefix to the e-mail subject line).
-Note that the mailing list quietly drops HTML formatted e-mail, so be sure
-to send plain text[3].
-
-Code submissions should stick to the linux kernel coding style[4] and
-follow the kernel patch submission process[5] as applied to the libgpiod
-source tree. All shell scripts must pass `shellcheck` tests[9]. All files
-must have a license and copyright SPDX headers and the repo is expected to
-pass the `reuse lint` check[10].
-
-The mailing list archive[6] contains all the historical mails to the list,
-and is the place to check to ensure your e-mail has been received.
-Search for "libgpiod" to filter the list down to relevant messages.
-Those also provide examples of the expected formatting.
-Allow some time for your e-mail to propagate to the list before retrying,
-particularly if there are no e-mails in the list more recent than yours.
-
-There is a libgpiod github page[7] available for reporting bugs and general
-discussions and although PRs can be submitted and discussed, upstreambound
-patches need to go through the mailing list nevertheless while release
-tarballs should be fetched from kernel.org[8].
-
-For more information, refer to CONTRIBUTING.md in this repository.
-
-[1] https://github.com/kward/shunit2
-[2] http://vger.kernel.org/vger-lists.html#linux-gpio
-[3] https://docs.kernel.org/process/email-clients.html
-[4] https://docs.kernel.org/process/coding-style.html
-[5] https://docs.kernel.org/process/submitting-patches.html
-[6] https://lore.kernel.org/linux-gpio/
-[7] https://github.com/brgl/libgpiod
-[8] https://mirrors.edge.kernel.org/pub/software/libs/libgpiod/
-[9] https://www.shellcheck.net/
-[10] https://reuse.software/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..664dbc5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,11 @@
+<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
+<!-- SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org> -->
+
+libgpiod
+========
+
+C library and tools for interacting with the linux GPIO character device.
+
+The project is hosted at https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/.
+
+Documentation is available at https://libgpiod.readthedocs.io/.
diff --git a/docs/bindings.rst b/docs/bindings.rst
index 73f1262..7f0f6b7 100644
--- a/docs/bindings.rst
+++ b/docs/bindings.rst
@@ -10,8 +10,12 @@
High-level language bindings to libgpiod
========================================
-The bindings provide a more straightforward interface to the base, low-level
-C library.
+Bindings provide a more straightforward interface to the core, low-level
+C library. Object-oriented bindings for C++, GLib, python3 and Rust are
+provided as part of the project. They can be enabled by passing
+``--enable-bindings-cxx``, ``--enable-bindings-glib``,
+``--enable-bindings-python`` and ``--enable-bindings-rust`` arguments to
+configure respectively.
.. toctree::
:maxdepth: 1
@@ -20,3 +24,20 @@ C library.
cpp_api
python_api
glib_api
+
+.. 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.
+
+.. note::
+ Rust bindings 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.
+
diff --git a/docs/building.rst b/docs/building.rst
new file mode 100644
index 0000000..958c6fb
--- /dev/null
+++ b/docs/building.rst
@@ -0,0 +1,74 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+Downloading, building & installing
+==================================
+
+Downloading
+-----------
+
+Libgpiod is packaged by several linux distributions. You should typically be
+able to install it using your package manager. If you want to build libgpiod
+from sources, the upstream git repository for libgpiod is hosted at
+`kernel.org <https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/>`_.
+together with
+`release tarballs <https://mirrors.edge.kernel.org/pub/software/libs/libgpiod/>`_.
+
+Building
+--------
+
+This is a pretty standard autotools project. The core C library does not have
+any external dependencies other than the standard C library with GNU extensions.
+
+The build system requires the following packages to be installed on the host
+system for the basic build:
+
+ * ``autotools``
+ * ``autoconf-archive``
+ * ``libtool``
+ * ``pkg-config``
+
+.. note::
+ Development files for additional libraries may be required depending on
+ selected options. The configure script will report any missing additional
+ required dependencies.
+
+To build the project (including command-line utilities) run:
+
+.. code-block:: none
+
+ ./autogen.sh --enable-tools=yes
+ make
+
+.. note::
+ The command-line tools optionally depend on libedit for the interactive
+ feature.
+
+The autogen script will execute ``./configure`` and pass all the command-line
+arguments to it.
+
+.. note::
+ If building from release tarballs, the configure script is already provided
+ and there's no need to invoke autogen.sh.
+
+For all configure features, see: ``./configure --help``.
+
+Installing
+----------
+
+To install the project run:
+
+.. code-block:: none
+
+ make install
+
+.. note::
+ The above may require superuser privileges.
+
+This will install libgpiod under the default system paths. If you want to
+install it under non-standard path, pass the ``--prefix=<install path>``
+option to ``configure``.
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..e46d50f
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,45 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+ Contribution guide.
+
+Contributing
+============
+
+Contributions are welcome - please send questions, patches and bug reports to
+the `linux-gpio mailing list
+<http://vger.kernel.org/vger-lists.html#linux-gpio>`_
+by e-mailing to ``linux-gpio@vger.kernel.org`` (add the ``[libgpiod]`` prefix
+to the e-mail subject line). Note that the mailing list quietly drops HTML
+formatted e-mail, so be sure to `send plain text
+<https://docs.kernel.org/process/email-clients.html>`_.
+
+Code submissions should stick to the `linux kernel coding style
+<https://docs.kernel.org/process/coding-style.html>`_ and follow the kernel
+`patch submission process
+<https://docs.kernel.org/process/submitting-patches.html>`_ as applied to the
+libgpiod source tree. All shell scripts must pass `shellcheck tests
+<https://www.shellcheck.net/>`_. All files must have a license and copyright
+SPDX headers and the repo is expected to pass the `reuse lint check
+<https://reuse.software/>`_.
+
+The `mailing list archive <https://lore.kernel.org/linux-gpio/>`_ contains all
+the historical mails to the list, and is the place to check to ensure your
+e-mail has been received.
+Search for `"libgpiod"` to filter the list down to relevant messages. Those
+also provide examples of the expected formatting. Allow some time for your
+e-mail to propagate to the list before retrying, particularly if there are no
+e-mails in the list more recent than yours.
+
+There is a `libgpiod github page <https://github.com/brgl/libgpiod>`_
+available for reporting bugs and general discussions and although PRs can be
+submitted and discussed, upstreambound patches need to go through the mailing
+list nevertheless.
+
+.. note::
+ For more information, please refer to the ``CONTRIBUTING.md`` file in the
+ libgpiod source tree.
diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst
index 83a6aa4..4c76b56 100644
--- a/docs/cpp_api.rst
+++ b/docs/cpp_api.rst
@@ -15,6 +15,9 @@ core C API. These bindings make it easier to work with GPIO lines in C++ by
offering an **object-oriented** approach and **RAII** (Resource Acquisition
Is Initialization) principles for managing resources.
+.. note::
+ C++17 compiler support is required to build the bindings.
+
.. toctree::
:maxdepth: 1
:caption: Contents
diff --git a/docs/dbus.rst b/docs/dbus.rst
index 0dcbb81..98d2cbe 100644
--- a/docs/dbus.rst
+++ b/docs/dbus.rst
@@ -10,11 +10,24 @@
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
+A commonly requested feature for the GPIO character device was state persistence
+after releasing the lines (as a kernel feature) or providing a central authority
+(in user-space) that would be in charge of keeping the lines requested and in a
+certain state (similarily to how the sysfs ABI works). **GPIO D-Bus API** has
+been provided to address this requirement. We define an interface covering the
+majority of the GPIO chardev's functionality and implement it from both the
+server and client sides in the form of the **gpio-manager** daemon and the
+**gpiocli** command-line utility for talking to the manager. It enables
+relatively efficient, asynchronous control of GPIO lines, offering methods for
configuring, monitoring, and manipulating GPIOs.
+.. note::
+ DBus support can be built by passing ``--enable-dbus`` to configure. The
+ daemon is bundled with a systemd unit file and an example configuration file
+ for the ``io.gpiod1`` interface that allows all users to access basic
+ information about the GPIOs in the system but only root to request lines or
+ change their values.
+
.. toctree::
:maxdepth: 1
:caption: Contents
diff --git a/docs/glib_api.rst b/docs/glib_api.rst
index 307f5f7..f6d8665 100644
--- a/docs/glib_api.rst
+++ b/docs/glib_api.rst
@@ -15,6 +15,9 @@ 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.
+.. note::
+ GLib bindings require GLib (as well as GObject, GIO and GIO-Unix) v2.80.
+
.. warning::
The documentation for GObject bindings is generated using gi-docgen and
cannot be easily integrated with sphinx documentation. Please navigate to
diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst
index 7372de4..e4bf584 100644
--- a/docs/gpio_tools.rst
+++ b/docs/gpio_tools.rst
@@ -10,9 +10,29 @@
Command-line tools
==================
+Overview
+--------
+
The **libgpiod** project includes a suite of **command-line tools** to
facilitate GPIO manipulation from console and shell scripts.
+There are currently six command-line tools available:
+
+* **gpiodetect**: list all gpiochips present on the system, their names, labels
+ and number of GPIO lines
+* **gpioinfo**: list lines, their gpiochip, offset, name, and direction, and if
+ in use then the consumer name and any other configured attributes, such as
+ active state, bias, drive, edge detection and debounce period
+* **gpioget**: read values of specified GPIO lines
+* **gpioset**: set values of specified GPIO lines, holding the lines until the
+ process is killed or otherwise exits
+* **gpiomon**: wait for edge events on GPIO lines, specify which edges to watch
+ for, how many events to process before exiting, or if the events should be
+ reported to the console
+* **gpionotify**: wait for changed to the info for GPIO lines, specify which
+ changes to watch for, how many events to process before exiting, or if the
+ events should be reported to the console
+
.. toctree::
:maxdepth: 1
:caption: Manual entries
@@ -23,3 +43,199 @@ facilitate GPIO manipulation from console and shell scripts.
gpioset<gpioset>
gpiomon<gpiomon>
gpionotify<gpionotify>
+
+Examples
+--------
+
+.. note::
+ The following examples where creating using a Raspberry Pi 4B. The pins
+ will be different on other board.
+
+Detect the available gpiochips:
+
+.. code-block:: none
+
+ $ gpiodetect
+ gpiochip0 [pinctrl-bcm2711] (58 lines)
+ gpiochip1 [raspberrypi-exp-gpio] (8 lines)
+
+Read the info for all the lines on a gpiochip:
+
+.. code-block:: none
+
+ $ gpioinfo -c 1
+ gpiochip1 - 8 lines:
+ line 0: "BT_ON" output
+ line 1: "WL_ON" output
+ line 2: "PWR_LED_OFF" output active-low consumer="led1"
+ line 3: "GLOBAL_RESET" output
+ line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io"
+ line 5: "CAM_GPIO" output consumer="cam1_regulator"
+ line 6: "SD_PWR_ON" output consumer="sd_vcc_reg"
+ line 7: "SD_OC_N" input
+
+Read the info for particular lines:
+
+.. code-block:: none
+
+ $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET
+ gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0"
+ gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1"
+ gpiochip1 3 "GLOBAL_RESET" output
+
+Read the value of a single GPIO line by name:
+
+.. code-block:: none
+
+ $ gpioget RXD1
+ "RXD1"=active
+
+Read the value of a single GPIO line by chip and offset:
+
+.. code-block:: none
+
+ $ gpioget -c 0 15
+ "15"=active
+
+Read the value of a single GPIO line as a numeric value:
+
+.. code-block:: none
+
+ $ gpioget --numeric RXD1
+ 1
+
+Read two values at the same time, set the active state of the lines to low and
+without quoted names:
+
+.. code-block:: none
+
+ $ gpioget --active-low --unquoted GPIO23 GPIO24
+ GPIO23=active GPIO24=active
+
+Set the value of a line and hold the line until killed:
+
+.. code-block:: none
+
+ $ gpioset GPIO23=1
+
+Set values of two lines, then daemonize and hold the lines:
+
+.. code-block:: none
+
+ $ gpioset --daemonize GPIO23=1 GPIO24=0
+
+Set the value of a single line, hold it for 20ms, then exit:
+
+.. code-block:: none
+
+ $ gpioset --hold-period 20ms -t0 GPIO23=1
+
+Blink an LED on GPIO22 at 1Hz:
+
+.. code-block:: none
+
+ $ gpioset -t500ms GPIO22=1
+
+Blink an LED on GPIO22 at 1Hz with a 20% duty cycle:
+
+.. code-block:: none
+
+ $ gpioset -t200ms,800ms GPIO22=1
+
+Set some lines interactively (requires ``--enable-gpioset-interactive``):
+
+.. code-block:: none
+
+ $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active
+ gpioset> get
+ GPIO23=inactive GPIO24=active
+ gpioset> toggle
+ gpioset> get
+ GPIO23=active GPIO24=inactive
+ gpioset> set GPIO24=1
+ gpioset> get
+ GPIO23=active GPIO24=active
+ gpioset> toggle
+ gpioset> get
+ GPIO23=inactive GPIO24=inactive
+ gpioset> toggle GPIO23
+ gpioset> get
+ GPIO23=active GPIO24=inactive
+ gpioset> exit
+
+Wait for three rising edge events on a single GPIO line, then exit:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=3 --edges=rising GPIO22
+ 10002.907638045 rising "GPIO22"
+ 10037.132562259 rising "GPIO22"
+ 10047.179790748 rising "GPIO22"
+
+Wait for three edge events on a single GPIO line, with time in local time and
+with unquoted line name, then exit:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22
+ 2022-11-15T10:36:59.109615508 rising GPIO22
+ 2022-11-15T10:36:59.129681898 falling GPIO22
+ 2022-11-15T10:36:59.698971886 rising GPIO22
+
+Wait for falling edge events with a custom output format:
+
+.. code-block:: none
+
+ $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22
+ 2 gpiochip0 22 GPIO22 10946.693481859
+ 2 gpiochip0 22 GPIO22 10947.025347604
+ 2 gpiochip0 22 GPIO22 10947.283716669
+ 2 gpiochip0 22 GPIO22 10947.570109430
+ ...
+
+Block until an edge event occurs, don't print anything:
+
+.. code-block:: none
+
+ $ gpiomon --num-events=1 --quiet GPIO22
+
+Monitor multiple lines, exit after the first edge event:
+
+.. code-block:: none
+
+ $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17
+
+Monitor a line for changes to info:
+
+.. code-block:: none
+
+ $ gpionotify GPIO23
+ 11571.816473718 requested "GPIO23"
+ 11571.816535124 released "GPIO23"
+ 11572.722894029 requested "GPIO23"
+ 11572.722932843 released "GPIO23"
+ 11573.222998598 requested "GPIO23"
+ ...
+
+Monitor a line for requests, reporting UTC time and unquoted line name:
+
+.. code-block:: none
+
+ $ gpionotify --utc --unquoted GPIO23
+ 2022-11-15T03:05:23.807090687Z requested GPIO23
+ 2022-11-15T03:05:23.807151390Z released GPIO23
+ 2022-11-15T03:05:24.784984280Z requested GPIO23
+ 2022-11-15T03:05:24.785023873Z released GPIO23
+ ...
+
+Monitor multiple lines, exit after the first is requested:
+
+.. code-block:: none
+
+ $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17
+
+Block until a line is released:
+
+.. code-block:: none
+
+ $ gpionotify --quiet --num-events=1 --event=released GPIO6
diff --git a/docs/gpiocli_top.rst b/docs/gpiocli_top.rst
index 52e3295..3b50b91 100644
--- a/docs/gpiocli_top.rst
+++ b/docs/gpiocli_top.rst
@@ -10,6 +10,87 @@
Command-line client
===================
+With the manager running the user can run ``gpiocli`` to control GPIOs by
+asking the ``gpio-manager`` to act on their behalf.
+
+Examples
+--------
+
+Detect chips in the system:
+
+.. code-block:: none
+
+ $ gpiocli detect
+ gpiochip0 [INT34C6:00] (463 lines)
+
+Request a set of lines:
+
+.. note::
+ **gpiocli** exits immediately but the state of the lines is retained
+ because it's the **gpio-manager** that requested them.
+
+.. code-block:: none
+
+ $ gpiocli request --output foo=active
+ request0
+
+Previous invocation printed out the name of the request by which the caller
+can refer to it later. All active requests can also be inspected at any time:
+
+.. code-block:: none
+
+ $ gpiocli requests
+ request0 (gpiochip1) Offsets: [5]
+
+
+Print the information about the requested line using the information above:
+
+.. code-block:: none
+
+ $ gpiocli info --chip=gpiochip1 5
+ gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull]
+
+Change the value of the line:
+
+.. code-block:: none
+
+ $ gpiocli set foo=inactive
+
+Read it back:
+
+.. code-block:: none
+
+ $ gpiocli get foo
+ "foo"=inactive
+
+We can even reconfigure it to input and enable edge-detection:
+
+.. code-block:: none
+
+ $ gpiocli reconfigure --input --both-edges request0
+
+And wait for edge events:
+
+.. code-block:: none
+
+ $ gpiocli monitor cos
+ 21763952894920 rising "foo"
+
+And finally release the request:
+
+.. code-block:: none
+
+ $ gpiocli release request0
+
+.. note::
+ For more information please refer to the output of ``gpiocli --help`` as
+ well as ``gpiocli <command> --help`` which prints detailed info on every
+ available command.
+
+.. note::
+ Users can talk to **gpio-manager** using any **D-Bus** library available
+ and are not limited to the provided client.
+
.. toctree::
:maxdepth: 1
:caption: Manual entries
diff --git a/docs/index.rst b/docs/index.rst
index 3101e14..8c02c6a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,17 +14,30 @@ The **libgpiod** project provides a low-level C library, bindings to high-level
languages and tools for interacting with the GPIO (General Purpose Input/Output)
lines on Linux systems.
-It replaces the older, legacy GPIO sysfs interface, which has been deprecated
-in the Linux kernel. The newer GPIO character device interface (introduced in
-Linux kernel version 4.8) provides a more flexible and efficient way to
-interact with GPIO lines, and libgpiod is the primary tool for working with
-this interface.
+It replaces the older, **legacy GPIO sysfs interface**, which has been
+deprecated in the Linux kernel. The newer **GPIO character device** interface
+(introduced in **Linux kernel version 4.8**) provides a more flexible and
+efficient way to interact with GPIO lines, and libgpiod is the **primary tool**
+for working with this interface.
+
+The character device interface guarantees all allocated resources are freed
+after closing the device file descriptor and adds several new features that
+are not present in the obsolete sysfs interface (like reliable event polling,
+setting/reading multiple values at once or open-source and open-drain GPIOs).
+
+Unfortunately interacting with the linux device file can no longer be done
+using only standard command-line tools. This is the reason for creating a
+library encapsulating the cumbersome, ioctl-based kernel-userspace interaction
+in a set of convenient functions and opaque data structures.
.. toctree::
:maxdepth: 1
:caption: Contents
+ building
core_api
bindings
gpio_tools
dbus
+ testing
+ contributing
diff --git a/docs/python_api.rst b/docs/python_api.rst
index 00b30cb..2c4f59d 100644
--- a/docs/python_api.rst
+++ b/docs/python_api.rst
@@ -17,6 +17,10 @@ easily through Python scripts, enabling tasks such as reading input values,
setting outputs, monitoring events, and configuring more fine-grained pin
options.
+.. note::
+ Python bindings require python3 support and libpython development files for
+ building from sources.
+
.. toctree::
:maxdepth: 1
:caption: Contents
@@ -31,3 +35,7 @@ options.
python_line_settings
python_line_request
python_misc
+
+.. note::
+ Python bindings can be installed from https://pypi.org/ with pip by running
+ ``pip install gpiod``.
diff --git a/docs/testing.rst b/docs/testing.rst
new file mode 100644
index 0000000..e645e71
--- /dev/null
+++ b/docs/testing.rst
@@ -0,0 +1,46 @@
+..
+ SPDX-License-Identifier: CC-BY-SA-4.0
+ SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+
+..
+ This file is part of libgpiod.
+
+ Contribution guide.
+
+Testing
+=======
+
+A comprehensive testing framework is included with the library and can be used
+to test both the core library code as well as the kernel-to-user-space
+interface.
+
+The minimum kernel version required to run the tests can be checked in the
+``tests/gpiod-test.c`` source file (it's subject to change if new features are
+added to the kernel). The tests work together with the **gpio-sim** kernel
+module which must either be built-in or available for loading using kmod.
+A helper library - **libgpiosim** - is included to enable straightforward
+interaction with the module.
+
+To build the testing executable add the ``--enable-tests`` option when running
+the configure script. If enabled, the tests will be installed next to
+**gpio-tools**.
+
+As opposed to standard autotools projects, libgpiod doesn't execute any tests
+when invoking ``make check``. Instead the user must run them manually with
+superuser privileges.
+
+The testing framework uses the **GLib unit testing** library so development
+package for GLib must be installed.
+
+The **gpio-tools** programs can be tested separately using the
+``gpio-tools-test.bash`` script. It requires `shunit2
+<https://github.com/kward/shunit2>`_ to run and assumes that the tested
+executables are in the same directory as the script.
+
+C++, Rust and Python bindings also include their own test-suites. All three
+reuse the **libgpiosim** library to avoid code duplication when interacting
+with **gpio-sim**.
+
+Python test-suite uses the standard unittest package. C++ tests use an external
+testing framework - **Catch2** - which must be installed in the system. Rust
+bindings use the standard tests module layout and the ``#[test]`` attribute.
--
2.45.2
^ permalink raw reply related [flat|nested] 23+ messages in thread* RE: [External] - [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs
2025-02-06 12:22 ` [PATCH libgpiod v3 16/16] doc: move README contents to sphinx docs Bartosz Golaszewski
@ 2025-02-10 13:48 ` Vincent Fazio
0 siblings, 0 replies; 23+ messages in thread
From: Vincent Fazio @ 2025-02-10 13:48 UTC (permalink / raw)
To: Bartosz Golaszewski, Kent Gibson, Linus Walleij, Erik Schilling,
Phil Howard, Viresh Kumar
Cc: Bartosz Golaszewski, linux-gpio@vger.kernel.org
> -----Original Message-----
> From: Bartosz Golaszewski <brgl@bgdev.pl>
> Sent: Thursday, February 6, 2025 6:22 AM
> To: Vincent Fazio <vfazio@xes-inc.com>; Kent Gibson
> <warthog618@gmail.com>; Linus Walleij <linus.walleij@linaro.org>; Erik
> Schilling <erik.schilling@linaro.org>; Phil Howard <phil@gadgetoid.com>;
> Viresh Kumar <viresh.kumar@linaro.org>
> Cc: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>; linux-
> gpio@vger.kernel.org
> Subject: [External] - [PATCH libgpiod v3 16/16] doc: move README contents
> to sphinx docs
>
> From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
>
> We now have comprehensive documentation available online on
> readthedocs.
> Let's not duplicate docs in README - move all information into the
> sphinx files.
>
> While at it: make the remaining README use markdown.
>
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> ---
> README | 384 --------------------------------------------------
> README.md | 11 ++
> docs/bindings.rst | 25 +++-
> docs/building.rst | 74 ++++++++++
> docs/contributing.rst | 45 ++++++
> docs/cpp_api.rst | 3 +
> docs/dbus.rst | 19 ++-
> docs/glib_api.rst | 3 +
> docs/gpio_tools.rst | 216 ++++++++++++++++++++++++++++
> docs/gpiocli_top.rst | 81 +++++++++++
> docs/index.rst | 23 ++-
> docs/python_api.rst | 8 ++
> docs/testing.rst | 46 ++++++
> 13 files changed, 544 insertions(+), 394 deletions(-)
>
> diff --git a/docs/bindings.rst b/docs/bindings.rst
> index 73f1262..7f0f6b7 100644
> --- a/docs/bindings.rst
> +++ b/docs/bindings.rst
> @@ -10,8 +10,12 @@
> High-level language bindings to libgpiod
> ========================================
>
> -The bindings provide a more straightforward interface to the base, low-level
> -C library.
> +Bindings provide a more straightforward interface to the core, low-level
> +C library. Object-oriented bindings for C++, GLib, python3 and Rust are
> +provided as part of the project. They can be enabled by passing
> +``--enable-bindings-cxx``, ``--enable-bindings-glib``,
> +``--enable-bindings-python`` and ``--enable-bindings-rust`` arguments to
> +configure respectively.
>
> .. toctree::
> :maxdepth: 1
> @@ -20,3 +24,20 @@ C library.
> cpp_api
> python_api
> glib_api
> +
> +.. 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.
> +
> +.. note::
> + Rust bindings 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.
> +
Minor, but I get whitespace warnings when applying
Applying: doc: move README contents to sphinx docs
.git/rebase-apply/patch:457: trailing whitespace.
.git/rebase-apply/patch:463: new blank line at EOF.
+
warning: 2 lines add whitespace errors.
.. note::
Rust bindings 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.
-
^ permalink raw reply [flat|nested] 23+ messages in thread