doc: improvements for ReadTheDocs
v4 cover doc: improvements for ReadTheDocs
One thing that this project is missing is nicely looking, accessible and automatically updated documentation. I'd like to finally address it and replace our static doxygen pages with sphinx docs.
I spent some time playing with sphinx, doxygen, breathe and exhale. It turned out that exhale doesn't support doxygen groups and I really want to have them for the core C API to avoid having to manually assign each function to a specific module. That means we must use breathe on its own to integrate our existing doxygen docs with .rst.
First 10 preparatory patches address existing issues in code documentation. Patches 11-15 add sphinx docs for all project sections and last patch moves most README contents into sphinx as well.
I allowed myself to publish this branch on RTD for testing purposes.
Once this is merged, I'l backport these changes to the v2.2.x branch so that the documentation for the most recent release can become available online too.
---
Changes in v4:
- remove unconditional docs for __init__() in the python section, use :class-doc-from: both instead for LineRequest
- fix make docs failure with GObject introspection not being found
- fix make clean for sphinx and doxygen output
- fix commit message typos
- fix whitespace errors
- Link to v3: https://lore.kernel.org/r/[email protected]
Changes in v3:
- make the commits more fine-grained: add a separate commit for each new documentation section
- set the PACKAGE_URL in configure.ac
- add GLib docs
- add gpio-tools docs
- generate man pages for D-Bus programs
- add docs for D-Bus API and utilities
- reduce the top toc tree depth to 1
- change license of .rst files to CC-BY-SA-4.0
- move most of the README contents into sphinx docs
- many other minor tweaks
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- update .readthedocs.yaml
- add requirements.txt in order for rtd to install breathe
- mv doc docs
- a couple minor improvements
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Bartosz Golaszewski (17):
build: set PACKAGE_URL
bindings: cxx: doc: remove the gpiod_cxx doxygen group
bindings: python: doc: update the docstring for gpiod.request_lines()
bindings: python: doc: make code examples appear as such in sphinx
bindings: python: doc: describe undocumented members
bindings: gpiod: reword the docstring for LineRequest.__init__()
bindings: glib: add the configuration file for gi-docgen
dbus: daemon: add a more detailed description to help text
dbus: client: tweak help text
dbus: improve comments in API xml
doc: create man entries for gpio-manager and gpiocli
doc: provide sphinx docs for the core C API and C++ bindings
doc: add documentation for python bindings
doc: add documentation for GLib bindings
doc: add documentation for gpio-tools
doc: add documentation for D-Bus API, daemon and command-line client
doc: move README contents to sphinx docs
.gitignore | 2 - .readthedocs.yaml | 25 +- Doxyfile.in | 105 -------- Makefile.am | 24 +- README | 386 ---------------------------- README.md | 11 + 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 - bindings/glib/.gitignore | 1 + bindings/glib/Makefile.am | 6 +- bindings/glib/gi-docgen.toml.in | 9 + bindings/python/gpiod/__init__.py | 15 +- bindings/python/gpiod/chip.py | 4 +- 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_request.py | 6 +- bindings/python/gpiod/line_settings.py | 8 + configure.ac | 33 ++- dbus/client/gpiocli.c | 2 +- dbus/lib/io.gpiod1.xml | 98 +++---- dbus/manager/gpio-manager.c | 9 + docs/.gitignore | 19 ++ docs/Doxyfile | 12 + docs/Makefile.am | 61 +++++ docs/bindings.rst | 27 ++ docs/building.rst | 74 ++++++ docs/conf.py | 137 ++++++++++ docs/contributing.rst | 45 ++++ 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 | 37 +++ 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/dbus.rst | 37 +++ docs/dbus_api.rst | 23 ++ docs/glib_api.rst | 26 ++ docs/gpio_tools.rst | 241 +++++++++++++++++ docs/gpiocli_top.rst | 110 ++++++++ docs/index.rst | 43 ++++ docs/python_api.rst | 41 +++ 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 | 13 + docs/python_line_settings.rst | 12 + docs/python_misc.rst | 13 + docs/requirements.txt | 5 + docs/rust_api.rst | 23 ++ docs/testing.rst | 46 ++++ include/gpiod.h | 36 --- man/Makefile.am | 72 +++++- sphinx/conf.py | 68 ----- sphinx/contents.rst | 24 -- 95 files changed, 1793 insertions(+), 859 deletions(-)
---
base-commit: 5486f1f0ffa419bcbb25288b0157c8e2ab643403
change-id: 20241216-improve-docs-19ed36687963
Best regards,
Signature · 1 line
Bartosz Golaszewski <[email protected]>
PATCH v4 1/17 build: set PACKAGE_URL
From: Bartosz Golaszewski <[email protected]>
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.
--- configure.ac | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
configure.ac +2 -1
@@ -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],
Signature · 1 line
2.45.2
PATCH v4 2/17 bindings: cxx: doc: remove the gpiod_cxx doxygen group
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- 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(-)
bindings/cxx/gpiod.hpp +0 -6
@@ -8,12 +8,6 @@ #ifndef __LIBGPIOD_GPIOD_CXX_HPP__ #define __LIBGPIOD_GPIOD_CXX_HPP__ -/** - * @defgroup gpiod_cxx C++ bindings - * - * C++ bindings for libgpiod. - */ - /** * @cond */
bindings/cxx/gpiodcxx/chip-info.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/chip.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/edge-event-buffer.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/edge-event.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/exception.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/info-event.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/line-config.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/line-info.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/line-request.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/line-settings.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/line.hpp +0 -9
@@ -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 */
bindings/cxx/gpiodcxx/misc.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/request-builder.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/request-config.hpp +0 -9
@@ -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__ */
bindings/cxx/gpiodcxx/timestamp.hpp +0 -9
@@ -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__ */
Signature · 1 line
2.45.2
PATCH v4 3/17 bindings: python: doc: update the docstring for gpiod.request_lines()
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- bindings/python/gpiod/__init__.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-)
bindings/python/gpiod/__init__.py +12 -3
@@ -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.
Signature · 1 line
2.45.2
PATCH v4 4/17 bindings: python: doc: make code examples appear as such in sphinx
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
In order for code examples inside docstrings to be interpreted as such by sphinx, we need to use a double colon ("Example::").
--- bindings/python/gpiod/chip.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
bindings/python/gpiod/chip.py +2 -2
@@ -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)
Signature · 1 line
2.45.2
PATCH v4 5/17 bindings: python: doc: describe undocumented members
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
There are several public members in python bindings that are missing docstrings. Document them for completeness.
--- 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(+)
bindings/python/gpiod/chip_info.py +5 -0
@@ -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}>'
bindings/python/gpiod/edge_event.py +9 -0
@@ -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,
bindings/python/gpiod/info_event.py +8 -0
@@ -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))
bindings/python/gpiod/line.py +20 -0
@@ -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."""
bindings/python/gpiod/line_info.py +12 -0
@@ -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,
bindings/python/gpiod/line_settings.py +8 -0
@@ -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>
Signature · 1 line
2.45.2
PATCH v4 6/17 bindings: gpiod: reword the docstring for LineRequest.__init__()
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
Change the docstring for LineRequest.__init__() so that when it appears in sphinx docs as part of the class description, it won't sound as if the class was not to be used at all.
--- bindings/python/gpiod/line_request.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
bindings/python/gpiod/line_request.py +2 -4
@@ -29,10 +29,8 @@ class LineRequest: def __init__(self, req: _ext.Request): """ - DON'T USE - - LineRequest objects can only be instantiated by a Chip parent. This is - not part of stable API. + Note: LineRequest objects can only be instantiated by a Chip parent. + LineRequest.__init__() is not part of stable API. """ self._req: Union[_ext.Request, None] = req self._chip_name: str
Signature · 1 line
2.45.2
PATCH v4 7/17 bindings: glib: add the configuration file for gi-docgen
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- 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(-)
bindings/glib/.gitignore +1 -0
@@ -4,3 +4,4 @@ *.gir *.typelib Gpiodglib-1.0 +gi-docgen.toml
bindings/glib/Makefile.am +4 -2
@@ -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
bindings/glib/gi-docgen.toml.in new file +9 -0
@@ -0,0 +1,9 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> + +[library] +description = "GObject bindings to libgpiod" +version = "@PACKAGE_VERSION@" +authors = "Bartosz Golaszewski" +license = "LGPL-2.1-or-later" +website_url = "@PACKAGE_URL@"
configure.ac +1 -0
@@ -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
Signature · 1 line
2.45.2
PATCH v4 8/17 dbus: daemon: add a more detailed description to help text
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- dbus/manager/gpio-manager.c | 9 +++++++++ 1 file changed, 9 insertions(+)
dbus/manager/gpio-manager.c +9 -0
@@ -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);
Signature · 1 line
2.45.2
PATCH v4 9/17 dbus: client: tweak help text
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- dbus/client/gpiocli.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
dbus/client/gpiocli.c +1 -1
@@ -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 );
Signature · 1 line
2.45.2
PATCH v4 10/17 dbus: improve comments in API xml
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- dbus/lib/io.gpiod1.xml | 98 ++++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 46 deletions(-)
dbus/lib/io.gpiod1.xml +52 -46
@@ -1,5 +1,5 @@ <!-- SPDX-License-Identifier: CC-BY-SA-4.0 --> -<!-- SPDX-FileCopyrightText: 2022-2024 Bartosz Golaszewski <[email protected]> --> +<!-- SPDX-FileCopyrightText: 2022-2025 Bartosz Golaszewski <[email protected]> --> <!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)'/>
Signature · 1 line
2.45.2
PATCH v4 11/17 doc: create man entries for gpio-manager and gpiocli
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
Extend the build files under man/ to also generate man pages for gpio-manager, gpiocli and each of the former's sub-commands.
--- Makefile.am | 8 ++++++- man/Makefile.am | 72 +++++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 67 insertions(+), 13 deletions(-)
Makefile.am +7 -1
@@ -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
man/Makefile.am +60 -12
82 lines not on this page · raw message
Signature · 1 line
2.45.2
PATCH v4 12/17 doc: provide sphinx docs for the core C API and C++ bindings
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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 ./docs/ docs/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.
--- .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, 591 insertions(+), 259 deletions(-)
.gitignore +0 -2
@@ -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
.readthedocs.yaml +8 -8
@@ -1,5 +1,6 @@ # SPDX-License-Identifier: LGPL-2.1-or-later # SPDX-FileCopyrightText: 2022 Kent Gibson <[email protected]> +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]> # # 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
Doxyfile.in deleted +0 -105
105 lines not on this page · raw message
Makefile.am +5 -7
@@ -50,15 +50,13 @@ SUBDIRS += man endif -if HAS_DOXYGEN +if WITH_DOCS -doc: Doxyfile - $(AM_V_GEN)doxygen Doxyfile -.PHONY: doc +SUBDIRS += docs -clean-local: - rm -rf doc +docs: + $(MAKE) -C docs docs -EXTRA_DIST += Doxyfile +.PHONY: docs endif
README +5 -7
@@ -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.
configure.ac +7 -2
@@ -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
docs/.gitignore new file +5 -0
@@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +doxygen-output +sphinx-output
docs/Doxyfile new file +12 -0
@@ -0,0 +1,12 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 +# SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <[email protected]> + +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
docs/Makefile.am new file +45 -0
45 lines not on this page · raw message
docs/bindings.rst new file +20 -0
@@ -0,0 +1,20 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/conf.py new file +53 -0
53 lines not on this page · raw message
docs/core_api.rst new file +62 -0
62 lines not on this page · raw message
docs/core_chip_info.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygengroup:: chip_info
docs/core_chips.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygengroup:: chips
docs/core_edge_event.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygengroup:: edge_event
docs/core_line_config.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygengroup:: line_config
docs/core_line_defs.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line definitions +===================== + +.. doxygengroup:: line_defs
docs/core_line_info.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line information +===================== + +.. doxygengroup:: line_info
docs/core_line_request.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line request +================== + +.. doxygengroup:: line_request
docs/core_line_settings.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygengroup:: line_settings
docs/core_line_watch.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line watch +=============== + +.. doxygengroup:: line_watch
docs/core_misc.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +libgpiod misc interfaces +======================== + +.. doxygengroup:: misc
docs/core_request_config.rst new file +11 -0
@@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygengroup:: request_config
docs/cpp_api.rst new file +34 -0
@@ -0,0 +1,34 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/cpp_chip.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygenclass:: gpiod::chip + :members:
docs/cpp_chip_info.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygenclass:: gpiod::chip_info + :members:
docs/cpp_edge_event.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygenclass:: gpiod::edge_event + :members:
docs/cpp_edge_event_buffer.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO edge event buffer +====================== + +.. doxygenclass:: gpiod::edge_event_buffer + :members:
docs/cpp_exceptions.rst new file +18 -0
@@ -0,0 +1,18 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +libgpiod exceptions +=================== + +.. doxygenclass:: gpiod::chip_closed + :members: + +.. doxygenclass:: gpiod::request_released + :members: + +.. doxygenclass:: gpiod::bad_mapping + :members:
docs/cpp_info_event.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. doxygenclass:: gpiod::info_event + :members:
docs/cpp_line.rst new file +24 -0
@@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/cpp_line_config.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygenclass:: gpiod::line_config + :members:
docs/cpp_line_info.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line info +============== + +.. doxygenclass:: gpiod::line_info + :members:
docs/cpp_line_request.rst new file +15 -0
@@ -0,0 +1,15 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. doxygenclass:: gpiod::request_builder + :members: + +.. doxygenclass:: gpiod::line_request + :members:
docs/cpp_line_settings.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygenclass:: gpiod::line_settings + :members:
docs/cpp_misc.rst new file +16 -0
@@ -0,0 +1,16 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +libgpiodcxx misc interfaces +=========================== + +.. doxygenclass:: gpiod::timestamp + :members: + +.. doxygenfunction:: gpiod::is_gpiochip_device + +.. doxygenfunction:: gpiod::api_version
docs/cpp_request_config.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygenclass:: gpiod::request_config + :members:
docs/index.rst new file +28 -0
@@ -0,0 +1,28 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/requirements.txt new file +5 -0
@@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +breathe==4.35.0 +sphinx-rtd-theme==3.0.2
include/gpiod.h +0 -36
@@ -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 * @{
sphinx/conf.py deleted +0 -68
68 lines not on this page · raw message
sphinx/contents.rst deleted +0 -24
@@ -1,24 +0,0 @@ -.. - SPDX-License-Identifier: LGPL-2.1-or-later - SPDX-FileCopyrightText: 2022 Kent Gibson <[email protected]> - -.. - 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`
Signature · 1 line
2.45.2
PATCH v4 13/17 doc: add documentation for python bindings
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
Integrate python docs with sphinx using autodoc and the import mock feature which allows us to avoid having to build the C extension.
--- docs/Makefile.am | 13 ++++++++++++- docs/bindings.rst | 1 + docs/conf.py | 6 +++++- 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 | 13 +++++++++++++ docs/python_line_settings.rst | 12 ++++++++++++ docs/python_misc.rst | 13 +++++++++++++ 14 files changed, 193 insertions(+), 2 deletions(-)
docs/Makefile.am +12 -1
@@ -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) pushd ..; sphinx-build ./docs/ ./docs/sphinx-output; popd
docs/bindings.rst +1 -0
@@ -18,3 +18,4 @@ C library. :caption: Contents cpp_api + python_api
docs/conf.py +5 -1
@@ -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:
docs/python_api.rst new file +33 -0
@@ -0,0 +1,33 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/python_chip.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. autoclass:: gpiod.Chip + :members:
docs/python_chip_info.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. autoclass:: gpiod.ChipInfo + :members:
docs/python_edge_event.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. autoclass:: gpiod.EdgeEvent + :members:
docs/python_exceptions.rst new file +17 -0
@@ -0,0 +1,17 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +libgpiod python errors +====================== + +.. autoclass:: gpiod.ChipClosedError + :members: + :show-inheritance: + +.. autoclass:: gpiod.RequestReleasedError + :members: + :show-inheritance:
docs/python_info_event.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. autoclass:: gpiod.InfoEvent + :members:
docs/python_line.rst new file +27 -0
@@ -0,0 +1,27 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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:
docs/python_line_info.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line info +============== + +.. autoclass:: gpiod.LineInfo + :members:
docs/python_line_request.rst new file +13 -0
@@ -0,0 +1,13 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. autoclass:: gpiod.LineRequest + :members: + :class-doc-from: both
docs/python_line_settings.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. autoclass:: gpiod.LineSettings + :members:
docs/python_misc.rst new file +13 -0
@@ -0,0 +1,13 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +libgpiod python bindings misc +============================= + +.. autofunction:: gpiod.is_gpiochip_device + +.. autofunction:: gpiod.request_lines
Signature · 1 line
2.45.2
PATCH v4 14/17 doc: add documentation for GLib bindings
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- .readthedocs.yaml | 9 ++++++++- docs/Makefile.am | 1 + docs/bindings.rst | 1 + docs/conf.py | 41 +++++++++++++++++++++++++++++++++++++++++ docs/glib_api.rst | 23 +++++++++++++++++++++++ 5 files changed, 74 insertions(+), 1 deletion(-)
.readthedocs.yaml +8 -1
@@ -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
docs/Makefile.am +1 -0
@@ -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 \
docs/bindings.rst +1 -0
@@ -19,3 +19,4 @@ C library. cpp_api python_api + glib_api
docs/conf.py +41 -0
45 lines not on this page · raw message
docs/glib_api.rst new file +23 -0
@@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + 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>`_
Signature · 1 line
2.45.2
PATCH v4 15/17 doc: add documentation for gpio-tools
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
We already generate man pages for gpio-tools. Let's use man2html to make them part of the sphinx docs.
--- .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(-)
.readthedocs.yaml +2 -0
@@ -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:
configure.ac +19 -13
@@ -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
docs/.gitignore +8 -0
@@ -3,3 +3,11 @@ doxygen-output sphinx-output + +# Automatically generated .rst +gpiodetect.rst +gpioinfo.rst +gpioget.rst +gpioset.rst +gpiomon.rst +gpionotify.rst
docs/Makefile.am +1 -0
@@ -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 \
docs/conf.py +22 -0
@@ -91,8 +91,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, + )
docs/gpio_tools.rst new file +25 -0
@@ -0,0 +1,25 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> + +.. + 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>
docs/index.rst +1 -0
@@ -26,3 +26,4 @@ this interface. core_api bindings + gpio_tools
Signature · 1 line
2.45.2
PATCH v4 16/17 doc: add documentation for D-Bus API, daemon and command-line client
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
Use the man pages for gpio-manager and gpiocli + some manual labor to provide sphinx docs for the libgpiod D-Bus API.
--- .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(+)
.readthedocs.yaml +2 -0
@@ -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
docs/.gitignore +6 -0
@@ -11,3 +11,9 @@ gpioget.rst gpioset.rst gpiomon.rst gpionotify.rst + +gpio-manager.rst + +dbus-io.gpiod1.*.rst +gpiocli.rst +gpiocli-*.rst
docs/Makefile.am +3 -0
@@ -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 \
docs/conf.py +17 -0
@@ -92,6 +92,7 @@ subprocess.run( "--enable-bindings-glib", "--enable-introspection", "--enable-tools", + "--enable-dbus", ], check=True, )
@@ -105,6 +106,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( [
@@ -118,3 +133,5 @@ for page in [ ], check=True, ) + +subprocess.run(["gdbus-codegen", "--generate-rst", "dbus", "../dbus/lib/io.gpiod1.xml"])
docs/dbus.rst new file +24 -0
@@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/dbus_api.rst new file +23 -0
@@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> + +.. + 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
docs/gpiocli_top.rst new file +29 -0
@@ -0,0 +1,29 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> + +.. + 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>
docs/index.rst +1 -0
@@ -27,3 +27,4 @@ this interface. core_api bindings gpio_tools + dbus
Signature · 1 line
2.45.2
PATCH v4 17/17 doc: move README contents to sphinx docs
In reply to Bartosz GolaszewskiFrom: Bartosz Golaszewski <[email protected]>
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.
--- README | 384 -------------------------------------------------- README.md | 11 ++ docs/bindings.rst | 9 +- 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/rust_api.rst | 23 +++ docs/testing.rst | 46 ++++++ 14 files changed, 551 insertions(+), 394 deletions(-)
README deleted +0 -384
@@ -1,384 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski <[email protected]> - -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 [email protected] -(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/
README.md new file +11 -0
@@ -0,0 +1,11 @@ +<!-- SPDX-License-Identifier: CC-BY-SA-4.0 --> +<!-- SPDX-FileCopyrightText: 2025 Bartosz Golaszewski <[email protected]> --> + +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/.
docs/bindings.rst +7 -2
@@ -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,4 @@ C library. cpp_api python_api glib_api + rust_api
docs/building.rst new file +74 -0
74 lines not on this page · raw message
docs/contributing.rst new file +45 -0
45 lines not on this page · raw message
docs/cpp_api.rst +3 -0
@@ -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
docs/dbus.rst +16 -3
@@ -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
docs/glib_api.rst +3 -0
@@ -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
docs/gpio_tools.rst +216 -0
228 lines not on this page · raw message
docs/gpiocli_top.rst +81 -0
87 lines not on this page · raw message
docs/index.rst +18 -5
@@ -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
docs/python_api.rst +8 -0
@@ -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``.
docs/rust_api.rst new file +23 -0
@@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski <[email protected]> + +.. + This file is part of libgpiod. + +Where are the Rust bindings? +============================= + +.. 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. + +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.
docs/testing.rst new file +46 -0
46 lines not on this page · raw message
Signature · 1 line
2.45.2
From: Bartosz Golaszewski <[email protected]>
Quoted 11 lines · Bartosz Golaszewski
One thing that this project is missing is nicely looking, accessible and automatically updated documentation. I'd like to finally address it and replace our static doxygen pages with sphinx docs.
I spent some time playing with sphinx, doxygen, breathe and exhale. It turned out that exhale doesn't support doxygen groups and I really want to have them for the core C API to avoid having to manually assign each function to a specific module. That means we must use breathe on its own to integrate our existing doxygen docs with .rst.
[...]
I'm happy with the series so let's merge it and start building the official docs from the master branch.
[01/17] build: set PACKAGE_URL
commit: 588a196abbebc82eaa3495a9db4e9edfbaa44ed9
[02/17] bindings: cxx: doc: remove the gpiod_cxx doxygen group
commit: e025e1cb5cbb5be933ab3d7b34cef2800a41eed1
[03/17] bindings: python: doc: update the docstring for gpiod.request_lines()
commit: 8aa4d84b6f8e2d5d5fbb1b5c23d0eab69f9bf72a
[04/17] bindings: python: doc: make code examples appear as such in sphinx
commit: b1bc6664f697c2aa693192d43f58d01b8210d3e5
[05/17] bindings: python: doc: describe undocumented members
commit: d46e8f67aa45e2acbe8b918ff9815628167aea9b
[06/17] bindings: gpiod: reword the docstring for LineRequest.__init__()
commit: 7ac26508931ce6aa8a5b2f9e45bcdeb4fb9d80a1
[07/17] bindings: glib: add the configuration file for gi-docgen
commit: d0139ffa9c02b594e36681d3bb2b48932b3d573d
[08/17] dbus: daemon: add a more detailed description to help text
commit: 681c0c2767944f668f2e6649ff0663ce4dbbcbd1
[09/17] dbus: client: tweak help text
commit: 1ddfa9fc4b5b58bcf11a8852c5b71a66223de9ac
[10/17] dbus: improve comments in API xml
commit: 91955a1f934452eafbc862de2b3392110cc338c0
[11/17] doc: create man entries for gpio-manager and gpiocli
commit: 3b4a2ced02138c2837f99bfd1ed3773390ded74a
[12/17] doc: provide sphinx docs for the core C API and C++ bindings
commit: 7e11886fffc095b9d3f211d49a49f96cfd73e578
[13/17] doc: add documentation for python bindings
commit: 07da46218683322a246dfe5eda317589cd822a58
[14/17] doc: add documentation for GLib bindings
commit: f37aaf2a6af66f22518091c7c58de596ff613010
[15/17] doc: add documentation for gpio-tools
commit: 6f8b77c712a30ebea4089d317f4f8617287341cc
[16/17] doc: add documentation for D-Bus API, daemon and command-line client
commit: bbcb5d44611d15d4db5d4f9fdb3362a0f84d7d10
[17/17] doc: move README contents to sphinx docs
commit: dda57bd63f220d57bf80e3c1411ee612befda011Best regards,
Signature · 1 line
Bartosz Golaszewski <[email protected]>