From patchwork Sun Dec 22 20:08:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 853022 Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5B686165F1E for ; Sun, 22 Dec 2024 20:08:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898102; cv=none; b=MNIFYcAT0puqkGGIvV5e9x2N0nbTYnEBcP00FXi8rEC/vvK4sgoOE9VoADzMS5ocJlFKfRw6LAlo9mt0JTEYH2zGmMQGEzzBXCnBtF0q3eN9vPXqjIie5K2o5H3PLv6SN0rCyrHNow+VvN4Srlo2Bt2G1SWnX5sDGkI9sf4hBRw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898102; c=relaxed/simple; bh=0kbUWR2z9wlXm8RVPEQnbnh1RvUEhAz6KQpoEXpU1o0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=ZBvbp9aQx3me9UedrmC69cidasupbUyva+17VWXA/aW6rZYPtOdqWQDTVWq0VtajnTrnWHy1SiIlCifhuh7GUJ4+UhRr9PCHqbxmL8299f3WEi9DXBD2AQaGkuPlc+WgSSadUqCTEpXhF8xD2cPKwj5SX/TWtsjgJ4F58SCVdiI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl; spf=none smtp.mailfrom=bgdev.pl; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b=jj6TImCN; arc=none smtp.client-ip=209.85.221.41 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="jj6TImCN" Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-386329da1d9so1678286f8f.1 for ; Sun, 22 Dec 2024 12:08:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1734898099; x=1735502899; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=knd5f/sdD9mpQfJK+Hl87zARM4lUQB8IaXLK2CKxR2Y=; b=jj6TImCNmKzQWUC6msZ9NJpvwoGFTyugObFXePfQpsCu7uIEfIoemMNN35SxDL0ZOC 55kCcB3P2UR/RDaxDDwiw1SF3h8Bs7vhgu/cpNMZHT7licoZFw6O4BhnPyOYYe2FQa4J MnUQ6Tw24dC7GQ4vhlysNtEsUUlAYR4K+rv7nd/328A9z9B8AxiYpmeHtBaEUHxT1Zmz TlwaNaBmJDgh+ZNwVQlW/boGTJD7ygSrzjgVHtkYfI19cUNP3EX11d7L9OOLmO/9C3tb jgptHwVbdrKBBgaQIXwzhWXIANzAa5c8k45+RAwJG5hBqV+L0AGgmg1K8otAjgwafLxV 2W3g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734898099; x=1735502899; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=knd5f/sdD9mpQfJK+Hl87zARM4lUQB8IaXLK2CKxR2Y=; b=ZmPmtLVCEApY0n64VG2MWZuBHva9u+YP03wylAUZA2411xL64f9BK/IWWDthXknVI3 6/4a9sVDQD0Z9oyyRbbTTfrmMulR5wc11aWPCQUGCtjQxAo2lEe2X8Qi3ZvWw/Zczksw 8Venl5WA6u4D9v7NrDzNR3qphhyroFWjkSbISb8sdW82UDiGLUw6BPZzzyVmlA/vlqjM tTehOzffD4QxYBixxjWOxaGpzuvFFKHSznqusQbPakJLckwUQh5IL4i/AO0Fr4pHxZi1 oo64+kX7IJFMxqgdJ0SRNLitT0le5sR3PHmP7B5m7xqU0C+Wva/YxZi3Xuwh5l+OlPag eadw== X-Forwarded-Encrypted: i=1; AJvYcCXw3EEmeIgRNhchvkoIIy1JRNtuMUhUqR8Gx+wPLUICrcPEnw32zkqA3tZDXj9FBGj7PQ8lu1M63XZN@vger.kernel.org X-Gm-Message-State: AOJu0YzdEwjltMBu6wjFjMuLL0cEVK/vs6KAEhK4Q49zitO1RRzAhLrU 6MqAwMXmvxYZGp1p342BpJNtVTwnC/jKKC19nGsXmzKjBiUuNhcJONApM9/RUsE= X-Gm-Gg: ASbGnctacq+M0IRO/i5KgXno09et0iXAAwL0fbpu6fhxN/t6p8SRpUw1a3cDiLnhVS1 c2p8C4LReFU/w7xSgxnduEPVihqZVAgW5pu3i4oPzE+pkIX+/Bym+sxoldnDtDG7OmadCkBLF+N IcJI0PTCXRR6uYZVnmxiPZhTrBeEG208Ca27PCYFp4IxGBQAKhrRRzSHLNlxIxS/X8gobTjxnSD t4h62w7Bxm9v2WMf/SYb3c+i8Zw16LR+ZobG16fI3cOBYKU X-Google-Smtp-Source: AGHT+IECk2g9/9q65ResOhV2KTho/lVLlUTlaTBHejZM5AMPg9iO9IyPioOC90KNnwkP3NNj82MfpA== X-Received: by 2002:a05:6000:4614:b0:386:2e8c:e277 with SMTP id ffacd0b85a97d-38a22408c81mr9877992f8f.55.1734898098560; Sun, 22 Dec 2024 12:08:18 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:a153:75c:4edb:ec23]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-38a1c833155sm9492900f8f.24.2024.12.22.12.08.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 12:08:17 -0800 (PST) From: Bartosz Golaszewski Date: Sun, 22 Dec 2024 21:08:06 +0100 Subject: [PATCH libgpiod v2 1/5] bindings: cxx: doc: remove the gpiod_cxx doxygen group Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20241222-improve-docs-v2-1-9067aa775099@linaro.org> References: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> In-Reply-To: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> To: Vincent Fazio , Kent Gibson , Linus Walleij , Erik Schilling , Phil Howard , Viresh Kumar Cc: Bartosz Golaszewski , linux-gpio@vger.kernel.org X-Mailer: b4 0.14.1 X-Developer-Signature: v=1; a=openpgp-sha256; l=11272; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=0srOWbscmu/4FhrutKp8ov6udNTa0kboULA18SAHm8w=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnaHGuAbreD9w58hodzN6UNVdf5ZLsu1LQ0CXs8 kaS6whScXuJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ2hxrgAKCRARpy6gFHHX cvlsEAC3Xvh5EtxAQNia2ix3I+3FydbvtMnCdFR8T1Num041JEI3ia7QyaDlLTsA3sVqNkcRD62 3uZ9HSe/GWxSZbe/r0AkOK/hyLp6Q+cy96Pk0xJZUc+ks9HGgoWCOKq8PrSwhwWvCJ3hbbJ7zCl NVZnwrbiBa7QHm+ZAJed5YY/xMqacegJMVRvEXGcSMRO8w2ik0cbozXRUKy2ZZxIjhBsyAPyEo+ hNowp5Ouj19Ahb7L4cDBJvsjUplblrv7VbIte1zy+VF8fI4stIgINkJptiDAz6a6eah4fblePp+ HT27z9vknH5/RVHRwIPUrfkQ+PJKoZVrw+0GZNPdCMUHpC7ZBbx6Tb3RU9jtQNaNgtyVKHB5wN2 YB7I67gi5c/xKmjye1h6La8j/nKoWCI0FuihmLRaJXvOIwW9CYSgvHHVmes9FklJ+ECbDzvZOcA SPIzIseqtC7OniredId2pgClQMIGJGUm9yKCbH5j4Bj3fg704z0oNwnJQj4fw8FFncaNqChckqC M2iPMF3efXa67676j4rTvo5HQPnp+4y7wgdra2X/uouVc/cPywh9qZf1lEsU8VzSJWkZHtoXRhb we2Zodnh24oslIJ0vA/ko4+dQ/2M7l4izPNuwDFJofXd9sF9e7rACMrARb4YwA14Pn4xq4vzMDR rzUfwbzen0hz5Vg== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Groups make sense for the C API as they allow us to nicely order interfaces manipulating a given structure thematically but for C++ they make less sense as methods are already typically part of a class. Additionally for global functions, they seem to make it difficult for breathe to look up the correct symbols. Remove the gpiod_cxx group from Doxygen comments. Signed-off-by: Bartosz Golaszewski --- bindings/cxx/gpiod.hpp | 6 ------ bindings/cxx/gpiodcxx/chip-info.hpp | 9 --------- bindings/cxx/gpiodcxx/chip.hpp | 9 --------- bindings/cxx/gpiodcxx/edge-event-buffer.hpp | 9 --------- bindings/cxx/gpiodcxx/edge-event.hpp | 9 --------- bindings/cxx/gpiodcxx/exception.hpp | 9 --------- bindings/cxx/gpiodcxx/info-event.hpp | 9 --------- bindings/cxx/gpiodcxx/line-config.hpp | 9 --------- bindings/cxx/gpiodcxx/line-info.hpp | 9 --------- bindings/cxx/gpiodcxx/line-request.hpp | 9 --------- bindings/cxx/gpiodcxx/line-settings.hpp | 9 --------- bindings/cxx/gpiodcxx/line.hpp | 9 --------- bindings/cxx/gpiodcxx/misc.hpp | 9 --------- bindings/cxx/gpiodcxx/request-builder.hpp | 9 --------- bindings/cxx/gpiodcxx/request-config.hpp | 9 --------- bindings/cxx/gpiodcxx/timestamp.hpp | 9 --------- 16 files changed, 141 deletions(-) diff --git a/bindings/cxx/gpiod.hpp b/bindings/cxx/gpiod.hpp index 91e41a5..606994d 100644 --- a/bindings/cxx/gpiod.hpp +++ b/bindings/cxx/gpiod.hpp @@ -8,12 +8,6 @@ #ifndef __LIBGPIOD_GPIOD_CXX_HPP__ #define __LIBGPIOD_GPIOD_CXX_HPP__ -/** - * @defgroup gpiod_cxx C++ bindings - * - * C++ bindings for libgpiod. - */ - /** * @cond */ diff --git a/bindings/cxx/gpiodcxx/chip-info.hpp b/bindings/cxx/gpiodcxx/chip-info.hpp index e740e94..61c0b78 100644 --- a/bindings/cxx/gpiodcxx/chip-info.hpp +++ b/bindings/cxx/gpiodcxx/chip-info.hpp @@ -19,11 +19,6 @@ namespace gpiod { class chip; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Represents an immutable snapshot of GPIO chip information. */ @@ -96,10 +91,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const chip_info& chip); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_CHIP_INFO_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/chip.hpp b/bindings/cxx/gpiodcxx/chip.hpp index 4d67476..8a1389e 100644 --- a/bindings/cxx/gpiodcxx/chip.hpp +++ b/bindings/cxx/gpiodcxx/chip.hpp @@ -30,11 +30,6 @@ class line_request; class request_builder; class request_config; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Represents a GPIO chip. */ @@ -173,10 +168,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const chip& chip); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_CHIP_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/edge-event-buffer.hpp b/bindings/cxx/gpiodcxx/edge-event-buffer.hpp index 2482e8a..083c2e1 100644 --- a/bindings/cxx/gpiodcxx/edge-event-buffer.hpp +++ b/bindings/cxx/gpiodcxx/edge-event-buffer.hpp @@ -22,11 +22,6 @@ namespace gpiod { class edge_event; class line_request; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Object into which edge events are read for better performance. * @@ -120,10 +115,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const edge_event_buffer& buf); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_EDGE_EVENT_BUFFER_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/edge-event.hpp b/bindings/cxx/gpiodcxx/edge-event.hpp index 47c256a..acbe7af 100644 --- a/bindings/cxx/gpiodcxx/edge-event.hpp +++ b/bindings/cxx/gpiodcxx/edge-event.hpp @@ -22,11 +22,6 @@ namespace gpiod { class edge_event_buffer; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Immutable object containing data about a single edge event. */ @@ -128,10 +123,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const edge_event& event); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_EDGE_EVENT_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/exception.hpp b/bindings/cxx/gpiodcxx/exception.hpp index 34737d2..b753af0 100644 --- a/bindings/cxx/gpiodcxx/exception.hpp +++ b/bindings/cxx/gpiodcxx/exception.hpp @@ -17,11 +17,6 @@ namespace gpiod { -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Exception thrown when an already closed chip is used. */ @@ -149,10 +144,6 @@ public: ~bad_mapping(); }; -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_EXCEPTION_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/info-event.hpp b/bindings/cxx/gpiodcxx/info-event.hpp index 69b88b6..ee01651 100644 --- a/bindings/cxx/gpiodcxx/info-event.hpp +++ b/bindings/cxx/gpiodcxx/info-event.hpp @@ -23,11 +23,6 @@ namespace gpiod { class chip; class line_info; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Immutable object containing data about a single line info event. */ @@ -114,10 +109,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const info_event& event); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_INFO_EVENT_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/line-config.hpp b/bindings/cxx/gpiodcxx/line-config.hpp index 58c9d87..b3b9aba 100644 --- a/bindings/cxx/gpiodcxx/line-config.hpp +++ b/bindings/cxx/gpiodcxx/line-config.hpp @@ -21,11 +21,6 @@ class chip; class line_request; class line_settings; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Contains a set of line config options used in line requests and * reconfiguration. @@ -111,10 +106,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const line_config& config); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_LINE_CONFIG_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/line-info.hpp b/bindings/cxx/gpiodcxx/line-info.hpp index 8b10dc4..bf02ba1 100644 --- a/bindings/cxx/gpiodcxx/line-info.hpp +++ b/bindings/cxx/gpiodcxx/line-info.hpp @@ -22,11 +22,6 @@ namespace gpiod { class chip; class info_event; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Contains an immutable snapshot of the line's state at the * time when the object of this class was instantiated. @@ -167,10 +162,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const line_info& info); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_LINE_INFO_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/line-request.hpp b/bindings/cxx/gpiodcxx/line-request.hpp index fcc4e0e..9605019 100644 --- a/bindings/cxx/gpiodcxx/line-request.hpp +++ b/bindings/cxx/gpiodcxx/line-request.hpp @@ -26,11 +26,6 @@ class edge_event; class edge_event_buffer; class line_config; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Stores the context of a set of requested GPIO lines. */ @@ -227,10 +222,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const line_request& request); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_LINE_REQUEST_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/line-settings.hpp b/bindings/cxx/gpiodcxx/line-settings.hpp index 1004ccd..89d79f8 100644 --- a/bindings/cxx/gpiodcxx/line-settings.hpp +++ b/bindings/cxx/gpiodcxx/line-settings.hpp @@ -21,11 +21,6 @@ namespace gpiod { class line_config; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Stores GPIO line settings. */ @@ -193,10 +188,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const line_settings& settings); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_LINE_SETTINGS_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/line.hpp b/bindings/cxx/gpiodcxx/line.hpp index 2810571..c58bf11 100644 --- a/bindings/cxx/gpiodcxx/line.hpp +++ b/bindings/cxx/gpiodcxx/line.hpp @@ -23,11 +23,6 @@ namespace gpiod { */ namespace line { -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Wrapper around unsigned int for representing line offsets. */ @@ -265,10 +260,6 @@ using value_mappings = ::std::vector; */ ::std::ostream& operator<<(::std::ostream& out, const value_mappings& mappings); -/** - * @} - */ - } /* namespace line */ } /* namespace gpiod */ diff --git a/bindings/cxx/gpiodcxx/misc.hpp b/bindings/cxx/gpiodcxx/misc.hpp index eab8eba..cb56b92 100644 --- a/bindings/cxx/gpiodcxx/misc.hpp +++ b/bindings/cxx/gpiodcxx/misc.hpp @@ -16,11 +16,6 @@ namespace gpiod { -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Check if the file pointed to by path is a GPIO chip character device. * @param path Path to check. @@ -35,10 +30,6 @@ bool is_gpiochip_device(const ::std::filesystem::path& path); */ const ::std::string& api_version(); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_MISC_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/request-builder.hpp b/bindings/cxx/gpiodcxx/request-builder.hpp index 192bd91..62597b4 100644 --- a/bindings/cxx/gpiodcxx/request-builder.hpp +++ b/bindings/cxx/gpiodcxx/request-builder.hpp @@ -22,11 +22,6 @@ class line_config; class line_request; class request_config; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Intermediate object storing the configuration for a line request. */ @@ -148,10 +143,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const request_builder& builder); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_REQUEST_BUILDER_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/request-config.hpp b/bindings/cxx/gpiodcxx/request-config.hpp index 6ebbf99..96f0262 100644 --- a/bindings/cxx/gpiodcxx/request-config.hpp +++ b/bindings/cxx/gpiodcxx/request-config.hpp @@ -23,11 +23,6 @@ namespace gpiod { class chip; -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Stores a set of options passed to the kernel when making a line * request. @@ -105,10 +100,6 @@ private: */ ::std::ostream& operator<<(::std::ostream& out, const request_config& config); -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_REQUEST_CONFIG_HPP__ */ diff --git a/bindings/cxx/gpiodcxx/timestamp.hpp b/bindings/cxx/gpiodcxx/timestamp.hpp index fcb4d8d..dc44eb7 100644 --- a/bindings/cxx/gpiodcxx/timestamp.hpp +++ b/bindings/cxx/gpiodcxx/timestamp.hpp @@ -17,11 +17,6 @@ namespace gpiod { -/** - * @ingroup gpiod_cxx - * @{ - */ - /** * @brief Stores the edge and info event timestamps as returned by the kernel * and allows to convert them to std::chrono::time_point. @@ -114,10 +109,6 @@ private: ::std::uint64_t _m_ns; }; -/** - * @} - */ - } /* namespace gpiod */ #endif /* __LIBGPIOD_CXX_TIMESTAMP_HPP__ */ From patchwork Sun Dec 22 20:08:07 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 853341 Received: from mail-wm1-f53.google.com (mail-wm1-f53.google.com [209.85.128.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 644A518BBB9 for ; Sun, 22 Dec 2024 20:08:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898103; cv=none; b=YnKtzs2q/bRAkWYUPSBPIDVPmJwha760MWgTD1076S4AsOuRz2+kvZVY353iwZ5tXlmd/RRwWiQ2HVMA2hmHlycZv+2AEDIRKKglXVBLz/OnUPWtNgJb4HFJVuDtETHTNCivmQ1mUGHKVrkAbAbF0rUZmdO5uvHlyhPjs2+bhus= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898103; c=relaxed/simple; bh=YilZz6A9tl3H04do/1ex0MqqUVgAZTxf2/OpwfJAKDY=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=qKIqSVftpA/4fPdhcW/5k99403CJ131t7qFlmK6VpgmLU1G7vLPN9XTrOHuQMUhY2GctCexjr7zeOfv5NwsbC9E1atvhkPYUPDSha5ERwsJLxchZa6+wNol3NwzvtjC8RUlCsA5W9u7iVsUEkzt+WLJoz5nOVnjBAk6SPiJ0IXQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl; spf=none smtp.mailfrom=bgdev.pl; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b=woZVy1as; arc=none smtp.client-ip=209.85.128.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="woZVy1as" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-43624b2d453so38199375e9.2 for ; Sun, 22 Dec 2024 12:08:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1734898099; x=1735502899; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=L1J2i+9hAYKMd/cu+aN5cLBk4csvIDgvl+kPAxnJaEw=; b=woZVy1asQxMNFiCFJv6g3WY5aj/DQv0dp68pkujoCq/bymIGX9GxaxRadLFA28RcNh 1kj5rhFQuJdBOUNo7s7iTO0riA5GPhsCZyiT9bm2dqEYfkvxtQ7XX6dEDYZN1Vf6UJKu 7aVgI/tLqiwRjOhX3pRVRwzfWZ1tpAOwZ5dBvllK8Ds3B9WYVeUjhLGOQsDfpkzqbQ+R i/eBe6Qms2UC8yoJxgKogMuBkaS3L3PChMDCZGKQemLpxutbGe8pPkabf+N2PAcOAg// NSwGKfXqplaedFmv5EbcyrPa4mL6jIep6Iwgp8LyMu/lY3Tt22G41aszk4ve4+/iM5TT 6WkA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734898099; x=1735502899; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=L1J2i+9hAYKMd/cu+aN5cLBk4csvIDgvl+kPAxnJaEw=; b=AVldsZijHzQ/iahQ6B+amMMo4+D8zZbe5IEf2w09T93+l3knZqoICtTALkIlkKcLuy RxyeUaE1ivSDQYT6+DymNm3PNHgRwiEceE7gI7MNeolb1BRkfH5NnQFsNh9IGzNiEuWT oZLpG8rpGxa0EPzwxZeqE9W2VoRa5RtrbC7gMpomo7LbbPn20yBWKZbmV5LIxWryTiFS DkKuIfG9Vn1U6BIY5CXGaBT//7x79GAWFL1wgFVk6l7l+j1jY9yzlplpQoyc1sL0jopM cD5PNEOQCN1ZF7DZ8/3yFcpoEZci/pvidTRN2b2VlsjrhDAbr5rxl0ljQfS8TFZqEIYA 1dhQ== X-Forwarded-Encrypted: i=1; AJvYcCWzwCZc6b1tHuDYFzV55RmPP1hpfZyrBJmVcziBN/h2w5aD4rmPgeD7NCAUPUvWLl8NKi0OdWXIYcRA@vger.kernel.org X-Gm-Message-State: AOJu0YxLJNDeV7iBOTXiHT4GprT7XLhui8E7W/ZyPtThETqYfMIrMYaR 5Lymh8ROcJGJpjKiPaasko641mefBrXfpHowxDShd7oJ+bG0WF2iCq5Jt/nhVOk= X-Gm-Gg: ASbGnctbXTAFoMv4JROQllyYcSlJ/WfJAK9yNRil4c5O208LTL9rLZxFhtkFGehQ+IF oljVxcvEDsSAeuqW78Te1PX6GFEkth24iRONHN7tLylc9dwqZqgieNewt1EoN95H3QvaelCyfkf 8ee3ML5x3bTmKG1jono99pYIi4Yi0krsD5kCqqgIRkuKFDN1gIN/oDvPC2ZisO55foEPAZAlb8D YYo5gp+yd3RWrAXwC3X3IadZMthnVup+aPEPqWtSK+qiSB/ X-Google-Smtp-Source: AGHT+IEyqI3K30QnOwMngwZ2ZdYDKJAwkMl7DUVDU9oLopstBP28yLQmcV5LAUgQv2D9pwzmP4fFlQ== X-Received: by 2002:a5d:5e09:0:b0:385:e4a7:df09 with SMTP id ffacd0b85a97d-38a223f75fbmr11465438f8f.44.1734898099561; Sun, 22 Dec 2024 12:08:19 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:a153:75c:4edb:ec23]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-38a1c833155sm9492900f8f.24.2024.12.22.12.08.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 12:08:18 -0800 (PST) From: Bartosz Golaszewski Date: Sun, 22 Dec 2024 21:08:07 +0100 Subject: [PATCH libgpiod v2 2/5] bindings: python: doc: update the docstring for gpiod.request_lines() Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20241222-improve-docs-v2-2-9067aa775099@linaro.org> References: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> In-Reply-To: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> To: Vincent Fazio , Kent Gibson , Linus Walleij , Erik Schilling , Phil Howard , Viresh Kumar Cc: Bartosz Golaszewski , linux-gpio@vger.kernel.org X-Mailer: b4 0.14.1 X-Developer-Signature: v=1; a=openpgp-sha256; l=1494; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=DE6f488TgezGHpfP+C15KZ9ntYY4YymZkPrZIuz9vlE=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnaHGvtACFk0lhp4Ud6GHmEQiFkdlBJm2CafNXE bpIKCQ+on+JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ2hxrwAKCRARpy6gFHHX cqI8EACOxfr0EpFVDN5W4c5kMDhDiiuXq+rd1fv/ihIqeTKzi+b++6xSPlOW3zk9m99ism6kqED kzq3Ea3dRph1tLE7MykIj90iXpFdWgAelrNFIAId9rO7IK2TetJR6Ty2p7laFt37hnDiM3OTyBi fKm5IfT5dg/2kRioHFFEeMJEZnPthgqL8jLJHLRlkwN6G/tt5b9pFzgcsv085ukINK0xmxbeft0 a/Hs0h5S9D9kc0VCxxq4e3rPxhd7fi52kLGlGWkkiQ5YVmBGfqZKtk4NBPnd2pHdWxGF+mv/6OC 1zbxQZYrKX3iqfmDXhXL0tHK+ojajr+ZZuih3IAHNQTGHHuYpwEJh9CyMbybuu3MPlYjYSnjid1 4yFB9ouJJdFrODfVIrIj6M7+RngEIgJ+PvhtQdu4/CdpGbCx67eBiI7n/XugUhNTrWTr4FVD/do ET5HTiY9b8mo6tTQx9ygiaARSBula/TMeLCsppPaq/YxMU0yA0V8ek0CN7PK/OzSZGkZt7EcP/m fhG3G4yJLELhHG5uXKyltAm/U7CZKKVxjrGnX/ug8AYVQ9iHbENfy84Mbv3fvKW28exyny/+2DP dzgIzsLOChQTVRqd2x9mAEjgV+KImlCJ5Zoz0XXioLYy8dQ4pCOUVYXIRpLpQ6M6wtAZKZV9dBz bHbDQC3aDCzJgxg== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski 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. Signed-off-by: Bartosz Golaszewski --- bindings/python/gpiod/__init__.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/bindings/python/gpiod/__init__.py b/bindings/python/gpiod/__init__.py index 817c755..854e41f 100644 --- a/bindings/python/gpiod/__init__.py +++ b/bindings/python/gpiod/__init__.py @@ -99,9 +99,18 @@ def request_lines( Args: path Path to the GPIO character device file. - *args - **kwargs - See Chip.request_lines() for configuration arguments. + config: + Dictionary mapping offsets or names (or tuples thereof) to + LineSettings. If None is passed as the value of the mapping, + default settings are used. + consumer: + Consumer string to use for this request. + event_buffer_size: + Size of the kernel edge event buffer to configure for this request. + output_values: + Dictionary mapping offsets or names to line.Value. This can be used + to set the desired output values globally while reusing LineSettings + for more lines. Returns: Returns a new LineRequest object. From patchwork Sun Dec 22 20:08:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 853021 Received: from mail-wm1-f50.google.com (mail-wm1-f50.google.com [209.85.128.50]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0731418F2CF for ; Sun, 22 Dec 2024 20:08:21 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.50 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898103; cv=none; b=JT+6jYfcW1p+aE1xUI8Qd58Xyje2ESW6xahlKr6WTYbMwkXxZvOaBdfqt1el3fYglmHV+frqcdl3FhtqQUxvjkq5NwXs6Upxd4nt88RqqdxZ6wKW1JNXYGHWJqllfQ5ctjfBMPj4YWuwf3w/hMTps0hNPqtVE69Zq7nY+a5vOBg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898103; c=relaxed/simple; bh=WO/IMfzFod/8cBoacm7o51W0b+nlCHHqIWQnuGnGvBk=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=DVjAgXIp9oEctdt+W5KYrXLHSMF027BHJuMoq7yvqPW9OLjAo+LJ4MuWtJDpCgEg1tJbuyo90EPj1PJULiZbx0xBGrDK4bvS9S8vx47bYCRagspXpddz8ByymMTFs7vj8li0fZ+63JKGJBOkuWnu/rHiplruHRSaaDtYFzmfc8A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl; spf=none smtp.mailfrom=bgdev.pl; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b=TOvwZ1kr; arc=none smtp.client-ip=209.85.128.50 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="TOvwZ1kr" Received: by mail-wm1-f50.google.com with SMTP id 5b1f17b1804b1-436341f575fso38291965e9.1 for ; Sun, 22 Dec 2024 12:08:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1734898100; x=1735502900; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=y1BBaXwMfpgsyUobFfQ5GTap8VassTB06r2EoTlfJ+w=; b=TOvwZ1krnNxXRu0TRSBTAu9jlZEqszUEP1gv9JGgHRmNQW60h7m+lNy1w/cHXbAwK8 WSJVm/vFsycgh6Dh2EAELdFPnfIp2MtIVin922qAEFmlxN7j/sFzKv/hEjGyMhwwHdW+ 6eB2GOU8YvBlERHdfxoetfvYvOBCgWeo1HIs1mudq6s0LMlILmaAh8WEXzUHBqG6b+ir V72IcJ5p5YjvZfubBluD9rj3M96Qed5vLKmAS8e2x3OOA4vmbCIwZ1IzhtN4OPWiykXH co4HTWiLDvMHvW3m8q6SfBw0g1zeyHPOQns06W8kDyRTzIGcrDVAJClBkx8NsBL/g7BU ZS+Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734898100; x=1735502900; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=y1BBaXwMfpgsyUobFfQ5GTap8VassTB06r2EoTlfJ+w=; b=sO0q4h+BKJsnAf3XEq1/KOkZMLD6HJycZAzxU98HdgINgJu2SsXn/y9Mjt2iN3BIwh 19n6AmlBxpvbBrKfHhqFjkVPxDzqHSpYNOzEaiWe44pfXOSxD1Al5Xukt18Donilct/r 3eG/C8/Dn7Yypp9VzPJuTclOI9tzqVFAOZflFsEpVH50gCukpPHlbwGFFOIFMdmdmPlo XLLMLntwFe8I/leZ8mh1DfvSP5HFfHIaKEDhSEYJ5YIKq/1gslbHQMvcheEAtjqLC0Cf G8P8ScoCGvaz6pttZQNhylt3QreeyaNbJvZp8zLSUQzkdB8JlxMbn1k9XY4IytVq7COm GkaA== X-Forwarded-Encrypted: i=1; AJvYcCXeWhVulYYfXCrWvja8W+pQCdxHIR+obhWm8wQ+qrlq1JBfQo+l9VMolRth4JFm1C+yTg4m80sZLZzE@vger.kernel.org X-Gm-Message-State: AOJu0YxJQ73dHhpieBaZEMiS0InNm0KvysmJd6ARyQreCs789HyvA5AY fj+glGLOsJBPxHpzz2WtjfZ2FRQP0dbnpU4f/oieFMd8ebiW2I7cez/cOXnezq0= X-Gm-Gg: ASbGnctfYt0Zw09qssJUs7WlKR353eP1aeaMb8CmdwewXY9zWyX4MtMn+U8Um6gCgLa K9YX/qgqjzqO0LM9337jzDWeCZ3DIKoKIkPXjysUo/FrAwL9D4WLu1B0fXamJVkHz1MaElTmIWI D0oyGkcYfytzQJJ8cynlK1h9ONsg8CYDKvXLuR0Q0TO+n3WKXsZIcLdBbZ+ggU1XLmT+zIq6TRo RfyrMwmFvrJvA4kOkNUxSEiH8eBQG99vazQh4fh815m89Fc X-Google-Smtp-Source: AGHT+IGBD/YHSaEqYkFn/OiKhIYVpboBX4XgLY492MgyAHUPXur5yEh4nooh0/Fr1D5ZBF2Cj0T6Ug== X-Received: by 2002:a5d:6f16:0:b0:382:40ad:44b2 with SMTP id ffacd0b85a97d-38a221fadadmr9370116f8f.34.1734898100427; Sun, 22 Dec 2024 12:08:20 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:a153:75c:4edb:ec23]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-38a1c833155sm9492900f8f.24.2024.12.22.12.08.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 12:08:19 -0800 (PST) From: Bartosz Golaszewski Date: Sun, 22 Dec 2024 21:08:08 +0100 Subject: [PATCH libgpiod v2 3/5] bindings: python: doc: make code examples appear as such in sphinx Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20241222-improve-docs-v2-3-9067aa775099@linaro.org> References: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> In-Reply-To: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> To: Vincent Fazio , Kent Gibson , Linus Walleij , Erik Schilling , Phil Howard , Viresh Kumar Cc: Bartosz Golaszewski , linux-gpio@vger.kernel.org X-Mailer: b4 0.14.1 X-Developer-Signature: v=1; a=openpgp-sha256; l=979; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=ql8amRJIay+V0eyvml8PPHVhO3kwrPs+SWiWNGqjGeI=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnaHGvYyGXWK4q76Zr2TP47uMu1F71BAQHI4CP3 Ttw81h5+d2JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ2hxrwAKCRARpy6gFHHX cmqTEACtVf0lHDJ39keLQil4lwL5scqWxgjPA/567QLNjP+LRUcDZUkbB1W7nbsFCg/Vra2JWf9 Gq7zcdH5Wg5ACMw57Oz9ArVhzSQdhmwk8/JiRXjSXloPfadsNYzhZVpL7Gt5d2eHN8Vq2n6dgTZ cnoTz90LrybKNE4A3KG032FeaYWFK8WqOLKoPl/j7oGULs2q5lbz+DGH6ksO6DQU1/6p4CoTAH9 KneGP5LetLOjXm7z/xolltKPqK1oocKRmBnWaxG1VKSHWQZXyLCVGVGl+rDlQLw9xbtvIHpkFDK t0BFtE9T0BuwWlV14RYKSgsMpjEqZD+VqT7QsjnFk++tU6b5RH4I5mdTn224c3uC6DVOgOc3aNv j6V4bi2ikVJc3I9517CYBW9Flh3iRyeuf47oKlK2ABz4SKWdnYUfKLOcYnKqNNqfCObMu5CcUwv 0lnGkUNIENDs/do1ajpF5+go7YB6duEKHqd6IRIIqS/FmL+iA6Pp0Jz1wfcCc1+KlzO4vxpZ/V9 X1pj8BNMMLp4L4mGwYGKcdLnbhKpnZ4Neq5E3QYPBrhlRPXz46X+8pSELofs+APCAzz608k33ge c93rR7UI6RggIzbzsf/8m57v4ZAxMV/9dlxeFYiCQbwm50MyYo5/Tv1MsiaqosuczimyeR7gk5h ByEiEwOMOzEttwA== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski In order for code examples inside docstrings to be interpreted as such by sphinx, we need to use a double colon ("Example::"). Signed-off-by: Bartosz Golaszewski --- bindings/python/gpiod/chip.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bindings/python/gpiod/chip.py b/bindings/python/gpiod/chip.py index ddd07b8..5641343 100644 --- a/bindings/python/gpiod/chip.py +++ b/bindings/python/gpiod/chip.py @@ -39,7 +39,7 @@ class Chip: Callers must close the chip by calling the close() method when it's no longer used. - Example: + Example:: chip = gpiod.Chip(\"/dev/gpiochip0\") do_something(chip) @@ -47,7 +47,7 @@ class Chip: The gpiod.Chip class also supports controlled execution ('with' statement). - Example: + Example:: with gpiod.Chip(path="/dev/gpiochip0") as chip: do_something(chip) From patchwork Sun Dec 22 20:08:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 853340 Received: from mail-wm1-f44.google.com (mail-wm1-f44.google.com [209.85.128.44]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5719D165F1E for ; Sun, 22 Dec 2024 20:08:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.44 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898105; cv=none; b=Fw84wAwfGZPmW3qdadnP0RGKnm1tIHsQGT8Mfhs2f7XhaKs0psZCUXgICTQFbs5nDyYnqERPeFu9xZ/TwZVp1g2ghF1z7btm+nrXZrKM7Mmp0Uyo6OSpQzWU3BhCh653dJkByRXEatUshMvCtTxRpQ4buqzBSnQqm4xYhhqQPjA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898105; c=relaxed/simple; bh=NhCfl+Kf5EQ2UwVelToJ1q07HgJ+U6QdzNQaf1Pr7sE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=peUzp58H+bZoOzGYAw6XPtbwcmQKp6yAUrIrINL+Kh2v0NOf5IQ4DMsHBWILgsvhNfdEw7AUmBdQGUThRuN1LezkAgXcRRg/5O11Ojm6PB5gLn8Uxa4MWoYdZ9yd0xZ8W9sMtNBmKAI7wGPn/12ydIUTeIgIZVJUkHIq8z5Jm7g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl; spf=none smtp.mailfrom=bgdev.pl; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b=Umo/b80X; arc=none smtp.client-ip=209.85.128.44 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="Umo/b80X" Received: by mail-wm1-f44.google.com with SMTP id 5b1f17b1804b1-436202dd7f6so40570155e9.0 for ; Sun, 22 Dec 2024 12:08:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1734898102; x=1735502902; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=Z+mrn6ZS9pJMG2PWPukzMUQixAlUjJ28nS6mTddW1wQ=; b=Umo/b80XRxR7loHcY4UEFvyaEAwUkEf9LfyEkJHxxY6R570UnzyxT9QqjSkp7QPyb5 Dn455TxKVfpFBZ96vspY/i3hOQq3SLpbBj9BB8Eq7irQn6zXeFPBZwO33XFQep0VczPu emnlSDI8UEnp4VLcNsps+zIeU5eyTbOBdnaMUGyTPt/wKzvImg6H3m+qKy0V/LdmQTUt F3RlFRN/dEaBasOLcigeWm0pmcmsVrQk5ZbAAAlNRfxA0nYwagqfXdJ5OqpkulxjapTP VQboLTpACk/Jkjy6MksJ4Adpop9D6qdISGDl4+XxEBd0N3H27G/5OINTo19D2yYsQqH5 DIVw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734898102; x=1735502902; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Z+mrn6ZS9pJMG2PWPukzMUQixAlUjJ28nS6mTddW1wQ=; b=myKIJ0jGDDSJr9nd221MUeZtHwSsieImFs2/c4PaioCNfzmGR4RMS/TIYor7o5crx6 k3Yy1PmWqxDJpnF3DkpMdQGb7w3ctIzHFyTgY8+Aw8FJ0ajLNjqQ5sJjdwCi3V4txisC boYkgNaSllSybXXXPVijCS7J176D2r0CBLcaqfnmBSVf8AUQJuDhQLMX9f3OsntuRk6c VExbqk+Funqf108TpskRHxaa32iSeAbnrKGLnodytQJ15QuMxA1daCuivtrj1kpE5pBM 84jW/NdpamMAi6KTw32uzGCxSP6sfJN5AwCVwbG/JY18OJRZLBQ/N2Yo+lgs7zFqwsq0 W9Tw== X-Forwarded-Encrypted: i=1; AJvYcCVZIFvt7KaW5s7iWX2j6x8L20g4+7S/M+Q87jNRvi4BpOFPJkVhZiUWF/fTH/uYUicZ3h2JBxt+AaNS@vger.kernel.org X-Gm-Message-State: AOJu0Yxh4CdX0eVbNWQu7eOwe5N12jyntdzhMFrqyhJm1auqa7i61xvv 9SD9MT7w2k2a8z3Z81alzRycPBAv+OJhyOLI1dPcOXqUgyuHoMXSunJw1R3foh4= X-Gm-Gg: ASbGnctsP3HGop4fZztNqFRi9xH3vwH9JECTVRhJTtWoD2Nhgn/7xmTDmUzMdVn/ePW QRM1ituU/z8l9pT8G1oqiI9abX9+25aRi6llDecep6+F6WBHpIAJCHPMuC+blSiFw/4Vpj8w8wq 6fB/Z7NC3Ntr3Tt3bTa2nI9uKTh/vRIfuULKy8A/QTUP8qvPgIQrnWBh994g0jiBDXc/bxyl5ml kmnfvSsGmGXJPlHt4ef4327ekk5FcsT8HyVujBbLWnTEXBP X-Google-Smtp-Source: AGHT+IH+3OM1R3Q0LMmG7iy01KiJSl1AUteWJL7QIxuzLl2fNUxLBdJzcyfgBv9rhpngeQoegbD3gA== X-Received: by 2002:a05:600c:282:b0:436:51bb:7a3b with SMTP id 5b1f17b1804b1-4366854c054mr84986185e9.6.1734898101463; Sun, 22 Dec 2024 12:08:21 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:a153:75c:4edb:ec23]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-38a1c833155sm9492900f8f.24.2024.12.22.12.08.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 12:08:21 -0800 (PST) From: Bartosz Golaszewski Date: Sun, 22 Dec 2024 21:08:09 +0100 Subject: [PATCH libgpiod v2 4/5] bindings: python: doc: describe undocumented members Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20241222-improve-docs-v2-4-9067aa775099@linaro.org> References: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> In-Reply-To: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> To: Vincent Fazio , Kent Gibson , Linus Walleij , Erik Schilling , Phil Howard , Viresh Kumar Cc: Bartosz Golaszewski , linux-gpio@vger.kernel.org X-Mailer: b4 0.14.1 X-Developer-Signature: v=1; a=openpgp-sha256; l=7689; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=LhcHepDt0rsWrdFCseebevfOQ5srCUTQc8wqLx64ULM=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnaHGw3w4cJgfjXBE3irvshwCndrGDHfx57Oqng 7gJ7kEbNheJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ2hxsAAKCRARpy6gFHHX crUED/9Y1RVY2JKl83gKRwjXCM6tGWR+NRKOQ7gb39UrXmqWDChGQpJ709dwA9GHMkkuc+htY4n G32A6W0WIOtULXIxCsIU7rbbwprmLSVQnueH4NxmUeP8GbhVQnABTnx7R4i2+y3pF5THGHNsg+p Ru8yM7Hk+2ltgsM5gqyNuz41CmyG9pw3oCD0/PwuAzhvU1BO/K4PufaPEWPZaH88PlOt4vEVoso kE/Qusacp8JpPY0LaCiF6kKQJcawjLyQtqI1goF9OUipGYOYEc1LOEk2ov3Odc210udj7FfX304 QkOmPfJZ7g3P/dcNIcM2Qi3y7buo401fsV5CQH0TgeDMdxZGjkk9SLux3Gpy4eQtAFQlFE+zHWE +wDXerZ3hOtd8AEcqCjHi0nSI9HAB32/qFz3qggocGl6TMnYVJD+WiIk6wEAEYPHl/tSLUN3Q8Q hQRBvFPQ5+ygKbazkHvnzZB/u822J6QpVy8lZ+YZRMZsXLAcHnrorsgosa4qbvGo3CDikEuPKym RTRa1WrLzRUmy5z91KciCAlxU9GzizpzyMqSy0sEI31mOExdKzS45qTRvMrbJUSj7CEpkYV2P05 LSIdzIREDJuYoZQw2oUSqnErfjqFrLwhiT2ZLPOVDjk6hCrwcpDl79Iq9QZu5O6jdXhBaWwdN8c e8fk3KWbs44okyg== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski There are several public members in python bindings that are missing docstrings. Document them for completeness. Signed-off-by: Bartosz Golaszewski --- bindings/python/gpiod/chip_info.py | 5 +++++ bindings/python/gpiod/edge_event.py | 9 +++++++++ bindings/python/gpiod/info_event.py | 8 ++++++++ bindings/python/gpiod/line.py | 20 ++++++++++++++++++++ bindings/python/gpiod/line_info.py | 12 ++++++++++++ bindings/python/gpiod/line_settings.py | 8 ++++++++ 6 files changed, 62 insertions(+) diff --git a/bindings/python/gpiod/chip_info.py b/bindings/python/gpiod/chip_info.py index 3306af2..737a45e 100644 --- a/bindings/python/gpiod/chip_info.py +++ b/bindings/python/gpiod/chip_info.py @@ -14,8 +14,13 @@ class ChipInfo: """ name: str + """Name of the chip.""" + label: str + """Label of the chip.""" + num_lines: int + """Number of lines exposed by the chip.""" def __str__(self) -> str: return f'' diff --git a/bindings/python/gpiod/edge_event.py b/bindings/python/gpiod/edge_event.py index 7f5cd4d..c888cb2 100644 --- a/bindings/python/gpiod/edge_event.py +++ b/bindings/python/gpiod/edge_event.py @@ -16,14 +16,23 @@ class EdgeEvent: """ class Type(Enum): + """Possible edge event types.""" + RISING_EDGE = _ext.EDGE_EVENT_TYPE_RISING + """Rising edge event.""" FALLING_EDGE = _ext.EDGE_EVENT_TYPE_FALLING + """Falling edge event.""" event_type: Type + """Edge event type.""" timestamp_ns: int + """Timestamp of the event in nanoseconds.""" line_offset: int + """Offset of the line on which this event was registered.""" global_seqno: int + """Global sequence number of this event.""" line_seqno: int + """Event sequence number specific to the concerned line.""" def __init__( self, diff --git a/bindings/python/gpiod/info_event.py b/bindings/python/gpiod/info_event.py index 4a86697..cd2785e 100644 --- a/bindings/python/gpiod/info_event.py +++ b/bindings/python/gpiod/info_event.py @@ -17,13 +17,21 @@ class InfoEvent: """ class Type(Enum): + """Line status change event types.""" + LINE_REQUESTED = _ext.INFO_EVENT_TYPE_LINE_REQUESTED + """Line has been requested.""" LINE_RELEASED = _ext.INFO_EVENT_TYPE_LINE_RELEASED + """Previously requested line has been released.""" LINE_CONFIG_CHANGED = _ext.INFO_EVENT_TYPE_LINE_CONFIG_CHANGED + """Line configuration has changed.""" event_type: Type + """Event type of the status change event.""" timestamp_ns: int + """Timestamp of the event.""" line_info: LineInfo + """Snapshot of line-info associated with the event.""" def __init__(self, event_type: int, timestamp_ns: int, line_info: LineInfo): object.__setattr__(self, "event_type", InfoEvent.Type(event_type)) diff --git a/bindings/python/gpiod/line.py b/bindings/python/gpiod/line.py index 33c7368..0cfc854 100644 --- a/bindings/python/gpiod/line.py +++ b/bindings/python/gpiod/line.py @@ -13,7 +13,9 @@ class Value(Enum): """Logical line states.""" INACTIVE = _ext.VALUE_INACTIVE + """Line is logically inactive.""" ACTIVE = _ext.VALUE_ACTIVE + """Line is logically active.""" def __bool__(self) -> bool: return self == self.ACTIVE @@ -23,40 +25,58 @@ class Direction(Enum): """Direction settings.""" AS_IS = _ext.DIRECTION_AS_IS + """Request the line(s), but don't change direction.""" INPUT = _ext.DIRECTION_INPUT + """Direction is input - for reading the value of an externally driven GPIO line.""" OUTPUT = _ext.DIRECTION_OUTPUT + """Direction is output - for driving the GPIO line.""" class Bias(Enum): """Internal bias settings.""" AS_IS = _ext.BIAS_AS_IS + """Don't change the bias setting when applying line config.""" UNKNOWN = _ext.BIAS_UNKNOWN + """The internal bias state is unknown.""" DISABLED = _ext.BIAS_DISABLED + """The internal bias is disabled.""" PULL_UP = _ext.BIAS_PULL_UP + """The internal pull-up bias is enabled.""" PULL_DOWN = _ext.BIAS_PULL_DOWN + """The internal pull-down bias is enabled.""" class Drive(Enum): """Drive settings.""" PUSH_PULL = _ext.DRIVE_PUSH_PULL + """Drive setting is push-pull.""" OPEN_DRAIN = _ext.DRIVE_OPEN_DRAIN + """Line output is open-drain.""" OPEN_SOURCE = _ext.DRIVE_OPEN_SOURCE + """Line output is open-source.""" class Edge(Enum): """Edge detection settings.""" NONE = _ext.EDGE_NONE + """Line edge detection is disabled.""" RISING = _ext.EDGE_RISING + """Line detects rising edge events.""" FALLING = _ext.EDGE_FALLING + """Line detects falling edge events.""" BOTH = _ext.EDGE_BOTH + """Line detects both rising and falling edge events.""" class Clock(Enum): """Event clock settings.""" MONOTONIC = _ext.CLOCK_MONOTONIC + """Line uses the monotonic clock for edge event timestamps.""" REALTIME = _ext.CLOCK_REALTIME + """Line uses the realtime clock for edge event timestamps.""" HTE = _ext.CLOCK_HTE + """Line uses the hardware timestamp engine for event timestamps.""" diff --git a/bindings/python/gpiod/line_info.py b/bindings/python/gpiod/line_info.py index 1aca142..d31565e 100644 --- a/bindings/python/gpiod/line_info.py +++ b/bindings/python/gpiod/line_info.py @@ -16,17 +16,29 @@ class LineInfo: """ offset: int + """Offset of the line.""" name: str + """Name of the line.""" used: bool + """Indicates whether line is in use.""" consumer: str + """Name of the consumer of the line.""" direction: Direction + """Direction setting of the line.""" active_low: bool + """Active-low setting of the line.""" bias: Bias + """Bias setting of the line.""" drive: Drive + """Drive setting of the line.""" edge_detection: Edge + """Edge detection setting of the line.""" event_clock: Clock + """Event clock setting used for edge event timestamps for the line.""" debounced: bool + """Indicates whether line is debounced.""" debounce_period: timedelta + """Debounce period of the line.""" def __init__( self, diff --git a/bindings/python/gpiod/line_settings.py b/bindings/python/gpiod/line_settings.py index 2aca71c..3752acd 100644 --- a/bindings/python/gpiod/line_settings.py +++ b/bindings/python/gpiod/line_settings.py @@ -17,13 +17,21 @@ class LineSettings: """ direction: Direction = Direction.AS_IS + """Line direction.""" edge_detection: Edge = Edge.NONE + """Edge detection setting.""" bias: Bias = Bias.AS_IS + """Line bias setting.""" drive: Drive = Drive.PUSH_PULL + """Line drive setting.""" active_low: bool = False + """Active-low switch.""" debounce_period: timedelta = timedelta() + """Debounce period of the line.""" event_clock: Clock = Clock.MONOTONIC + """Edge event timestamping clock setting.""" output_value: Value = Value.INACTIVE + """Output value of the line.""" # __repr__ generated by @dataclass uses repr for enum members resulting in # an unusable representation as those are of the form: From patchwork Sun Dec 22 20:08:10 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 853020 Received: from mail-wr1-f50.google.com (mail-wr1-f50.google.com [209.85.221.50]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 35E2D191F98 for ; Sun, 22 Dec 2024 20:08:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.50 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898108; cv=none; b=JjDZxeQs701pJwg/U2GjDNP9D+BFsCkFDEPNUwu8nu2av04T0+cGpgPXVe9CyPIaVv8a41aw2FfdPvvBFx1+8TciI+VxSOr4qiTY/00JTUN0so/OhVjqW9BWoU3fiojFrbO1ULTnAwz04JoatETH4o57b/DhT9Vvklm+gkKPO6o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734898108; c=relaxed/simple; bh=okrZomR+HnBe/n0Q/3H8HmcZOFruD1bCBRkO+rK9YqA=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=iFveCk7BwoIMN92IK+gVGvNeAd+mBZSLv1W8mRflYBmqrlmYAOZs/SbYOHkDn0Hss6jb0YJWYPvPCCuKdKY2BUQEfMa94E3OPNTCQwUTI559B544la0n4KRnYmzZu41h+L6aJiutoghNYhw7DsroAWE2tAPRZoQCFNzxD/SNwLc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl; spf=none smtp.mailfrom=bgdev.pl; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b=Q4I7UaDz; arc=none smtp.client-ip=209.85.221.50 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="Q4I7UaDz" Received: by mail-wr1-f50.google.com with SMTP id ffacd0b85a97d-385e27c75f4so2653034f8f.2 for ; Sun, 22 Dec 2024 12:08:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1734898103; x=1735502903; darn=vger.kernel.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=F+lnsSVCSxJXIbhiRhlkB+ifVjCogn7UKJ23gEmWNj4=; b=Q4I7UaDzsnIsCLRVgnoPeEHw2HWHjwpTDAPp1SDGDTnQNPurLuWryPmNKjopPd1Mf/ XbZa4VLIZXxF9cRGV4WiduR80tpkg2PSMXbqv4nKfX6BwVkNV0NP1NOD7dBZReYSPxqi B5bM/KYFnmeMXuvXNh0A3nafNmKT16VDoV5no4v1UvI08ZEiSNzGbLubJlJP2rI9iosM Asr5xI9oLzxW7q9uX7OFqEOcOFe2Up7NKgZIb2MXqxI6wi4ogNpaMnmuC+tai1+6p5A+ sS7urVh23nHpF+dUX/1KlOaXqkg/TQ2UJfp1WWffHJqjc5uUhIY1BfdOV7a8COv7gYn1 r3dA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1734898103; x=1735502903; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=F+lnsSVCSxJXIbhiRhlkB+ifVjCogn7UKJ23gEmWNj4=; b=tz91PB2MZIO8kZkpxVulPmqBUDFFgeGU3foO90Ci6ryd9n+Y2HNVaVNzA93vS460lL BEqNA8/TbLiWJ9KzdvLIagMaJU71My/0JWDaq40Ni30rkwbSm1gjsCUad/e0qKnqKeVM aYuGKB8qJU8gfaKjmkhX3mxaZMsdfAMEEFYQXOgxyy+tq4HaipgwbgqFqHHiYiIv0wbd H8RcbShKmEe9lw8aVO+koOPKsk6dSGI5V4xQE+hHj9FnSvOpdg/p3A/1ygLzi6co/3or RNFakrU+z1SJtbtEdqSI1iGufoSBonj+5QTe+aCtv/YCMRXzqHrWhs2NHK43s67zWdCr mBUw== X-Forwarded-Encrypted: i=1; AJvYcCVqTlQd0gqRvxL9uPfP238fl3SjEB5yxnUTdQTEF2JuQL86lcqGDPwG3BbAsgUIxnAGQkCeUKhqOtgS@vger.kernel.org X-Gm-Message-State: AOJu0YzxsOgKpWUxrxDxm2MNJ/CwLIszCYX+KZCN7eY/9ZZPaWv1XlSH 2JSy8J8/DSY8lP0EDCkbm1jFN5EOMISo02f5hWzFfL6Eh/9UdZofFB4uqG/83LE= X-Gm-Gg: ASbGncuV2m/yDGDi99r9VJqZtl2Y9NNbWFQ487CEhyutGJRZ6MEoAgGJdXHd6gLUKVN ztu11ebk+0TxKFZ27kBYGgdfkjLl24vg/BC7BhPuvttb0YuaB5lv+DIB+VBB1iDez2p+reiSuBd TYY0VYsroK1HngvCuA5Bva6Ubvv63yon1vObycJe/x18Z1hBRVaa8jcuHe415jeVj8I4453uavU QM91CO4iYY5jPNT7Oe7HGQotbaBTZoolTZhJ6a05ALVu+b8 X-Google-Smtp-Source: AGHT+IHeRlRVRznQrGcxIiEUfCvnRZd2hJWMnkUmSVFHiLUm4D93WJvyi7qX+HS8tM9E8vvaYhYrEQ== X-Received: by 2002:a5d:5e09:0:b0:37c:d23f:e464 with SMTP id ffacd0b85a97d-38a223f75bdmr9896969f8f.38.1734898102615; Sun, 22 Dec 2024 12:08:22 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:a153:75c:4edb:ec23]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-38a1c833155sm9492900f8f.24.2024.12.22.12.08.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 22 Dec 2024 12:08:22 -0800 (PST) From: Bartosz Golaszewski Date: Sun, 22 Dec 2024 21:08:10 +0100 Subject: [PATCH libgpiod v2 5/5] doc: use sphinx in conjunction with doxygen Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20241222-improve-docs-v2-5-9067aa775099@linaro.org> References: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> In-Reply-To: <20241222-improve-docs-v2-0-9067aa775099@linaro.org> To: Vincent Fazio , Kent Gibson , Linus Walleij , Erik Schilling , Phil Howard , Viresh Kumar Cc: Bartosz Golaszewski , linux-gpio@vger.kernel.org X-Mailer: b4 0.14.1 X-Developer-Signature: v=1; a=openpgp-sha256; l=41610; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=HtxpZUVghrMaoS5bv8bk71h/y4oV3Xq1Rk7uVs0VwA0=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnaHGww/y02qDU70W0l/AL4i8MYjB6nlICVpqNX NWSYKljZK2JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ2hxsAAKCRARpy6gFHHX crvfEADRflxVbD6gbOIzD3nVUVfwsYea/dkWSsruK6HWzDEcHo/Sd38A5GEK6Irj5JxCsrOGfWS 9WKbmBSAtmYT8XVrGObV0tt3ISVMFsqtyUSPHa4+RpTDaiy5UsvVGPt68T1bgO/byDHvgX+fmJP 3Yn/jax1Aa8ZfyDA0jeXBj+guDtLSIeBm805ijD3QGNQY9LwpS9Aoc0lwPZ2XpOhoBwbijvuFRW bgG0fFbK16NjLqZgAXrWaOo+VZQMKR07o3EjHtQnatLXL9uW11E4ncOLuwiimzgyF8s3D452Tp2 aLeQxZjQGPx6MDDIqP3UcXc8WM5EXVwmq+Y2FtC/al1YOSGxn0NOYT/C6yRmy7N97MjDKczGKQK rEnYxlkig5i3Cfa7RJBgkkteN/FsOS3uppEDffFXOUEPBFdSie9GF6vslQc8vuCUl2AXaWPlt2L Qcblwwbxt9OgS81w3oCSkjO6/4+7o8KTWknM1uuVCHUgZ+Pn7I2dhK+U2zFIjy2UQCYNFXWjAie rYGoMZVeO4x+AJvPoKfuIjh6kosm821mvvOfcox4lSc+B8+GgnBo6Qm/UkL654Zhzc1emdYd/EH cAB8pUHbj6+2mZXW7/CrsifJqjTaJMlUiIzD0eeQ4RgTIUqEmPkcx9DWQVdiZdkzQ5dSanUd4J9 udgGwMiAPjIpedQ== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski 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. Signed-off-by: Bartosz Golaszewski --- .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(-) diff --git a/.gitignore b/.gitignore index c3a29d8..7b5fa15 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,6 @@ *.la generated-*.c generated-*.h -doc *.pc *.tar.gz *.patch @@ -16,7 +15,6 @@ tags # autotools stuff .deps/ .libs/ -Doxyfile Makefile Makefile.in aclocal.m4 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f40e95f..1243f11 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,6 @@ # SPDX-License-Identifier: LGPL-2.1-or-later # SPDX-FileCopyrightText: 2022 Kent Gibson +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski # # 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 diff --git a/Doxyfile.in b/Doxyfile.in deleted file mode 100644 index 9c85e21..0000000 --- a/Doxyfile.in +++ /dev/null @@ -1,105 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-or-later -# SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski - -# libgpiod doxygen configuration - -# General configuration -PROJECT_NAME = libgpiod -PROJECT_NUMBER = @VERSION_STR@ -OUTPUT_DIRECTORY = doc -OUTPUT_LANGUAGE = English -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_STATIC = YES -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ALWAYS_DETAILED_SEC = NO -FULL_PATH_NAMES = NO -STRIP_FROM_PATH = @top_srcdir@ -INTERNAL_DOCS = NO -STRIP_CODE_COMMENTS = YES -CASE_SENSE_NAMES = YES -SHORT_NAMES = NO -HIDE_SCOPE_NAMES = NO -VERBATIM_HEADERS = YES -SHOW_INCLUDE_FILES = YES -JAVADOC_AUTOBRIEF = YES -INHERIT_DOCS = YES -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -DISTRIBUTE_GROUP_DOC = NO -TAB_SIZE = 8 -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -ALIASES = -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -OPTIMIZE_OUTPUT_FOR_C = YES -SHOW_USED_FILES = YES -QUIET = YES -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_FORMAT = -WARN_LOGFILE = -INPUT = @top_srcdir@/include/gpiod.h \ - @top_srcdir@/bindings/cxx/gpiod.hpp \ - @top_srcdir@/bindings/cxx/gpiodcxx/ -SOURCE_BROWSER = YES -INLINE_SOURCES = NO -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -ALPHABETICAL_INDEX = NO -IGNORE_PREFIX = -SEARCHENGINE = NO -ENABLE_PREPROCESSING = YES - -# HTML output -GENERATE_HTML = YES -HTML_OUTPUT = -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -GENERATE_HTMLHELP = NO -GENERATE_CHI = NO -BINARY_TOC = NO -TOC_EXPAND = NO -DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 -GENERATE_TREEVIEW = NO -TREEVIEW_WIDTH = 250 - -# LaTeX output -GENERATE_LATEX = NO -LATEX_OUTPUT = -COMPACT_LATEX = NO -PAPER_TYPE = a4 -EXTRA_PACKAGES = -LATEX_HEADER = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO - -# RTF output -GENERATE_RTF = NO -RTF_OUTPUT = -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = - -# Man page output -GENERATE_MAN = YES -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_LINKS = YES - -# XML output -GENERATE_XML = YES - -# External references -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO diff --git a/Makefile.am b/Makefile.am index c824dc4..7807a0e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -44,15 +44,60 @@ SUBDIRS += dbus endif -if HAS_DOXYGEN +if WITH_DOCS -doc: Doxyfile - $(AM_V_GEN)doxygen Doxyfile -.PHONY: doc +DOCS_DEPS = \ + docs/conf.py \ + docs/core_api.rst \ + docs/core_chip_info.rst \ + docs/core_chips.rst \ + docs/core_edge_event.rst \ + docs/core_line_config.rst \ + docs/core_line_defs.rst \ + docs/core_line_info.rst \ + docs/core_line_request.rst \ + docs/core_line_settings.rst \ + docs/core_line_watch.rst \ + docs/core_misc.rst \ + docs/core_request_config.rst \ + docs/cpp_api.rst \ + docs/cpp_chip_info.rst \ + docs/cpp_chip.rst \ + docs/cpp_edge_event_buffer.rst \ + docs/cpp_edge_event.rst \ + docs/cpp_exceptions.rst \ + docs/cpp_info_event.rst \ + docs/cpp_line_config.rst \ + docs/cpp_line_info.rst \ + docs/cpp_line_request.rst \ + docs/cpp_line.rst \ + docs/cpp_line_settings.rst \ + docs/cpp_misc.rst \ + docs/cpp_request_config.rst \ + docs/Doxyfile \ + docs/index.rst \ + docs/python_api.rst \ + docs/python_chip_info.rst \ + docs/python_chip.rst \ + docs/python_edge_event.rst \ + docs/python_exceptions.rst \ + docs/python_info_event.rst \ + docs/python_line_info.rst \ + docs/python_line_request.rst \ + docs/python_line.rst \ + docs/python_line_settings.rst \ + docs/python_misc.rst \ + docs/requirements.txt + +docs: $(DOCS_DEPS) + sphinx-build docs/ docs/sphinx-output + +.PHONY: docs clean-local: - rm -rf doc + rm -rf docs/sphinx-output + rm -rf docs/doxygen-output -EXTRA_DIST += Doxyfile +EXTRA_DIST += $(DOCS_DEPS) endif diff --git a/README b/README index 80ad939..28a3dfd 100644 --- a/README +++ b/README @@ -333,14 +333,12 @@ bindings use the standard tests module layout and the #[test] attribute. DOCUMENTATION ------------- -All API symbols exposed by the core C API and C++ bindings are documented with -doxygen markup blocks. Doxygen documentation can be generated by executing -'make doc' given that the doxygen executable is available in the system. +The project uses sphinx to automatically generate the documentation. The system +needs to provide doxygen and sphinx-build programs. With those in place, the +build can be invoked with 'make docs'. This generates documentation for the +core C API as well as C++ and python bindings. -Python bindings contain help strings that can be accessed with the help -builtin. - -Rust bindings use rustdoc. +Rust bindings use rustdoc, GLib bindings use gi-docgen. Man pages for command-line programs are generated automatically if gpio-tools were selected and help2man is available in the system. diff --git a/configure.ac b/configure.ac index 78a6670..88ee367 100644 --- a/configure.ac +++ b/configure.ac @@ -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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..3793d27 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +doxygen-output +sphinx-output diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..e4e55f9 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,12 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2022 Bartosz Golaszewski + +PROJECT_NAME = libgpiod +OUTPUT_DIRECTORY = doxygen-output +INPUT = ../include/gpiod.h \ + ../bindings/cxx/gpiod.hpp \ + ../bindings/cxx/gpiodcxx/ +GENERATE_XML = YES +WARN_IF_UNDOCUMENTED = YES +QUIET = YES +EXTRACT_ALL = YES diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..fae849e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later +# SPDX-FileCopyrightText: 2022 Kent Gibson +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +# This file is part of libgpiod. +# +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import re +import subprocess +import sys +from pathlib import Path + +sys.path.insert(0, str(Path("../bindings/python").resolve())) + +project = "libgpiod" +copyright = "2017-2024, Bartosz Golaszewski" +author = "Bartosz Golaszewski" + +# Extract the full version from configure.ac (including -devel, -rc and other +# tags). +with open("../configure.ac", "r") as fd: + version = "" + extra = "" + for line in fd.readlines(): + match = re.search(r"AC_INIT\(\[libgpiod\], \[(.*?)\]\)", line) + if match: + version = match.group(1) + continue + + match = re.search(r"AC_SUBST\(EXTRA_VERSION, \[(.*?)\]\)", line) + if match: + extra = match.group(1) + + release = f"{version}{extra}" + +subprocess.run(["doxygen", "Doxyfile"]) + +master_doc = "index" +source_suffix = ".rst" + +extensions = ["breathe", "sphinx.ext.autodoc"] + +breathe_projects = {"libgpiod": "./doxygen-output/xml"} +breathe_default_project = "libgpiod" + +autodoc_mock_imports = ["gpiod._ext"] + +# Use the RTD theme if available +sphinx_rtd_theme = None +try: + import sphinx_rtd_theme + + extensions.append("sphinx_rtd_theme") +except ImportError: + pass + +html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default" diff --git a/docs/core_api.rst b/docs/core_api.rst new file mode 100644 index 0000000..58b9012 --- /dev/null +++ b/docs/core_api.rst @@ -0,0 +1,58 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod core API documentation + +libgpiod core API +================= + +This is the complete documentation of the public API made available to users of +libgpiod. + +The API is logically split into several sections. For each opaque data class, +there's a set of functions for manipulating it. Together they can be thought +of as objects and their methods in OOP parlance. + +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. + + +.. toctree:: + :maxdepth: 1 + + core_chips + core_chip_info + core_line_defs + core_line_info + core_line_watch + core_line_settings + core_line_config + core_request_config + core_line_request + core_edge_event + core_misc diff --git a/docs/core_chip_info.rst b/docs/core_chip_info.rst new file mode 100644 index 0000000..40a5ca6 --- /dev/null +++ b/docs/core_chip_info.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygengroup:: chip_info diff --git a/docs/core_chips.rst b/docs/core_chips.rst new file mode 100644 index 0000000..758f365 --- /dev/null +++ b/docs/core_chips.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygengroup:: chips diff --git a/docs/core_edge_event.rst b/docs/core_edge_event.rst new file mode 100644 index 0000000..65ea53c --- /dev/null +++ b/docs/core_edge_event.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygengroup:: edge_event diff --git a/docs/core_line_config.rst b/docs/core_line_config.rst new file mode 100644 index 0000000..5dc8bcb --- /dev/null +++ b/docs/core_line_config.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygengroup:: line_config diff --git a/docs/core_line_defs.rst b/docs/core_line_defs.rst new file mode 100644 index 0000000..08ec6fc --- /dev/null +++ b/docs/core_line_defs.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line definitions +===================== + +.. doxygengroup:: line_defs diff --git a/docs/core_line_info.rst b/docs/core_line_info.rst new file mode 100644 index 0000000..e90059a --- /dev/null +++ b/docs/core_line_info.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line information +===================== + +.. doxygengroup:: line_info diff --git a/docs/core_line_request.rst b/docs/core_line_request.rst new file mode 100644 index 0000000..39b87ad --- /dev/null +++ b/docs/core_line_request.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================== + +.. doxygengroup:: line_request diff --git a/docs/core_line_settings.rst b/docs/core_line_settings.rst new file mode 100644 index 0000000..cc84345 --- /dev/null +++ b/docs/core_line_settings.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygengroup:: line_settings diff --git a/docs/core_line_watch.rst b/docs/core_line_watch.rst new file mode 100644 index 0000000..61fc007 --- /dev/null +++ b/docs/core_line_watch.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line watch +=============== + +.. doxygengroup:: line_watch diff --git a/docs/core_misc.rst b/docs/core_misc.rst new file mode 100644 index 0000000..414a97a --- /dev/null +++ b/docs/core_misc.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod misc interfaces +======================== + +.. doxygengroup:: misc diff --git a/docs/core_request_config.rst b/docs/core_request_config.rst new file mode 100644 index 0000000..9433406 --- /dev/null +++ b/docs/core_request_config.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygengroup:: request_config diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst new file mode 100644 index 0000000..8e6df40 --- /dev/null +++ b/docs/cpp_api.rst @@ -0,0 +1,33 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + 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 diff --git a/docs/cpp_chip.rst b/docs/cpp_chip.rst new file mode 100644 index 0000000..694a21c --- /dev/null +++ b/docs/cpp_chip.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygenclass:: gpiod::chip + :members: diff --git a/docs/cpp_chip_info.rst b/docs/cpp_chip_info.rst new file mode 100644 index 0000000..ce9d07b --- /dev/null +++ b/docs/cpp_chip_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygenclass:: gpiod::chip_info + :members: diff --git a/docs/cpp_edge_event.rst b/docs/cpp_edge_event.rst new file mode 100644 index 0000000..0be8fdd --- /dev/null +++ b/docs/cpp_edge_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygenclass:: gpiod::edge_event + :members: diff --git a/docs/cpp_edge_event_buffer.rst b/docs/cpp_edge_event_buffer.rst new file mode 100644 index 0000000..2e044d0 --- /dev/null +++ b/docs/cpp_edge_event_buffer.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event buffer +====================== + +.. doxygenclass:: gpiod::edge_event_buffer + :members: diff --git a/docs/cpp_exceptions.rst b/docs/cpp_exceptions.rst new file mode 100644 index 0000000..2357a87 --- /dev/null +++ b/docs/cpp_exceptions.rst @@ -0,0 +1,18 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod exceptions +=================== + +.. doxygenclass:: gpiod::chip_closed + :members: + +.. doxygenclass:: gpiod::request_released + :members: + +.. doxygenclass:: gpiod::bad_mapping + :members: diff --git a/docs/cpp_info_event.rst b/docs/cpp_info_event.rst new file mode 100644 index 0000000..b389d6f --- /dev/null +++ b/docs/cpp_info_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. doxygenclass:: gpiod::info_event + :members: diff --git a/docs/cpp_line.rst b/docs/cpp_line.rst new file mode 100644 index 0000000..adf23ad --- /dev/null +++ b/docs/cpp_line.rst @@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiodcxx line definitions +============================ + +.. doxygenclass:: gpiod::line::offset + :members: + +.. doxygenenum:: gpiod::line::value + +.. doxygenenum:: gpiod::line::direction + +.. doxygenenum:: gpiod::line::edge + +.. doxygenenum:: gpiod::line::bias + +.. doxygenenum:: gpiod::line::drive + +.. doxygenenum:: gpiod::line::clock diff --git a/docs/cpp_line_config.rst b/docs/cpp_line_config.rst new file mode 100644 index 0000000..a3fc714 --- /dev/null +++ b/docs/cpp_line_config.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygenclass:: gpiod::line_config + :members: diff --git a/docs/cpp_line_info.rst b/docs/cpp_line_info.rst new file mode 100644 index 0000000..d2e8eeb --- /dev/null +++ b/docs/cpp_line_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line info +============== + +.. doxygenclass:: gpiod::line_info + :members: diff --git a/docs/cpp_line_request.rst b/docs/cpp_line_request.rst new file mode 100644 index 0000000..f2ae4f8 --- /dev/null +++ b/docs/cpp_line_request.rst @@ -0,0 +1,15 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. doxygenclass:: gpiod::request_builder + :members: + +.. doxygenclass:: gpiod::line_request + :members: diff --git a/docs/cpp_line_settings.rst b/docs/cpp_line_settings.rst new file mode 100644 index 0000000..e9bc067 --- /dev/null +++ b/docs/cpp_line_settings.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygenclass:: gpiod::line_settings + :members: diff --git a/docs/cpp_misc.rst b/docs/cpp_misc.rst new file mode 100644 index 0000000..ce6ba4c --- /dev/null +++ b/docs/cpp_misc.rst @@ -0,0 +1,16 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiodcxx misc interfaces +=========================== + +.. doxygenclass:: gpiod::timestamp + :members: + +.. doxygenfunction:: gpiod::is_gpiochip_device + +.. doxygenfunction:: gpiod::api_version diff --git a/docs/cpp_request_config.rst b/docs/cpp_request_config.rst new file mode 100644 index 0000000..476cfa6 --- /dev/null +++ b/docs/cpp_request_config.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygenclass:: gpiod::request_config + :members: diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b7cb6ef --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,28 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + 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 diff --git a/docs/python_api.rst b/docs/python_api.rst new file mode 100644 index 0000000..a90afe6 --- /dev/null +++ b/docs/python_api.rst @@ -0,0 +1,31 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + 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 diff --git a/docs/python_chip.rst b/docs/python_chip.rst new file mode 100644 index 0000000..83d34bd --- /dev/null +++ b/docs/python_chip.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. autoclass:: gpiod.Chip + :members: diff --git a/docs/python_chip_info.rst b/docs/python_chip_info.rst new file mode 100644 index 0000000..8116ef7 --- /dev/null +++ b/docs/python_chip_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. autoclass:: gpiod.ChipInfo + :members: diff --git a/docs/python_edge_event.rst b/docs/python_edge_event.rst new file mode 100644 index 0000000..6c77a38 --- /dev/null +++ b/docs/python_edge_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. autoclass:: gpiod.EdgeEvent + :members: diff --git a/docs/python_exceptions.rst b/docs/python_exceptions.rst new file mode 100644 index 0000000..c247321 --- /dev/null +++ b/docs/python_exceptions.rst @@ -0,0 +1,17 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod python errors +====================== + +.. autoclass:: gpiod.ChipClosedError + :members: + :show-inheritance: + +.. autoclass:: gpiod.RequestReleasedError + :members: + :show-inheritance: diff --git a/docs/python_info_event.rst b/docs/python_info_event.rst new file mode 100644 index 0000000..6d32368 --- /dev/null +++ b/docs/python_info_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. autoclass:: gpiod.InfoEvent + :members: diff --git a/docs/python_line.rst b/docs/python_line.rst new file mode 100644 index 0000000..3a63ae5 --- /dev/null +++ b/docs/python_line.rst @@ -0,0 +1,27 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line definitions +===================== + +.. autoclass:: gpiod.line.Value + :members: + +.. autoclass:: gpiod.line.Direction + :members: + +.. autoclass:: gpiod.line.Bias + :members: + +.. autoclass:: gpiod.line.Drive + :members: + +.. autoclass:: gpiod.line.Edge + :members: + +.. autoclass:: gpiod.line.Clock + :members: diff --git a/docs/python_line_info.rst b/docs/python_line_info.rst new file mode 100644 index 0000000..2e0faeb --- /dev/null +++ b/docs/python_line_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line info +============== + +.. autoclass:: gpiod.LineInfo + :members: diff --git a/docs/python_line_request.rst b/docs/python_line_request.rst new file mode 100644 index 0000000..47fa734 --- /dev/null +++ b/docs/python_line_request.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. autoclass:: gpiod.LineRequest + :members: diff --git a/docs/python_line_settings.rst b/docs/python_line_settings.rst new file mode 100644 index 0000000..b15ba26 --- /dev/null +++ b/docs/python_line_settings.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. autoclass:: gpiod.LineSettings + :members: diff --git a/docs/python_misc.rst b/docs/python_misc.rst new file mode 100644 index 0000000..ea3f43c --- /dev/null +++ b/docs/python_misc.rst @@ -0,0 +1,13 @@ +.. + SPDX-License-Identifier: CC0-1.0 + SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod python bindings misc +============================= + +.. autofunction:: gpiod.is_gpiochip_device + +.. autofunction:: gpiod.request_lines diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..535321c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski + +breathe==4.35.0 +sphinx-rtd-theme==3.0.2 diff --git a/include/gpiod.h b/include/gpiod.h index 75c55d9..6d40275 100644 --- a/include/gpiod.h +++ b/include/gpiod.h @@ -16,42 +16,6 @@ extern "C" { #endif -/** - * @mainpage libgpiod public API - * - * This is the complete documentation of the public API made available to - * users of libgpiod. - * - * The API is logically split into several sections. For each opaque data - * class, there's a set of functions for manipulating it. Together they can be - * thought of as objects and their methods in OOP parlance. - * - * General note on error handling: all functions exported by libgpiod that - * can fail, set errno to one of the error values defined in errno.h upon - * failure. The way of notifying the caller that an error occurred varies - * between functions, but in general a function that returns an int, returns -1 - * on error, while a function returning a pointer indicates an error condition - * by returning a NULL pointer. It's not practical to list all possible error - * codes for every function as they propagate errors from the underlying libc - * functions. - * - * In general libgpiod functions are NULL-aware. For functions that are - * logically methods of data classes - ones that take a pointer to the object - * of that class as the first argument - passing a NULL pointer will result in - * the program aborting the execution. For non-methods, init functions and - * methods that take a pointer as any of the subsequent arguments, the handling - * of a NULL-pointer depends on the implementation and may range from gracefully - * handling it, ignoring it or returning an error. - * - * libgpiod is thread-aware but does not provide any further thread-safety - * guarantees. This requires the user to ensure that at most one thread may - * work with an object at any time. Sharing objects across threads is allowed - * if a suitable synchronization mechanism serializes the access. Different, - * standalone objects can safely be used concurrently. Most libgpiod objects - * are standalone. Exceptions - such as events allocated in buffers - exist and - * are noted in the documentation. - */ - /** * @struct gpiod_chip * @{ diff --git a/sphinx/conf.py b/sphinx/conf.py deleted file mode 100644 index 790c884..0000000 --- a/sphinx/conf.py +++ /dev/null @@ -1,68 +0,0 @@ -# SPDX-License-Identifier: LGPL-2.1-or-later -# SPDX-FileCopyrightText: 2022 Kent Gibson - -# This file is part of libgpiod. -# -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -import subprocess - -subprocess.run("cd .. ; ./autogen.sh ; make doc", shell=True) - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- Project information ----------------------------------------------------- - -project = "libgpiod" -copyright = "2022, Bartosz Golaszewski" -author = "Bartosz Golaszewski" - -# The full version, including alpha/beta/rc tags -release = ( - subprocess.run(["git", "describe", "--dirty"], capture_output=True) - .stdout.decode() - .strip() -) - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = [] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -root_doc = "contents" - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "alabaster" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] - -html_extra_path = ["../doc/html"] diff --git a/sphinx/contents.rst b/sphinx/contents.rst deleted file mode 100644 index c26d068..0000000 --- a/sphinx/contents.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. - SPDX-License-Identifier: LGPL-2.1-or-later - SPDX-FileCopyrightText: 2022 Kent Gibson - -.. - 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`