Skip to contentSkip to conversation

doc: improvements for ReadTheDocs

PATCH Superseded Bartosz Golaszewski 1 participant 6 messages Dec 22, 2024

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v2 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 four patches in this series address some issues with C++ and python docs that became apparent when I started integrating sphinx.

The final patch contains all the stuff sphinx needs to build us a nice website. If the RTD theme is available, then we're using it, otherwise let's fall back to the default theme.

Eventually I'd like to extend the documentation with examples, descriptions of gpio-tools and DBus API etc. but first let's agree this is the way forward. For now, the docs describe libgpiod, libgpiodcxx and python APIs.

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 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 (5):
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
doc: use sphinx in conjunction with doxygen

 .gitignore                                  |   2 -
 .readthedocs.yaml                           |  17 +++--
 Doxyfile.in                                 | 105 ----------------------------
 Makefile.am                                 |  57 +++++++++++++--
 README                                      |  12 ++--
 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/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_settings.py      |   8 +++
 configure.ac                                |   8 ++-
 docs/.gitignore                             |   5 ++
 docs/Doxyfile                               |  12 ++++
 docs/conf.py                                |  63 +++++++++++++++++
 docs/core_api.rst                           |  58 +++++++++++++++
 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                            |  33 +++++++++
 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/python_api.rst                         |  31 ++++++++
 docs/python_chip.rst                        |  12 ++++
 docs/python_chip_info.rst                   |  12 ++++
 docs/python_edge_event.rst                  |  12 ++++
 docs/python_exceptions.rst                  |  17 +++++
 docs/python_info_event.rst                  |  12 ++++
 docs/python_line.rst                        |  27 +++++++
 docs/python_line_info.rst                   |  12 ++++
 docs/python_line_request.rst                |  12 ++++
 docs/python_line_settings.rst               |  12 ++++
 docs/python_misc.rst                        |  13 ++++
 docs/requirements.txt                       |   5 ++
 include/gpiod.h                             |  36 ----------
 sphinx/conf.py                              |  68 ------------------
 sphinx/contents.rst                         |  24 -------
 75 files changed, 824 insertions(+), 405 deletions(-)

---
base-commit: 38adbae195555fae2b9d9e2a37c9507af1114757
change-id: 20241216-improve-docs-19ed36687963

Best regards,

Signature · 1 line
Bartosz Golaszewski <[email protected]>
#1 lore raw

PATCH v2 1/5 bindings: cxx: doc: remove the gpiod_cxx doxygen group

From: 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
index 91e41a5..606994d 100644
@@ -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
index e740e94..61c0b78 100644
@@ -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
index 4d67476..8a1389e 100644
@@ -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
index 2482e8a..083c2e1 100644
@@ -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
index 47c256a..acbe7af 100644
@@ -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
index 34737d2..b753af0 100644
@@ -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
index 69b88b6..ee01651 100644
@@ -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
index 58c9d87..b3b9aba 100644
@@ -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
index 8b10dc4..bf02ba1 100644
@@ -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
index fcc4e0e..9605019 100644
@@ -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
index 1004ccd..89d79f8 100644
@@ -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
index 2810571..c58bf11 100644
@@ -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
index eab8eba..cb56b92 100644
@@ -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
index 192bd91..62597b4 100644
@@ -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
index 6ebbf99..96f0262 100644
@@ -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
index fcb4d8d..dc44eb7 100644
@@ -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
#2 lore raw

PATCH v2 2/5 bindings: python: doc: update the docstring for gpiod.request_lines()

In reply to Bartosz Golaszewski

From: 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
index 817c755..854e41f 100644
@@ -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
#3 lore raw

PATCH v2 3/5 bindings: python: doc: make code examples appear as such in sphinx

In reply to Bartosz Golaszewski

From: 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
index ddd07b8..5641343 100644
@@ -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
#4 lore raw

PATCH v2 4/5 bindings: python: doc: describe undocumented members

In reply to Bartosz Golaszewski

From: 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
index 3306af2..737a45e 100644
@@ -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
index 7f5cd4d..c888cb2 100644
@@ -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
index 4a86697..cd2785e 100644
@@ -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
index 33c7368..0cfc854 100644
@@ -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
index 1aca142..d31565e 100644
@@ -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
index 2aca71c..3752acd 100644
@@ -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
#5 lore raw

PATCH v2 5/5 doc: use sphinx in conjunction with doxygen

In reply to Bartosz Golaszewski

From: Bartosz Golaszewski <[email protected]>

Integrate the API documentation generated with doxygen for the core C API and C++ bindings into sphinx using breathe. Integrate python docs with sphinx using autodoc and the import mock feature which allows us to avoid having to build the C extension.

Update configure.ac to check for sphinx-build in addition to doxygen and make the main Makefile trigger a sphinx build on make doc (although the docs can also be generated without starting the build system by
running: sphinx-build ./doc/ doc/sphinx-output).

Create a tree of .rst documents with branches for libgpiod, libgpiodcxx and python APIs.

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              |  17 ++++---
 Doxyfile.in                    | 105 -----------------------------------------
 Makefile.am                    |  57 +++++++++++++++++++---
 README                         |  12 ++---
 configure.ac                   |   8 +++-
 docs/.gitignore                |   5 ++
 docs/Doxyfile                  |  12 +++++
 docs/conf.py                   |  63 +++++++++++++++++++++++++
 docs/core_api.rst              |  58 +++++++++++++++++++++++
 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               |  33 +++++++++++++
 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/python_api.rst            |  31 ++++++++++++
 docs/python_chip.rst           |  12 +++++
 docs/python_chip_info.rst      |  12 +++++
 docs/python_edge_event.rst     |  12 +++++
 docs/python_exceptions.rst     |  17 +++++++
 docs/python_info_event.rst     |  12 +++++
 docs/python_line.rst           |  27 +++++++++++
 docs/python_line_info.rst      |  12 +++++
 docs/python_line_request.rst   |  12 +++++
 docs/python_line_settings.rst  |  12 +++++
 docs/python_misc.rst           |  13 +++++
 docs/requirements.txt          |   5 ++
 include/gpiod.h                |  36 --------------
 sphinx/conf.py                 |  68 --------------------------
 sphinx/contents.rst            |  24 ----------
 51 files changed, 748 insertions(+), 259 deletions(-)
.gitignore +0 -2
index c3a29d8..7b5fa15 100644
@@ -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 -9
index f40e95f..1243f11 100644
@@ -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,14 @@ 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"
+  #  doxygen is available by default, but just in case.
   apt_packages:
-      - autoconf
-      - autoconf-archive
-      - libtool
-      - m4
       - 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 +51 -6

66 lines not on this page · raw message

README +5 -7
index 80ad939..28a3dfd 100644
@@ -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 +6 -2
index 78a6670..88ee367 100644
@@ -326,12 +326,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
docs/.gitignore new file +5 -0
new file mode 100644
index 0000000..3793d27
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+doxygen-output
+sphinx-output
docs/Doxyfile new file +12 -0
new file mode 100644
index 0000000..e4e55f9
@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: CC0-1.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/conf.py new file +63 -0

63 lines not on this page · raw message

docs/core_api.rst new file +58 -0

58 lines not on this page · raw message

docs/core_chip_info.rst new file +11 -0
new file mode 100644
index 0000000..40a5ca6
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO chip info
+==============
+
+.. doxygengroup:: chip_info
docs/core_chips.rst new file +11 -0
new file mode 100644
index 0000000..758f365
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO chip
+=========
+
+.. doxygengroup:: chips
docs/core_edge_event.rst new file +11 -0
new file mode 100644
index 0000000..65ea53c
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..5dc8bcb
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..08ec6fc
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..e90059a
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..39b87ad
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..cc84345
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..61fc007
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO line watch
+===============
+
+.. doxygengroup:: line_watch
docs/core_misc.rst new file +11 -0
new file mode 100644
index 0000000..414a97a
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+libgpiod misc interfaces
+========================
+
+.. doxygengroup:: misc
docs/core_request_config.rst new file +11 -0
new file mode 100644
index 0000000..9433406
@@ -0,0 +1,11 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO request configuration
+==========================
+
+.. doxygengroup:: request_config
docs/cpp_api.rst new file +33 -0
new file mode 100644
index 0000000..8e6df40
@@ -0,0 +1,33 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
+
+   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
new file mode 100644
index 0000000..694a21c
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..ce9d07b
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..0be8fdd
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..2e044d0
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..2357a87
@@ -0,0 +1,18 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..b389d6f
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..adf23ad
@@ -0,0 +1,24 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..a3fc714
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..d2e8eeb
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..f2ae4f8
@@ -0,0 +1,15 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..e9bc067
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..ce6ba4c
@@ -0,0 +1,16 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..476cfa6
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..b7cb6ef
@@ -0,0 +1,28 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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: 2
+
+   core_api
+   cpp_api
+   python_api
docs/python_api.rst new file +31 -0
new file mode 100644
index 0000000..a90afe6
@@ -0,0 +1,31 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
+
+   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
new file mode 100644
index 0000000..83d34bd
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..8116ef7
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..6c77a38
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..c247321
@@ -0,0 +1,17 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..6d32368
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..3a63ae5
@@ -0,0 +1,27 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..2e0faeb
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO line info
+==============
+
+.. autoclass:: gpiod.LineInfo
+   :members:
docs/python_line_request.rst new file +12 -0
new file mode 100644
index 0000000..47fa734
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+GPIO line request
+=================
+
+.. autoclass:: gpiod.LineRequest
+   :members:
docs/python_line_settings.rst new file +12 -0
new file mode 100644
index 0000000..b15ba26
@@ -0,0 +1,12 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 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
new file mode 100644
index 0000000..ea3f43c
@@ -0,0 +1,13 @@
+..
+   SPDX-License-Identifier: CC0-1.0
+   SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+..
+   This file is part of libgpiod.
+
+libgpiod python bindings misc
+=============================
+
+.. autofunction:: gpiod.is_gpiochip_device
+
+.. autofunction:: gpiod.request_lines
docs/requirements.txt new file +5 -0
new file mode 100644
index 0000000..535321c
@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC0-1.0
+# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski <[email protected]>
+
+breathe==4.35.0
+sphinx-rtd-theme==3.0.2
include/gpiod.h +0 -36
index 75c55d9..6d40275 100644
@@ -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
deleted file mode 100644
index c26d068..0000000
@@ -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