From patchwork Tue Feb 11 12:59:22 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864626 Received: from mail-wm1-f54.google.com (mail-wm1-f54.google.com [209.85.128.54]) (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 24894217677 for ; Tue, 11 Feb 2025 12:59:39 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.54 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278783; cv=none; b=jUIzlnt6SRyBjP05208QX+Rcg5XdTVAa/u1n1/V+oFwpWggAEpkA+CgydRA8G9iD+FabI2gkktzd+rlRgAXtYWeCD7gXHXbdniBlttMCGFsPpa4YEM3ESU1rMEg5Vx+X/oSrdEdUStPu5xeR2+Jq9oDWv0uc0g62iS7js7TSMyU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278783; c=relaxed/simple; bh=hoHBTR9TOL1ZwazPya3p072s+4nDSW8c30s00S0GpdQ=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=Rs/q6HJ/S12FjErBWx5WA2kCYNHGKkKsbgbqjk6DzapnKfj2qdjbw3OsoIaGVkWM2ZOSLy3O/wAtLmugdlbpJxOp2KE9blo0pZBKS/2y1tsGMe8qTZTIVWMfxQHAuG2KdQMAA+ZePbDoes2ZeLZHem/XbEallFD7h6p0mhVgZ7U= 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=ZPuD7CBc; arc=none smtp.client-ip=209.85.128.54 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="ZPuD7CBc" Received: by mail-wm1-f54.google.com with SMTP id 5b1f17b1804b1-439554db49dso4993015e9.1 for ; Tue, 11 Feb 2025 04:59:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278778; x=1739883578; 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=cX9VVeruVQ7eRfdbechwCOPULJXVbEkw4OVdlGOjQXQ=; b=ZPuD7CBcITeUfx5iQLlCtkLQZ/eVB+DQ81TYVhNcrenegf/rez2KGvSFTsn3cP4GpF 3kY55oP1aSo1NQ1PVCxyNbFNbuwnPTTrQD9H7JwRL2svCEHx+6G/jYNw0Weo1R70wrNq IXszdwArBiJtaPOn21LFUfnzvN4M8ot5AFqHTcVlNzzoGp9ZFkKAxtJgGtzSWntjAD4W nXpVSBARRRqaX22OK69qFS3WCBa0+TZRjAqV6eu4sx6JipQzar0jcUXyU4fg2JN9UXwu vJ2ibaixkb1GdPMQnYESXkjJ66JneTYlwqItY6vn1h6OFCE2sJBP8WXiSDOo4QZMVR7C P+cQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278778; x=1739883578; 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=cX9VVeruVQ7eRfdbechwCOPULJXVbEkw4OVdlGOjQXQ=; b=Z68qJQyRmoDr88EEjHjiANOu6bQmzTXw471qUY8kROnwPJiWhAB6N5ypBWMCDym7c4 izy6UdaIaK+F/efUs96khN8U0VKKLYwL8F/kAqOumbVSZlg3Vnc07HFWTb/6/p+wbv0o SDJiR1c7xxvgpAmQ7NEF2ogmHl3yQwL/VQVTs5STkU6chpcsHoY0ZgpBwpbfOJJVTQAV epZ1+DgxkiZpzDEGRVUcfckqoT069W5Bi04GQDv5tP+wiatGQEUVACDgzb0EdcfnyyfQ JTfrYq4MV+B775cJYeXGQBIooD13iQ7VP62XLdGlwv2IhPQgAfqH16WxZNMsoWMIFVy+ Y7+g== X-Forwarded-Encrypted: i=1; AJvYcCXY+s7FcsyejzqwiehGdxIjxi5RdZGxFbNXBk7D5woIuvCo8fi0FQC86JVPpLPSicWwLlm466jaY8lU@vger.kernel.org X-Gm-Message-State: AOJu0Yx8WGGaSouzlm23iqBpIToLDg+5ZC5q5tRHl/4+UnX2KpOH2wRh qNodugGicPPEAZz8CUzm/H+8W0AQJYuk4DqrhIq2LfPHRpsdtWVe9lSiPQZXlxU= X-Gm-Gg: ASbGnctAcvTLxICySj3jPSstNOks1XaKkWkVOkmPLJh5YRaua7ZSvOobTNa7WD1lgLu 63YYBwkn4bk1tQwk5xSdRmpGrduOsNkWHXa5k3XBk9I2C0w6OghNS0otdrTT4+POoOCw/YCm3iG h3JdGAywL9cCNJJLF5jkXGfm8OVPpLIwfn3ptEj2kUvla45S0REKfoI6aQeHHDhw+oZ8aKcd7mq nncuUvawb9193yCUWu5HU+7xz6etY5iOpz2+KJmzpYxOO6QGjH918a6w9eJ0a01UVZFzZTbgkWB I9xMr24= X-Google-Smtp-Source: AGHT+IHQ/rHrFgniXog8tTw/tFz0mHcOwIIDFgl1EqTVbGN0+TjiJpaQsGFBes8T3Qf1kAI90VQw2A== X-Received: by 2002:a05:600c:3482:b0:439:42c6:f108 with SMTP id 5b1f17b1804b1-43942c6f621mr81784235e9.6.1739278778429; Tue, 11 Feb 2025 04:59:38 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:37 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:22 +0100 Subject: [PATCH libgpiod v4 01/17] build: set PACKAGE_URL Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-1-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=669; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=uL9eOG2xv0BMz+LonRXot+ZirkyYIT8F4vCr7Ugi4KA=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m0eI6BKbHm5ojBdN894BKwG84nkDn37vk+g 2/0b5WwKNCJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtAAKCRARpy6gFHHX csbmD/4iECJBitrsIhIEmKX59r8vrcSrmV/6NT0iQeyLZsqZE59GpEW+XjQKg1cTeL7KjrSewOT 6oLNBA2/Jd6Cljwx4aSXnxZYajNYbRxNddBEuGNWtBT3unag9aRrzw77a1iITXzxb1StXJr9B9x eZZ8kknXI4jybryiOjziZoLJiK9nYFHMvKc1aM8G77hWMjUSWQT2lcYPEVXXnX94l3DRjD1ExSo 0tt/j+IlRMnd69Mu2QAYujo3dXs25XzqW8b0x+2lsQZ+WmvKHCtP4xn+eZ6y/MXpmbiE2BMK8OY WXcXaXvoUAGQuS/5PqJMH0xeJeqshEq/FvZ/45YPKpMz+Mj7MkOKnV7eB3pwJYKD9MqFzzbE7fc CXc8DpCGdnVnvhoTqN8aTYlmQAagdT81jEEp8THTbN5Emy7bDCb0jGqKU5qfQ5fuqgzWGFirUHB kM1RX7XOC7MmHIeduFxpz3X04FzOCyD4ftemz1U/jgpSfQzYh5L7K5AH1EjilCAoXLYVwkXG+tA /9t8ZTEOjGo81X7jS5hPGYSEM7Eux8B80m+75aYCtqu7l6A/ruKJSM9YQ+26zlvpXgk0Mxonz3t n8CxJoTj/6HHZb1qUxyu4f1cCv4zDDKQlx+aR47or4nZPzwwQN4NcFxNK3/hFtl7oWBlj/0iq/h ke9UhfJZsfwbtLw== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski We don't set the package URL in AC_INIT() so the URL section in pkgconfig files is empty. Set it to the address of the main git repo. Signed-off-by: Bartosz Golaszewski --- configure.ac | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index 78a6670..34de870 100644 --- a/configure.ac +++ b/configure.ac @@ -3,7 +3,8 @@ AC_PREREQ([2.71]) -AC_INIT([libgpiod], [2.3]) +AC_INIT([libgpiod], [2.3], [], [], + [https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/]) AC_SUBST(EXTRA_VERSION, [-devel]) AC_DEFINE_UNQUOTED([GPIOD_VERSION_STR], From patchwork Tue Feb 11 12:59:23 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864625 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 245D5216E1D for ; Tue, 11 Feb 2025 12:59:40 +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=1739278784; cv=none; b=L56ttcj8nP/X6l16CGMPALpgi/elW/QPIiw6Y1u8QxtgM8HB9AvcPVTO0TF5024t/vcx1QkUMpafh0AXuTfIslqzzpWKaLO1IKdfm/w+QfWRSoBIHIkcQgVuJ0KspeA4YzxVxIZCYYjks/CL3wAY/kwZ2+JTMGVb0VP8m4ZuNwg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278784; c=relaxed/simple; bh=0kbUWR2z9wlXm8RVPEQnbnh1RvUEhAz6KQpoEXpU1o0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=HzDaBfdkkrULkfc1xgaQ2dOYhEUUm0Lj7S4UNhxsSGcQljVIFAHoLJytcU8Yc//BM/9/ZbFW1yT0zGtA8fUBkXifLHLD1BKqWtirvehDC4M3bMIwBcZ6hryCiX8ZQcVjHzSLAWY+vzcfLKmWPn+XigaBvJuVR44D2l2BgyYjY9U= 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=XxAJR+WZ; 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="XxAJR+WZ" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-43948f77f1aso11633845e9.0 for ; Tue, 11 Feb 2025 04:59:40 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278779; x=1739883579; 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=XxAJR+WZiVI2/W12FZUf/323Ddg8w3E6PGOeu/TZ76BEVJwWseTb09TGzqlYrjJygq vxpYnwxR5WZ4Z8xL1/iAFJjp5F/guVYvn0lScLa+3wP3L7SMMi1qC/r+lY04aFAtZegn R188w+Gkzd/eH1d95MULGfTjHclH+zLMR1WJ3BnKNb8Cp0u5o2YOkPVuuBLs1YTpr8gl vhFHmcAirASOuvJTaw9TwWlR1Pm+WQu47TeITVohjossrEmgSAx0CgFVy6VC2T3l0sJN kUHAd5l1ZN4Ey6I4hbQmgEuiD7SvdzrcQxkXjWaZktG/fdjEggO+mk/5ZPK3VTD5CNRW IOjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278779; x=1739883579; 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=QGkUgc793dTmzOReubQmfYvXaf8SGAka0uNhVsrP5dESlXBsDFzSLJzGG7UfE5/Wnz SNNvDy7sG44PTZMR1DutVVKNojgwbVW1vdIK4AbDvdIvj2L9y9HU9uw5ysQpbc1AfUqP HrmVDif1bME88BnDc2BrL6dk3dZ+SY4p57RySpFrr1UnBMHYgSYKQOGVhiYpocLfV0YM T9O6JE3veuQ4LneX3d7wJyKcxFGnoaRSEDdQ6r4p76sQc9xTQHqo+UOQK4j4+qSUsgNW 3m9t5voLnMpCI3chO+ygRv5H7R0yrlqN2Br883CIiqz1yBbD0YHQR+uZ6kYslw20kfn+ bBdQ== X-Forwarded-Encrypted: i=1; AJvYcCWtb8h2q02L0zp7ncbjx5/YPn0P11a9xzJHy16cVocwbezz9vdRXSKSW6VCZihl/5Npgh49sQBZBX+G@vger.kernel.org X-Gm-Message-State: AOJu0Yw3BBXbIaLHOvH0anS3aOh/AxLQzurf7ggPggKnV7gxVd8lpy4l EWxH9E6EWe5MVp/CeWJb0VzYnQ5GRsHwNbIJ1zqBtWIxW2DVRi3vzeqrDU9PBao= X-Gm-Gg: ASbGncubPqsK/4nEj90rB44CohKeksyvxjs6E7lBC00uBlW2PyTDC1v1MMGfqbEIqhM CG9zQo8uy/aLPiY8LQ3jMgJWwaNXJu65eVWOGBh9qKH7ibgL3rJVOVuyp7bR7PwyIjmWareRRfj wIF53PqOQsXl1T6sToyBNTJ/uFrkBzRXs4ha6PUbuqHomw7ashRK28CghtJDac9/7t5I/MOzERo xgOx9nS7BVzP2Qde7/fuYHmO+qalIZkg7NNPeiXq4KA5aaSiuSeckw5uYTr9+akQV+68wYtxrjC Dz7mU+0= X-Google-Smtp-Source: AGHT+IEHzuXax/XMGd25n1zQbPSrzxvW8vsScedHCL0o1fDW6CQQYo4wBMC3L0GMLzbKWFak4YsGXQ== X-Received: by 2002:a05:6000:1886:b0:38d:d8c0:1f77 with SMTP id ffacd0b85a97d-38dd8c022b3mr8917970f8f.43.1739278779278; Tue, 11 Feb 2025 04:59:39 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:38 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:23 +0100 Subject: [PATCH libgpiod v4 02/17] 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: <20250211-improve-docs-v4-2-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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/ZANAwAKARGnLqAUcddyAcsmYgBnq0m14GqS1cfaAs6ckzA5V8eSe/CNv+HenveLY f9oXzn163qJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtQAKCRARpy6gFHHX cltdD/9clR10Pz6vm0Qg05ooFONTCQ1egjeYG6N73yX1LY4Xo1vF/D8fwt/psW6f4KJLwjWBEh6 dtNKLI2p429aWzC/QH0g0qar0kFGb7jXGT8o+Es5lX1z1lUK1e6nz8idZECozbOBCc6cNhiS7aj FD+e/8Z216jo5JqAtzr3P8hfidZUtsW50PtzVPjeEnK5wV1B5nm1EobKwxh2Hv9szJVvwVBmtQr rSV29dl8Qs6ORTrB8dgb9sadYBcRT7bEHbVkyEmeri+lFRDyzQjZyE6dIhY0w+WyJIqN4WoFT4B ZdLxKVm1uy3KmnHC1jZL4NCG+ayAIDijPa7Eo1FsOURRWE80j/6F++qzPnpXRusj9KtaQZuHHrc 15k3HfAleXMNvRS2I+LipWBdlR9LvaamSMvavm196mhtI2VpvPwBec80OnDv4uipiTx1dUxbCVv Fjv2IzDf5/KtOB1jq/5f3lnM3r0aSEt/v5w4sG2yQL7+1VGKn1ylHL1MRK7+1BayW70oKHioXBw PZfngnzsMojlX9yvh0lBww/L81UTPfwGfT9o3sh0FlgQKXEaN4ceYbRGv9wdQrSBCTh6nFrh8Ib iw0TjuE9DHaLa29IkJ9iFMNnEns3wQZ9bD2EYHHrgN28OYxAB36hOoCdb+KZcqYJMNEImTCHsnN rlx3oYOkWHr6rVw== 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 Tue Feb 11 12:59:24 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864219 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (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 1B92E215F42 for ; Tue, 11 Feb 2025 12:59:41 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278783; cv=none; b=dv+p5dVGHugaOicDP++Svdbo/oH2dVYEqJO5qkW0EPMsbgg1v12A5wQzq/hT/qVt21Pxz7BUIlbcxni922nvQCOB0/CiP1DiO98bj2j0ppOgoo6AumB7rr66BmM4cLd1k303WObGcczuG8SxwI43WFpkwAd08TsY6SHLe5qRh1Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278783; c=relaxed/simple; bh=Xhx8I1RT8tRAlh1w32C6GuYPL3m92Qx4xndok+mVN0g=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=NJIzaNjrFgGrkkCmQPENmLPiFSrIv/FvuWqjyfyAwOw2806DWPanDEVS0K1yO+8eGm1yrjQt64aR0OSC3Iyfhh6im4fuvik2DWM32+MWCgCHLKgK4/ZE66/blpu2ZInU1EVuEe8lg+28uMTFKy1MBQWtNtIyWkHpFrUsFWLcNYI= 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=S7WDezW1; arc=none smtp.client-ip=209.85.128.51 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="S7WDezW1" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-43944c51e41so21916695e9.0 for ; Tue, 11 Feb 2025 04:59:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278780; x=1739883580; 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=zEqkRuUVrt/6To7a12oQ0QZUf+6LHMqjT8FfLiEpQWk=; b=S7WDezW1YA+uXqHNcQf92IKieOMZewC6pSffvCDFYUK8ol6tWhngVim8XNSznufPtU hGq3MQBuQsb5n4mxGRSFwGifT2MjeX8TyCz0r05uZezfYfwINpusKHPISt9vbIkd4Jk5 FBeY+7ERFMQQONXpFpZl4xMKxKj4Tf+mNRnyF39ArJXO8tstLHW7StxFZT0zBwA+v1pg XunYUq2Uie5c8RET5TKf2+HjhYLFVRGP792kjvBTQxXfSkdl/OvWBTAHXhGg/vdZTgmv AlgTnPhgzdF9XEITbcnDp7Rk3hQVEiyrdlGF81qTrBOuip/S03eEQeUmiN3muc4hwVVS Wy5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278780; x=1739883580; 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=zEqkRuUVrt/6To7a12oQ0QZUf+6LHMqjT8FfLiEpQWk=; b=C5AOsFv5VLirpiWXKWKur7yop3gMYuJZEIYVL6YzM96HdXAtTt00oi6ycYNNRwX2qH P2L76DlRxoCDswzJkJOFXipnvJPEXRYmzLBc0nIdSdLLhybVxh7C3IU2VDjW2MC6NRhE qNN0IwM4ubXlfwTQ1W+a9yWuDKfD2zpf7xOsDXa9U06G881hke2uro6brQ9AaE74fYO4 ssbHKB+j2ZC/2BsUAuGx728qgKngUa3goVOn2ePqZY2lcJ4dk0EUuXC0+2JFZL8HNDQo /Ur7OBXHTxPg4BK490/0TlgzyGy9YhUGCp5bdzcadAsKppQWaD3mY8z65nf+RQl9hDCY +kCg== X-Forwarded-Encrypted: i=1; AJvYcCVePXNd1Ka0YVWiHDeoBYhaOuragHehaYupSikOfSq8mOOWaJkgtBG4DbN5DeYXtrY51u80Z4szuN6e@vger.kernel.org X-Gm-Message-State: AOJu0Yy03F0i0UqBDorf/K2Nfg0UPiVyR8+CsowwElQfxChNFx8n1yK1 uRAl2ZC33gOc3VLzx8Ln/RiN35WTsFMm6EbWX8z68X20idDsDexX28z5pwM5wzk= X-Gm-Gg: ASbGncs3CSKcFTR/OmTcN/bdpw397V0YvKe73DvW3ZYJZKDSCHtdUFPDcaHPdwRkkPk dwkZJBAZXZ70hXB0UgUg9t4neT3+s1GVcviJ5uTb2xAp0jDE80bxi9OMbE2lE82g8D+cs6VKjpA pbUGbTHFENCzs+NphYxxaxL7+RDnKswSssreQevTgKJq9db0XKY0i3bxJ1Wm1WT4YWAs4tHgmPL 5XQ0TZZvJ7qtbLi5zykC0t3BLvd4rzTObVICL/gCSJXw8XnrQX5teBbi3MhHIKx3ICjmhitYOff 811gm6M= X-Google-Smtp-Source: AGHT+IHGXUSO0pPbwZ/qj7EObNe+fMSJu9V1qsIRXNnju8O0Hst+KLwvEOdVB5QPGzskoLkATSyhSg== X-Received: by 2002:a05:600c:1e14:b0:439:4d86:98c2 with SMTP id 5b1f17b1804b1-4394d8699fbmr26311775e9.29.1739278780302; Tue, 11 Feb 2025 04:59:40 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:39 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:24 +0100 Subject: [PATCH libgpiod v4 03/17] 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: <20250211-improve-docs-v4-3-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=1543; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=JJ3iUo1uXw5+ZWJPe5ttDwDK3Nl44JJtkWrt73AVAtM=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m1B4+X3U8f2SwttTO0FrzV5trRjoWpZvKLg DTqO1vbrk6JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtQAKCRARpy6gFHHX cmVtD/4kta9h4bkbCcHDEIYZyYP32QzIoVkMWhKqRYD/t4KPr8uPLQoyTQeTr4BEMDZsA8A8WhJ AokyJ0DBC3ginCAkp8LIbzGXHK6KHCYM8VExDZigye6zS4EPeuP66ef0uWaqmzSEnaPA1pHTNmR 0+nbFlIvzzVT4stMgwfJBU3ZOCt1kC3te6gXzVrZ4kEfgu1QxqS/bF9cyVhPeI4g5pVdKnqZqYC wQvvfdnKGnr6+hbVjer0zWiW4dnjOyMCJQPpv5FH+3v2Co1iJIYeCcnLDgGUGIRiXk6Tc1hBgLv WzXU4FYZ5L/ghR+qZfgazy1cP4Fvw8DVmzZWEUkcNMZWawZI2YDxEy8XgtLF6NswChDU10jHU3z ZrnAfWq87MknmA9nbavC8ikodV5RSLZUEpdkXNAyNXeBLz6/bW6dE9j2z+2rN48JUgfzwg3LWKY dqoOEMhJiuP3X3KHKgYZDe36+anpVWpzm63c6e2alYYbtc7tgKlghjurJnAvpEHCu+1sC/pep8y r7oO1xAaGNvEy0HcRyL+UZAbmxX/Tj94o/+lpMYT7u4Bq2oOppbuscAo/dehx4nnLk7umBpjYAi S5LcU7vleNhFp3Y/VflSKCuLtEtFu4il5AExVZ2JGpbqHZE2TqeCEZ77KceNsT6VbanDZwOkTdU aycoty+7wCEcR1A== 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. Reviewed-by: Vincent Fazio 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 Tue Feb 11 12:59:25 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864218 Received: from mail-wm1-f46.google.com (mail-wm1-f46.google.com [209.85.128.46]) (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 21BD721C9F3 for ; Tue, 11 Feb 2025 12:59:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278784; cv=none; b=auDCVq84Ai6wT76UbdVO4EsyyGKVGYzunN/KtN0NyzpWtf650ZHLaYAQDJkfohpTonayn+0bto+GXl2v3eJDccJLjUeRXEMAvKycWl4PrNTOQIovxvB51MkBrgU00lF+hWNnlB2WO39g3b9s1AYT3y1vhTS3ecCSddyRqEf6ORs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278784; 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=TYWk4w6gNXGCBegKjG9Z9Obsk1zHHPWckGP5AhvA9miUrPPRmKwNV9+UVEzl3CyvWh5ndsTskRwS805OpC9rs7z0VV7qoUQ7qtB1gtX5pmYQ90EXdSl6KniyHBhz5Yr8Le4mnQhKpG99KiAeNmrpGeLetyIWeT7fSbXPSLBlcKg= 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=pbA+nxeQ; arc=none smtp.client-ip=209.85.128.46 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="pbA+nxeQ" Received: by mail-wm1-f46.google.com with SMTP id 5b1f17b1804b1-4395561ab71so4909655e9.2 for ; Tue, 11 Feb 2025 04:59:42 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278781; x=1739883581; 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=pbA+nxeQeyz4sMGkr0JMF2mS2AWCxWwUSAicGbjkcM9VgR0Qa8JpE4DQ1LzDGPJWEo vYjBg7NgKxGemq2NrrJWGwPSH5E9adX1su0wg43ciiRpBYc+JmJKpjyQbzxBzjMLbiQA U6ll9oqGUMRbtjYnWj81/vhvYaYKNNj+iXRqMnqHf5gWZiGkZNv+buuRCOE1/0WK4+mS 6wDKlEA/S6KVk4iLvg4KZytt3Tl0zZGnS1c8N9UNwh+fhp1wpx3HhfsmqMjfhS4o2UYs TS3DJl2tzRicYYY8CGHf2ycvXtho8IfSFl5v8F2zKeE0MhRClDuyYloq5XLoYWAgs2ub aZ6g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278781; x=1739883581; 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=jTPB96pq9wK54WlVk6modKFrGv5V84XGokncn9EJ6Tj+SeVYVYYjCmUaeUCcbuXmmy X0T5IincGLMGUwT3BJHqHBDfwvFazVDdfB++2m7pVh025HP5US25VVUh5woLaV1UONw2 C14eFdNMtbomFIWoNcypFuX8a7H+6Wd1+haR5dmY9E1BJZ27/W828U4p2i1RgTHPQ/TZ KhgVeRTxp6QCvBSUqF/s+7PFMICb14/jubRjH774Ohv3EtYPg5Z3t3Y7JfWfd3Rwq8o3 2NNrAcImbZww58ZeaTz27D5jhD9JEcdvzIYGW12qhyQJO1fniIXMyD+TjrLHnkHNY9Ff 5esQ== X-Forwarded-Encrypted: i=1; AJvYcCUownHzxpu0nZWP2Syu2me9rzJOFH8bO4jDiLVOLYOH3fg8mAXzrN6vMw5eF7Pp2NVQSVcwdoxYML9X@vger.kernel.org X-Gm-Message-State: AOJu0YyKTM2dvZkTuaadtM3BN2fxXdS41dDuAG0HVa4gNgg7g2wwuGbn dN3pgsju1Q9ZGpf4gAArF+Ve6x9SPK8rGWEkIoeQBZKx8GX2PBogFAaLTovOPMo= X-Gm-Gg: ASbGncuSsAaEZ8M+WB/0rite8dfRBlM5dkuQimMJdLCBUhFUsKN6vK/7o1lTx+MZCXM tQRlONdnUu7iHsJaZkd0vvRlgymY2KmlndvFh030qqzmin24WhZQ/jujNfpY17eWPlHappoGyvC 2+GnTQTZbwWBlrxoJHI5xlDn5WEwzMyJYhc/656MPmPchA5fsnjkGIRt8vfgRNXTp5WFWCZGaLX epPr89UFyOckKQGGwnE1v+AFblShPge8BMB15Zp0BXf+aZG2AdJJdCfZhvWCMY8TvwEYrO5umqT duZCBSc= X-Google-Smtp-Source: AGHT+IH/QqzP9Fm57nRToI5S4Xs7Fzxt4LrLCGSWsyZt/UganCDt1UrDuC4IjVlIOzrgiiUABagnDg== X-Received: by 2002:a05:600c:1f09:b0:439:4d37:7f4d with SMTP id 5b1f17b1804b1-4394d3781f2mr26389495e9.27.1739278781231; Tue, 11 Feb 2025 04:59:41 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:40 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:25 +0100 Subject: [PATCH libgpiod v4 04/17] 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: <20250211-improve-docs-v4-4-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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/ZANAwAKARGnLqAUcddyAcsmYgBnq0m1ZEyXxUBzdrty2YlMBQBRMHQ6Rw+eRN6gg 3EOtwDB2lqJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtQAKCRARpy6gFHHX ctfrD/9qt7oKWLp7IkQFBD+KrgWJpAT+fSPY0IZ65u48y3C48ynkZ5GYU2LvU+nV2U7y9blMyUI 7EyRboA/dumjZe1AsJ5x14PzQGe6vD6+fXcPjFGOtPRPdlunROqwr3CS803f048BksiwzGNh/9/ FaAH/+YlCSz7GSGTinQbQpvCjDPLMwJ3Cg98mnPJd0Ifym+Gwv9z04Ck8aMIjbSbkXx7bxO6jAm KUVClS+UaFdNknIdHW+rGv8gDjxaDtI1idrc8zfYaul2zl+Bdy3xuHk61lW1272AgYTyfc48SJD 2JzTyLsOfSvIboGmVcmBBJ6dHHW0E0s1OGdwpjBp2Vm3BpFxwhhAXvBoEleAQd9g+UYLjAI9DSf t4bIEy9fHBxyZk6HTqliFzXd89F777VMBk28wFp9xViq8tBqwp7TKWm5InIETFx410YjxbQNt9b UOcREH6zpLxEmA64cDMdp1muGEUnZYpxbTOn9OOKD/2VCf6PJRUH4dI/mLSugMVlGhKLoOqmPwh IyR2D9V6trqV5oecI5u0vhnP3z8reYvhctwR3c89xYQ9wNyqxPUpwnSHIl9kwqPvA+M/lfwL+Xx Ix3QUzNFSvWf4kabf4JeZ4YiosvzgUwREd7UP/VX+5IVr8t26Pk+JgHIH0vIjSHcj7uMRTNDb2N DkWzQfXDRu9Zm8g== 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 Tue Feb 11 12:59:26 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864624 Received: from mail-wm1-f41.google.com (mail-wm1-f41.google.com [209.85.128.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 7DE9921E091 for ; Tue, 11 Feb 2025 12:59:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278786; cv=none; b=IWJqCsQxxZWTRVW4aWzkXt4oAdXQ7ByuwxGGeFM8AdaxojXB0nph4+KD1GD0wwZXSP2S4tnh8sgM3FkwfjVaSQSUyhE169rZvMZYjj0Lv22yrFKECCBGbqlLl1K5kkiYxRaS6vb1xGXCeRcDgpXniuVIPFhH5BRGuFIV4LK9ogw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278786; c=relaxed/simple; bh=NhCfl+Kf5EQ2UwVelToJ1q07HgJ+U6QdzNQaf1Pr7sE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=VfB8jbh0rRt7xNb2dKfuCU5TkOwyndQZffByrdL/6tc2CCxcylbuSwzrkieDO+9FWz4Os3grzCOzsB5APZPhQkHkyfCO7exiumDntNBC0YPQ2Ul+GV0x5ODNImG3+ciBQ9RXoKsfjl/yxgpqzFwwBAIOm3HJC+TR9whIQoCzsXc= 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=rbq2qrAE; arc=none smtp.client-ip=209.85.128.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="rbq2qrAE" Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-436ce2ab251so38398185e9.1 for ; Tue, 11 Feb 2025 04:59:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278783; x=1739883583; 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=rbq2qrAEt5FqlW1j3wllu/Xj1fZOkmNLRri72BvnjdBVHgYfcWvoIqmY30Puw2AOpK HtX1Ixkiht+EXW1+iKRXoIxhQuk9WgwvAbP0Kgzt5TEDemStHdvvQGMcpVDLgc1LjSSE ha4hhKcyePi8E7h8ggzkgmj3RTJXuXH8ZybJODKZ5iM5+mXxWVPIGCqhIKb2RfNMXu/C wJn6K6PKmwJGOjXE06HwUWLI6WEeu3/RmwCKJOwSKDMG1pdjvzJr9mnVjQYbMs0QEHdw P9nqdvzx5it25Bb2ot+E1OLWaE8A0PJBPAnuSAHemUhQsKnIwl53KlZouoPjg8BTED4H 2/og== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278783; x=1739883583; 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=eqEJG1DePDUyPnGcCwbnHblMRiNPDr7yMrkfhMsTg6j9oDPuDOWlL9yoBjR0wMbXVJ Fae8z8SiZ1NpIRqs8Kksgc/deMnepvL0Bj3aCY7EjCYbyk8SU+S06r8TCk7an0wovqwL QDxMntIV5lIOECjrrAAMyj/wpmRpLwGSMCBQsNnYxhsJlvsMR7eBSTtVJnNFBwkjakKp BDbwvqvHZAHmuDih7SFbEc++VDvZ9yG514vPmWTGsMyDNwxwvNs+5VeT0pmddCFya+Pl xnScQc4JNio/jnodlIIsaiRFHl9bB5YQeEBa8dw4u36wRfgag98XgQabGOZ+GVwjs2F6 xqOA== X-Forwarded-Encrypted: i=1; AJvYcCVpXpUwYlkYiDMBZtos5vOMRCDEIBAW4OMdjGyCq9dW0HLa/HfMGQmxKIz/iL44+XQ4megxJy9dECN/@vger.kernel.org X-Gm-Message-State: AOJu0YyrcSLppsua6tqo1ATs1ggrLhJ6MO+Yyz4SkyO3wPK65wuaDGDs A5nwuDNWaUU484FAZIiPdYJpm9KdVuZ1+1MmhGB35oG1wO8H22kqs0Wn+tC8OgM= X-Gm-Gg: ASbGncuhl0V2SCau0tCZDs0eYS9Zw+sf8Wm5GX8VttXKmDyvotbto+wceZMn8WXfVps PI2ge5VGsqiFRtrx3mXS48lwjoh3M0tgtwNYmazWSD8q2UCxsEC0tIusviPgJaVbPrd3imq4NSk d940W8UeIRgQPrVFwatyXXjd/9h5W9SUbHD2OyWc/ZRoeQXOM36R1FoYrpZCf2v++RdbRda2O94 D8QmP6CjhGWm0Hy7Mz9ZkSja9CmqKL+Gn37UF8V8+76ljQ7B9tHydVHRBNs/b2wh9G7xAG4YQQr Xa/0oDw= X-Google-Smtp-Source: AGHT+IFEtl4bEn4ibrjkMB9uEAGey2VSG1PhB34+uddjm2//j3Z7yHvWfamZqX3Ti5Pt10NeWBNwyg== X-Received: by 2002:a05:600c:5494:b0:439:5016:3867 with SMTP id 5b1f17b1804b1-43950163b9amr21251785e9.23.1739278782653; Tue, 11 Feb 2025 04:59:42 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:41 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:26 +0100 Subject: [PATCH libgpiod v4 05/17] 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: <20250211-improve-docs-v4-5-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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/ZANAwAKARGnLqAUcddyAcsmYgBnq0m1VmVdAcCKDaFQ9gSfBa4q1kJxwVgUYQcFQ gHXZagzE22JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtQAKCRARpy6gFHHX ciYbD/4tv80vGoLL56QltaOVtnqI0vCVrjswa4OKHjxM7LbrvaSBbdVwfLMak6ajY84znMn+kl1 oiqiI4VNoRIzWqcWgzrBaBspT5xReDAizQ53l7GVIg9lA7x5fJ2d8c9Eze88NgcIIY324ZhkKN2 dJlCHlgzv3zyvOM74lCXRGr3PHsFGIgAQRN3Au1LAVBeA9Mc806Wj1MQeNoRlxmtsP/yImFVnYq yrEB+o8dECGJ0J3j5TqTVoKnB69ZD2ltVN9UMA5uYZ1AdcUMn46/Crn2icZ4cHLLsW3/sKLSOIX hyn07FCtlKcTZIklrO8JDZcuw9cEO8Ocv8H+41B3Zcgk47eNUf9yF1Mt0laByhdiwADeTk9nDyU /p6Z/dzswfiyQD7g87RDTXbaOY4DwQviwYSFovDVhZdc4DVnryxAkYRbqM6DEXi3fvCnKiZyUe9 4EqLv8nELsXi46Tonq7S+TBFxPPVyBNHgjn5ZmgtZN2ovM9ABI/TezsBCEymVVRXzKBY1Rj0QHX QDX8hZCN+JZp48wOepMpfd3Srm4cL8pD8rZ96biEz66x85f+bgYuoJCfQ6vpdXE+aL41QqpAHtZ 2acjpXqO/U9lcy+jRIh8tE1O/s0nvYBiqQ0eFPx/bvMUxh60lQT0R/l6hFrot1LmueS8ORAVjzO V93i2fgfDU31mZw== 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 Tue Feb 11 12:59:27 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864217 Received: from mail-wm1-f41.google.com (mail-wm1-f41.google.com [209.85.128.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 3819A21C160 for ; Tue, 11 Feb 2025 12:59:45 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278786; cv=none; b=Vk7c977/nxsmRE0PsERe4rra3b914jjW2iKnhlOVfoE5Hy+U/uGfRFMPY8KiiLLRhHneXLfWz5QJcMD1HQ6tnDcFgOdkXgc3CEF60iVt8DFESs5h5dsL7Q1W96OIuLyEVQIaldd/5liVPPJytyJ/xH1ANmXNfqEyyaDep2Ka8yI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278786; c=relaxed/simple; bh=vXMfyBfCwmcZlImNds2ZpYink8E1dU2CJwjZR7ffIw0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=O/ZjDQnbQt5bgO1kG8Zho33JCtiteLMVnXeucoNgqBIXLScO3O/Ce3tqlNXbT2yU3XMZVinExUkg02OSDPGbYVSawUX3e2fNDotA//PoqgG7seRwrsE2yM+6ttvRa2AeMv9EeGBxTwJ+Zig0nw3nLyBRVznFvwJNflMAR8L7KNo= 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=QhHTKaa/; arc=none smtp.client-ip=209.85.128.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="QhHTKaa/" Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-439554db49dso4994115e9.1 for ; Tue, 11 Feb 2025 04:59:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278783; x=1739883583; 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=J8qQEfIoZcd5BDP5Ke0I95QrBh0088wo5gqTeCrW8Rw=; b=QhHTKaa/KG7pyuxBEtBe82b1MoBJG2JjhQzPWORJ95JbnkBNJa3WK/4/kmrqz/obPw fdL64upSrzMVPHQnBhnVylv7kvKEp60F5wnYuPuLxL36K7XGX8Rr0awgzhCx0X8ZwTIg 554U9WohEfBwGwMe4HF8SXcWLFXCEnwlY+l/hxKEwUMn1IwTKGLb2Fdncycu/kwFG80R JnfxrydO4GfGqrzc/ni3wUZBWVJTIZAMWuktfsDmBEH5Kn1FVmkOuIu7zruasOj5GAI7 Qi/REdGBg55L3vu1lJuIEHvjfDDjLKd3JAj3EvEMg78nzgvce4I4yDhUWWNM/MrHgOb4 eHHw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278783; x=1739883583; 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=J8qQEfIoZcd5BDP5Ke0I95QrBh0088wo5gqTeCrW8Rw=; b=TpdwCESN1f9HQZBCq/eWaIFFx9QlX7+m6pp10eW+N1BC7tjRJvHTuPNbcXyJCy977p ZhdxxpZDN53nDtet4oSClj4f/Ok8Xwxn+eO6WImYofSe6rrU+i5gwmOa4l0tTLqaWM9o UA4J90IttWomABklQJnunQJuRPvmlyMsCWQ4LUc9RM143YxoTFhj+sXIw7O8+OGfXPDz tGTTwHf80HipQ8gkjTayvt1OIzv2iLE2ha1gVJUZ3SOSQN98ZUw3vZfYvJAygZFkqxxt uLGkgTXpt4tbtWjVMmtsWRC3IkemDQErx1jkA2toBHuY5ckVzYC7lR6XqtUMF0+0CoOX gSxA== X-Forwarded-Encrypted: i=1; AJvYcCUWZny+WBm0h7ceALfw9QJUa4ZnjacsGUwIpDEpmhsV6X0tyniapSOTyLdVCCR5JbBg7fw9AR9J2WMa@vger.kernel.org X-Gm-Message-State: AOJu0YyPkWMFMEx3aROwB8t0YJ6BEkvz01jJPf+tMjywJzJblMizW7iF Hdf+NVuKTBEhdYwekn9gCEFf0fzRmdK7l21LIjQ82AzaUxBxFNZKw0xaRtWotdA= X-Gm-Gg: ASbGncuBQObp8GohRUiash9jrgqNA/09F1T1DSE1BA6oOjFNj5kj3OD8FrJFv03qqLe IkndR8+SlBrhmPMLF38CDKcSdfHeEFslZX/zOJpV7UaRHBrTL1+xDmgS+7VZBOvDlBZ8kGs9HOA VYf0Hrq9b1t3EX6Vg7HbQT5W7V/pSqmfTY8amvQV3h6DfpkYeA5KXDAU3yrQC2d6s4DRHwsOKRp vOidkk4s2tGtqcywELWUZa5uXYyMwXIZ/T+CT2wL2RYx/ViEU5V4YMDL1kxnEBeed7SxQZa4Mqv Yvb5xuA= X-Google-Smtp-Source: AGHT+IHtsJiD9q1DTOGuUYTybUn61NdajyZA6ML2JQ1VzrVJ3A2Wd4BSNw/Pkbe/tbz/QZVrb+JAaQ== X-Received: by 2002:a5d:588d:0:b0:38d:da11:df19 with SMTP id ffacd0b85a97d-38dda11dff7mr8857122f8f.41.1739278783598; Tue, 11 Feb 2025 04:59:43 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:43 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:27 +0100 Subject: [PATCH libgpiod v4 06/17] bindings: gpiod: reword the docstring for LineRequest.__init__() Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-6-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=1065; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=Y3gP+fQVa5ArhZWS64HI2dWPlLIXS38f6AQEio17tIg=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m1gE4DUKmjXrphsOh7IPgvrel9r+3Gft32a bUL27phs+mJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtQAKCRARpy6gFHHX clI9D/wKkqVjcti+7zK7hCf5DJW2dfqcREwH0HgU9BqF8sMXMbagdSTsz4A30GAe0JD5YchA3eD VqQO0A/YaLZenMGh4t36rTMJch+K2bfQPoGT3dPATEUyHLJTxpyPjZHhd696/pxpZPuOqw68Sgz YN/RutLFIKh9wfcgux+NbIuj7xNFYUfvZh3RhPYybEV8YHnpw9ryP0yTOPMP/8b5P/TQOAYX9X+ wXPILXsIaS0PGdxGbfcoXmRhG4A05+FuRuz6GgMmfQ8DuKgXCf8J02BTIEzli53qNCR/cTuGh/7 usYOHF6oVX9VZG2mKHWHpFtWPJxzBNapySi8m2JF2uRIGvsVuRwVjd66T/fE0S+IqEiuaksJKII D5J50LJu816VBLyAWXHyqUr4/c6IigIz28NUsmoUxSQSlxQTTVgCnJKQT2wLUMLbr9S+xOjphLi E+Nl6DhACYWuny0SZupdCUVyzyV67abhw9lK25TFZ+Rf6x7B1RiLOe+5xkuweF+fZBochM1CNAM xVOHtf5KkBI3ANYTH4B+2SEfBiy+eggKdjUUJaRpB5RS2qeynjX+N+DgOM/s5ejTd5PRBiE7uXJ XpynJHB28pvHExGCEKlU+vGijhw4KSAjqfc03ClVAZEsi9YO6YXl8pogNnYkTq90/rMudV5s80V epByD5VGJocKTCw== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Change the docstring for LineRequest.__init__() so that when it appears in sphinx docs as part of the class description, it won't sound as if the class was not to be used at all. Signed-off-by: Bartosz Golaszewski --- bindings/python/gpiod/line_request.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/bindings/python/gpiod/line_request.py b/bindings/python/gpiod/line_request.py index ef53e16..0220ba3 100644 --- a/bindings/python/gpiod/line_request.py +++ b/bindings/python/gpiod/line_request.py @@ -29,10 +29,8 @@ class LineRequest: def __init__(self, req: _ext.Request): """ - DON'T USE - - LineRequest objects can only be instantiated by a Chip parent. This is - not part of stable API. + Note: LineRequest objects can only be instantiated by a Chip parent. + LineRequest.__init__() is not part of stable API. """ self._req: Union[_ext.Request, None] = req self._chip_name: str From patchwork Tue Feb 11 12:59:28 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864623 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (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 268DE214A92 for ; Tue, 11 Feb 2025 12:59:45 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278788; cv=none; b=RGkBpsMGuB2Q50oO8/xntpscXU65aQ2c5LI381JFtnp9yP+HfBWMsymKEJj28qcKB6o3RCHBonqtYowio0fVH6pBj7fVGJvkpuSRidHi4KdBDML6zHYeiYluRfhKD7uyU/YhegPucLJDjVoY5BxrHZ0NdmNGALhxUoEd8ntrFSw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278788; c=relaxed/simple; bh=CAkwPFpseBA3z7f71zA6/63ooE7+6yUcVDOhZIH/1P4=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=P9E0wy4QX0OQrpE3FL3LPYHVMe6GdLFQzrZPoQimTbt6QjcACQfNBF50vfoRu/r14pj0xKkP/3VoWjTgdC8SZdhMO1DOOczcrXL13sJsVC148IvcALQVHdPmbMclnA3IjxuYkU/Xu9zPl4tXNpHyuicsDJ+lHs6tYIgnrZWVG8k= 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=b4R9aUH4; arc=none smtp.client-ip=209.85.128.51 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="b4R9aUH4" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-439307d83f0so19736445e9.3 for ; Tue, 11 Feb 2025 04:59:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278784; x=1739883584; 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=7R9YlqSLEOyBIptzx/BK0WNp0zHju9zqil6azG9zE4I=; b=b4R9aUH4K9OofT1CxLu2XldpNOMON9E1CXyXT28dtTI9hkR7w2w2LlF6qrTNNe6bij GAYfMIPVqWCNTC8FKWf86nGe2ezgzGQkWkTpfzHFz2Nt0FFdL3UJ+BAjF+VEGnbZCBBo Yx32r6M6L3wxPAaY9zAHm3aClkZmg/pSkJzd4ibc1UGBMNOjqXZ6txDxh8Baqs3tMnaF rT5PdOGcSf/qrJKMegXUc4rGMcxcDREfcemR33GJCaImdZ3JbPRO217w7LqGmbV4nEJn mm55feSRkDezH9PsLe7rFNyoj+DwBcGNWs19jbrhvOYHmbwzW0McuXHd5y8R6h0b2kMd 54EQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278784; x=1739883584; 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=7R9YlqSLEOyBIptzx/BK0WNp0zHju9zqil6azG9zE4I=; b=SPjCaHt3VnR97E43dFjTzt68p1FvvlIhRiw96F5uBdYAvSQpWEmWP0AuwlsptG4iPC iz0v53XO5XLPAfZpoK+bk0GdRv5h3Cj8KG548QV2WCfr9vMRautr9QhqihytaSnS4t+v /4AUHo2Mumf4LA9sOU3Lh2ngkMzWM/ujX4gFLbF+hDa73FAKWMlcOzJ10zXepFGiwfMr uX08Fmbj8vPFl9ufTszc5TOmP410es77Xj7otzZvxlAFL1C47cYCnlFUehyTyxd2yiHa /VclDxozoct+IBH0VFBh8utrkIFFma0jR5WaBbPGXROToCFfV/If7CN54kbgvUXYKWQx MApA== X-Forwarded-Encrypted: i=1; AJvYcCVYGJ79n3ITR74bzVI2/lV/asiUBeKS2ymOi25Y8t3hMXyEpYA8ONcRXRlHhQR1ur95Mh4FFFiILQEc@vger.kernel.org X-Gm-Message-State: AOJu0YwETRhKq/fbtRKIHbouMrNrO9XzuoPN8kHI6frruL6OjtJuhk6W Bh7ytAXKzq0G04T8yWK4V0Lu5lvX8nQEHPO7cDh/daVKWaCaUeY2LV82SRn5T+lcga3UCgrz8QK XTvw= X-Gm-Gg: ASbGncs/MAd5Hbby23DdJUi83qOvArPwoNciq47fUTio6Ax86RTOd11Udu65067VqtX WdW/h2PjIWuvqIY0+GKqCXJERZo8lxMKQjyN3z4+nCfzKj+cmx7ogBUOl4maSr5lbXi9mdO5WXZ Cob0Row6Z+ebQ1bHJ3MiTL6lqklz9HP1OMtnjJeb8DNLulBz92ZVmksGzoFVtm45piJlT/vxLoB wr71c5q1u7kBsTCTocoyfG5PwNzUVDizWHJuAnQdeWaWadgFIiEubCJ6n4V6CEknOz8DOHNdsz2 U4sX0z4= X-Google-Smtp-Source: AGHT+IFVq3VOfQAAUYEaU/wwYfN42bCdWCdjxZM8U6o/wfeIy5nmADYWgrsuVEWzgiwb6oyf0e9HwA== X-Received: by 2002:a05:600c:1e12:b0:439:3ba0:d578 with SMTP id 5b1f17b1804b1-4393ba0d71dmr115791555e9.11.1739278784509; Tue, 11 Feb 2025 04:59:44 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:44 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:28 +0100 Subject: [PATCH libgpiod v4 07/17] bindings: glib: add the configuration file for gi-docgen Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-7-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=2092; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=K/5KnBgwiq3Wbij50B7/aTbCG36deEQw4ZueYnmYsmA=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m2/ruAUhwPsdyjbvJ0Bp+2rt01u2yFAUptM 5rgb3mcE/6JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtgAKCRARpy6gFHHX coPTD/wNwj4LkUgD/3kbgdPHWPElkgfhrbwXJxPKvRm+f+u2rbO+4iZELroiaXpJpxAY5jcG6Ve svE+q57reJmSBDTaJlvyJV9dvt0nEUCEZ8IL1MR2MFy9dwhE8u49eTYEF6K5AOqPHuNhNil5wyf Uhlo8LehOshA0L1YVd5PBJ0V0TCGHu/UI4JN5mtnr+kaYBaxiLi5ETWNZunYE8ynzQ0OUgXjdJx hpgdEu15DWeRoMi8ZKR6DbzQGC0T/KOiYJMuaJCSyNUYjgGnYX3gvCd596AMkexNsyQ8JPxthVv U9J2vfremWU95veVGHlWZ9sR1woKzNerDCWXYKXDix9M9d096LJTmtteTDouGbiNNCrvQxL96fO DR/u9SrPCFcd8Dzl5uXEApVs68TC1j131vLt9VaCSzkTmUiF5nVxteBLEn8dPIgQqoFfEQXkYnk P7vmz+ZwnQ61VoATb/U+IjxP6zJ9jWTdORrQ8TZeH0fmGtyfHj8e/65S0/j3uvNdxinYiUGekPp jlISnVABAcH1KL5z5lSptJ4aCMNAIQ7U7a3WinAoV+/1vM2bbRTwcVs/tnA0DWPcuO+AWO/5/uo AGG4uo/zA8ITW64hLzURmdGVXp04LQ+lqPHQGo1brXngqjH02l4Ob66hZQ0go5+8IzEMX/8Bdi+ Y+J5j6aDVxO94Ug== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Without the gi-docgen configuration file, the GObject docs don't contain information such as library version, author, license, etc. Add a simple .toml to add missing bits and update the command in Makefile. Signed-off-by: Bartosz Golaszewski --- bindings/glib/.gitignore | 1 + bindings/glib/Makefile.am | 6 ++++-- bindings/glib/gi-docgen.toml.in | 9 +++++++++ configure.ac | 1 + 4 files changed, 15 insertions(+), 2 deletions(-) diff --git a/bindings/glib/.gitignore b/bindings/glib/.gitignore index aa399b8..5d6fe20 100644 --- a/bindings/glib/.gitignore +++ b/bindings/glib/.gitignore @@ -4,3 +4,4 @@ *.gir *.typelib Gpiodglib-1.0 +gi-docgen.toml diff --git a/bindings/glib/Makefile.am b/bindings/glib/Makefile.am index 6ecef94..f0241e8 100644 --- a/bindings/glib/Makefile.am +++ b/bindings/glib/Makefile.am @@ -124,8 +124,10 @@ endif if HAS_GI_DOCGEN -doc: Gpiodglib-1.0.gir - $(AM_V_GEN)gi-docgen generate Gpiodglib-1.0.gir +doc: Gpiodglib-1.0.gir gi-docgen.toml + $(AM_V_GEN)gi-docgen generate --config gi-docgen.toml Gpiodglib-1.0.gir .PHONY: doc +EXTRA_DIST += gi-docgen.toml + endif diff --git a/bindings/glib/gi-docgen.toml.in b/bindings/glib/gi-docgen.toml.in new file mode 100644 index 0000000..5550a31 --- /dev/null +++ b/bindings/glib/gi-docgen.toml.in @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +[library] +description = "GObject bindings to libgpiod" +version = "@PACKAGE_VERSION@" +authors = "Bartosz Golaszewski" +license = "LGPL-2.1-or-later" +website_url = "@PACKAGE_URL@" diff --git a/configure.ac b/configure.ac index 34de870..5a7e01c 100644 --- a/configure.ac +++ b/configure.ac @@ -307,6 +307,7 @@ then fi fi AM_CONDITIONAL([HAS_GI_DOCGEN], [test "x$has_gi_docgen" = xtrue]) +AM_COND_IF([HAS_GI_DOCGEN], [AC_CONFIG_FILES([bindings/glib/gi-docgen.toml])]) # GObject-introspection found_introspection=no From patchwork Tue Feb 11 12:59:29 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864216 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (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 B2E0D215799 for ; Tue, 11 Feb 2025 12:59:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278789; cv=none; b=lEpqaubLqjlObBTH764OgOclvYrTvExW2/MJuUZjgFZcPD3h6bv5iIKcOKHVG4YbiR9FLcTTiYT4axXj+k5qKDYQbqJ2w6fjbGu1bxIT3SqEBYg09AfagcPH5DL4YuzJSEaJ/WccCp/1uoQbiq8w9ibBO/eYkHLfwecH4RIA7GE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278789; c=relaxed/simple; bh=WB7fTYVpBhCtObrR7qdfc3t8+TkfB83AoOsP88xUS08=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=bujbAW8PF/UDH3OP0r5gafyg+9Qm5N1NkYzt0oZWFzHnnM+RhOT3t0J6xcu3H7KqFqwRReVCEvnP05JrOaUmw1CCs6BCsBP48mi0kPyvCGq0V2RegcaTOyM2hyIuZ8ApHx+BqLeasetIyza/93OjcCXqmdpBl3gGcQ5yL+rL7CA= 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=MbB/k0Rh; arc=none smtp.client-ip=209.85.128.51 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="MbB/k0Rh" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-439473da55aso12867675e9.2 for ; Tue, 11 Feb 2025 04:59:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278786; x=1739883586; 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=ANA/S/Ju/e3qEgT9tA2+KKtVfktLoZrMTODVCC9QX4I=; b=MbB/k0RhD/OFsoE17qG88CzyfEs+MD1yWDLR+GmGk1gk4BkYsy5dFkO3/bthpLTLWE vIsXJyXfDJvfcLhaZlNZDl32W3DbPH1nzcsXvqyiQBCihj9a2n6JEs+u6qPrOl74RzJA JEcpx0j06kKUABm5y5os37CXmh9EgbqFeXEpIwIyHSNKX5hYPM+mdMEpS6QS3n5bvAeO qQDFrK2F22EPMca7PXkLcsa9JJsvauueL19eIPvSruZXPbPXePflQlIJPnybDW0b+KcJ OZ/u1ocRYvDD65EGQdoK8L2Ao+W/osnkHA0KFA2S2oZEfsylDqm3ZtDlboiwVkS924vB lSBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278786; x=1739883586; 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=ANA/S/Ju/e3qEgT9tA2+KKtVfktLoZrMTODVCC9QX4I=; b=Aa5Ein7qjy3x4HePWVUUsm0cvgcKkVG4hTcvYNIeN6PobDAloT5luQ7xJ79JfTP5fO 1xmJv8E7gR3EbJPb7XmNtqprP3ngRw5Y49R/jgNSl1zffaFQH6tW6nDe6dXVMOWTMIBT GFoFMjX1K+pGJLXyig1WGcQuofWgDPG9QFlYffosUnun0ZhjJL0pRMez+5QAVywyKyQb qm1ND1nmIdGvHNTwKGi3EW/5yjc8Fja9RsJHSSrEym8mPAMDzr3BbH+WECXTNqA5MFHr 6jzQjNSLHbuwxI1AoSXNnot12iY5nr5qRmn4kFwUU9TiSrkPlKMPb7m6SK302fPB5gD2 clmg== X-Forwarded-Encrypted: i=1; AJvYcCUxhupWPAGA4HL/ir8BpvV7dIZyggQX5gZDXxxfPHFvMx0+PPkk5Na3au9ZDjSkg/KbT9M1h4yxo3c1@vger.kernel.org X-Gm-Message-State: AOJu0YxIjyZxVLp6sfbAiKuZEOfSinOv6N0Uii1IZNaNZyhQVs+d1L76 NiLOyGaZg/SftO+he8jSyxT4d3GWoQMEjSd8PhWmz4K0y1MdxTOA6RKMUqVvXrs= X-Gm-Gg: ASbGncsLe6JHOCqJjmJLtFLiNRbmWOBHCz0M8olmqeHa1oMJMoQ+LZBoWET8O2oh7N+ PK+0EB1/TAZaWQxOKRdWsSUXrwdmtk7Gji6dGzUE8GhRBrgT519MZy0a3Tm4NjCkmxBzCzH5mtG a1qqrXr5cJbTsHHRrsoSTwZGBlhwcxh1SVpU0um4EOSVDgykgzW+0BznOidG0xnb6mS0DGTek0s PmPuaGNK8lGGM7eIsUh3Mzu1eRllUW0Au2bO8x27VK8TIULRXV7YzXhcUEJhBhAncfdIwfbgTqx /oEMlFw= X-Google-Smtp-Source: AGHT+IGTEw6f/jMT7Y9rSI+dIIhHfxJew2oPRC6AbWnpy6GzrDxXT8Q3mqnhaIbx4zWaQNwhO7OM1A== X-Received: by 2002:a05:600c:4f8e:b0:434:a734:d268 with SMTP id 5b1f17b1804b1-43924990be0mr157670735e9.14.1739278785905; Tue, 11 Feb 2025 04:59:45 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:44 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:29 +0100 Subject: [PATCH libgpiod v4 08/17] dbus: daemon: add a more detailed description to help text Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-8-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=1640; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=QQqP3yj9obCCv4oCtUXElC79L1Ly6v7DP5+O2kzPRQ0=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m2X86mQY7Zd8qlcZ7u/R11otymooEXKcaMH gx48EY2oDKJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtgAKCRARpy6gFHHX cnOGEADLFo4NrwaJWo9cLVw8IfrduzpEoVRTqOFcgAqS6q2jwsqQuoZmm+caeGLiQC3VM6FrhC/ 7HvymMpQRLKYICY/8pWEU4aoPTvOpRqZ155ghtpZQK1w7szSsi14QozRnwtF4ycs8q4bIw/zHIN pNE0S4d8E+MbDQl19ojMt+oBTJOInPWBicQouYIX2d5GFUT8QtsxsKCSWZjB7UbTa7H30Z4xbgi Dif9/rYr0BHMHEEDKw7b7S2ca4w30ZRh7PaeZHrdHuuNAQaWU41AtXJeCb9Z26AJaLpVJMclMwQ YjkYowbRKHk8nao1pxh9vYyfpVTxbA3mUsrQXktbLpFpq5bv9OWprE5G5EEvFJRhTz2FGmqCHya VFY0MrqcOoktKC0SzbLhjxN9cPpIi6dWFHsuYjOp3eUfBCjoSA8gv6eEOURiXtvib/Ow+cUcdhg RZM5zk5siq8DWzi7zrnyqg80ixA5Tib0nRrweBWaHjAYaNSLGQrG65wcIgzN2iqx4ZT9VPbgk95 qvKCi8bpUqGwa1GLoldWNEy/D2Wc62XGAcCB6Zb/YSaIOxxCmFHB1od97m708u5aY5xUdp7vtXT m1P8WNJjbTg7B2YpthSbeMAyGhRdIduA7HliJym8f9DvFZxehs+IKAaJltisnV8XNLqSBXh6+Hi 6sNuxnrxxxx7IXQ== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski In preparation for adding man pages for the daemon and the command-line client, add a detailed description of what gpio-manager is and does to the output presented to user when they pass --help as argument. Signed-off-by: Bartosz Golaszewski --- dbus/manager/gpio-manager.c | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/dbus/manager/gpio-manager.c b/dbus/manager/gpio-manager.c index d34c7ea..03ca7ab 100644 --- a/dbus/manager/gpio-manager.c +++ b/dbus/manager/gpio-manager.c @@ -85,6 +85,14 @@ static void print_version_and_exit(void) static void parse_opts(int argc, char **argv) { + static const char *const description = +"The gpio-manager is the reference implementation of the GPIO D-Bus API\n" +"built on top of libgpiod. It serves as the central authority managing GPIO\n" +"chips and lines, exposing their functionalities to other applications\n" +"through the D-Bus interface. It supports operations such as requesting,\n" +"releasing, and setting line values, as well as monitoring events like rising\n" +"or falling edges and line property changes."; + gboolean ret, opt_debug = FALSE, opt_version = FALSE; g_autoptr(GOptionContext) ctx = NULL; g_auto(GStrv) remaining = NULL; @@ -118,6 +126,7 @@ static void parse_opts(int argc, char **argv) ctx = g_option_context_new(NULL); g_option_context_set_summary(ctx, "D-Bus daemon managing GPIOs."); + g_option_context_set_description(ctx, description); g_option_context_add_main_entries(ctx, opts, NULL); ret = g_option_context_parse(ctx, &argc, &argv, &err); From patchwork Tue Feb 11 12:59:30 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864622 Received: from mail-wm1-f54.google.com (mail-wm1-f54.google.com [209.85.128.54]) (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 8B42721C160 for ; Tue, 11 Feb 2025 12:59:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.54 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278790; cv=none; b=temuNU0VJfu0/Y9ycZM1Vw7FYHd1KqfQ6WY4xJGyHQjW8+UiJj5aix2xdrxF1FncehETc0YGAchsRGqr/cO5bF28ku0677VIn2zXigbuRoWPicNx46O3H0q1j+zWF3uAJeVDRwIG5tEvt7MUZE60dzek/I8u4/qvCgrItTHyb/0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278790; c=relaxed/simple; bh=YlPGh4pmtCOE7xtDJOAWZkfON+rqq1FB9jCLbTzmsKs=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=pg6YIjlEAVz97xhy2avawpZ5RA4pHDPx8N1jy0Iywoe0Lo7nIMQeoyIODChbsNdMdz8QvPffyQtsYZLmWRchepoKmRY8oRsuAtEbkGkeP4+W+S4FZcrH8JIBltlpE3ufa/qo8/hk5DNL1UdQz8eRSwOfi6PdQOrCfxWwOKCRogw= 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=OyKZzO6v; arc=none smtp.client-ip=209.85.128.54 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="OyKZzO6v" Received: by mail-wm1-f54.google.com with SMTP id 5b1f17b1804b1-43932b9b09aso32724385e9.3 for ; Tue, 11 Feb 2025 04:59:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278787; x=1739883587; 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=Yd1C+vo1v2WCKXm6pVEB5dHLGqFhuSBFksocLigcO0c=; b=OyKZzO6vfexvi1okZNGMdUL+5VTl9swBzquMQ4vjA+Occ4ElzF3C+9lCDVV3BlD+YP NK9esWVcIf2uFdq3br+Us7K4kZVmFU1vjwamYVMi3v1KCh/Y2jBCj0ArIAcezMjw/X/9 ia2uMAONk0DbIK26OD9te4o43+iZG2UI9Q8Hadmw0WOASgtY1vL2XPt/sL0ZX6LhKzaQ yKR7+QbAywyyr5wJgd8waZQ66LnrzkXP4UT0mr9VKaqFQRQ4leVV4V9t1V+Q3NaBjEgd A80EWKgsL7Q0InFBqE9lyqPpDOfg0lDAXdbX2nYkvh2A0Dv0xSs3QRnxWZsxSDLSNeF/ GWjA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278787; x=1739883587; 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=Yd1C+vo1v2WCKXm6pVEB5dHLGqFhuSBFksocLigcO0c=; b=qZVZlzA5h/ffrH4nTWLPvmBhsE1s5S1h5g2+aLKfkpG2pGCHxmo+3Tk9IQbcUiPHae HLTjOOECUSi7Xs5SxTeemmwW7aPMVOqQxBPHyFbaxSDfifXlYp0gO5yFOIR3x5DdZtt4 hvzCG/YaxDp7C7u08IaWTQnHs03OkgMzPXrfbGJVZGTFpAHujo/FVzcv2qHRRKsh+8lt T8l6VIwyFlue+Q8+S5gg8blNEQST40hKx1UorcELYGXiDdq3hds5XmiY2QP2Sll+ZFsD dCACEzhaKu/iXwa2p5iQtRq3l+xkBlmA6h375ZzUOV8InkKis0TC9m6kyHhe7ktzPBZO bSkA== X-Forwarded-Encrypted: i=1; AJvYcCUKn+4SOS80cLEbCq+Ihriu9t6vyY0AR4mWY/7+EODbDj1yxr0hLysuWumw5QWBXQ94IYsJwbEE/6Vy@vger.kernel.org X-Gm-Message-State: AOJu0YxLrHEVlYh49prm5VigdhpCJR28OzJFCegFFKYroDNrXIx8t7En oExgY94beBfZTawy4kMn1UxsNAcFY4P6aRJ4NH00qGeATWyPSYngrsjQxIOAgZg= X-Gm-Gg: ASbGnct4evNXtKxQ2PcIA1+M/LqlEzbSB7Y4ECHixNCnXFuasOargl4Tcu8YZmBRins JqlfUa5hNhi/LukKTTlwk8sBauSLWUIKltvF4puo6lunbaqT/Lqz+VkNm3ydJQ4+2ReUzcHL0jX //vg9l1b3IiYeXYnJpjJQZqd930pa8EoF2LxA0vUPNAZ+oU66vkTgOiBBLxmivX+75Kl3P+q1w1 5QhT3QPNhuqImD37SJIEoicKBRT1m5UxORVci0IG0j15xOGX3ajXeTkRiFK5xWSN+Uf2t4I5wzp o6IpBSY= X-Google-Smtp-Source: AGHT+IFCq9uaaKsPGro40XvGPjovM65iZ2iynRNpotXtF0MSl8eP7kJuq6ebatruUY6sdGUeyOtjzA== X-Received: by 2002:a05:600c:1f0f:b0:439:553c:2a34 with SMTP id 5b1f17b1804b1-439553c2b7dmr20004555e9.4.1739278786815; Tue, 11 Feb 2025 04:59:46 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:46 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:30 +0100 Subject: [PATCH libgpiod v4 09/17] dbus: client: tweak help text Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-9-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=926; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=835K+mlZ6UrS6q/DzaKsErP0FTSHQFLlFsXsvDQEKrk=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m2u5pJngcNkkhWLfm/nH6w9WfwJSSoDj31M DumKkb75uiJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtgAKCRARpy6gFHHX cq1nD/0acsavBDPLspI+hgxC7uQgeJJOu3jwYmjj172TjOx//u3De+so3N2Az7qszrfkaent1mR c/IxVK1WWxfjrfVtWsyBCCjb3aZzODY7nrgqZe1H2q9QYbYv5RnfYKw0mZcszS86t4xBnNm7lpO sdj1C+k/iWR+eEIjqytn7vS6sAVhJcIWvsjogaXJhLXIzG25jAHDMcWX5CfEaaPlV2ozLQuQt/I ZfvkovldsDOjOk6MW69RgQSH/Liw03KFtHT0/KJnOTWrfJht1d+BgXULSRCCrl/kl3XYXoW7jAJ TIW1TZeEz93+NQ0v17Q3M2ARYsMTyHphFX0zUOAOaZAhFePspwkfLRE3W8RHRGW36Wj8Lj9Lbox llpBIoSNM1bLGmKX07L/nbFPkiHN5VahsdGp8yepKkHYjY28jik9jOQ845/vDYkCMO8YNcsDHNh hfAduQwgAjE4TVepKvLqmlVD1Zci8afm+pa3F9g+DzHzx7XKJhPqt9IvkpnaIj5lppsEz12zUyo gXDgVwvrld2FK3JKfxLCtDv4i8XfuGFI+ZRJlRi0iGyMcAY1a4TLItt4CVEoMuJfw+YQkMsMfqa C2QDf+NsntMIujd/4nko5hSK6rypZ2yj5zTS6Ll+89pjvLEPkZOEtBxHsgbUxytcRhSk8cAgR3G eIGSwvmfbIK31HA== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski help2man struggles to generate correct output with current help-text for the sub-commands section. It doesn't break the lines correctly and the resulting .rst generated with pandoc looks just as bad. Tweak the output a bit to generate better man pages with correctly broken lines. Signed-off-by: Bartosz Golaszewski --- dbus/client/gpiocli.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dbus/client/gpiocli.c b/dbus/client/gpiocli.c index e9ab380..26d641b 100644 --- a/dbus/client/gpiocli.c +++ b/dbus/client/gpiocli.c @@ -107,7 +107,7 @@ static gchar *make_description(void) const GPIOCliCmd *cmd; for (cmd = &cli_cmds[0]; cmd->name; cmd++) - g_string_append_printf(descr, " %s - %s\n", + g_string_append_printf(descr, " - %s:\n\t%s\n", cmd->name, cmd->descr); g_string_truncate(descr, descr->len - 1); From patchwork Tue Feb 11 12:59:31 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864215 Received: from mail-wm1-f42.google.com (mail-wm1-f42.google.com [209.85.128.42]) (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 0A98C220697 for ; Tue, 11 Feb 2025 12:59:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.42 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278791; cv=none; b=rFbgeXKwqbSmMjFIO2E1bGlQZb2pge4okqtYnhGFXfb20ejEBlgGXmtRswCF7OdT1rTvu/d/g+Z3YW0aHfrtA7KY2xBtaN8IjRHEYMzBRcqTkpWjm7/ah1+prcfICjVFMloU6nFaNM9CIfPPEFREHgTON/SHoSBTdLCVSvqVXq0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278791; c=relaxed/simple; bh=NOWwpmJBYV5ghwlu+/wbIJh/GmNExKZiNFQCVv+Sxo0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=fpnsypT4i7n5XXZh5c9WUhvnSWtKz5Qa+RBdrv9cuf7nZ0Pqvu7uJV/l9cduuGMI/iY0FOhQQjrucvKu562uqIk2tMnEV5yAUUX8N8D9UvbyBlTpBJiFTqJIpQdQxbkTqTVnL2lKPry+uZrWh3jTjp6cAhWN4uV+pGgqLMfxjOQ= 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=C2cGhanZ; arc=none smtp.client-ip=209.85.128.42 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="C2cGhanZ" Received: by mail-wm1-f42.google.com with SMTP id 5b1f17b1804b1-43934d6b155so18055875e9.1 for ; Tue, 11 Feb 2025 04:59:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278788; x=1739883588; 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=InkFhCCRI2CAF2CvZhuAFHXRNWz5kwo2d8XJvFQW824=; b=C2cGhanZ3qP3tYQ7+rgoaXEvaxCntFwcdahOp72jSb3pNZ7V/lRmkfdcGBDXdymPuc n9jg77AYA+QtstzMdPXxLpUEpU8nXIwKlAE6NXUvl8+PdPde+RWr65TFRGepYQVqLa1e 88OjK+JVb71D+VomxaYncRXaGXPzNyumZfI3jTDUyUnnnswdmS6g3Kl6LDVK5HP5ndrb P4gVT+RU1PQOe+j8FSIAcR9fjeohZgM5n8/OTeIilCVyVhNrsffTu5BwEWi9aCPaYQdy kPE9GRtXo6Pmyc7R6zq8pvU4ZvABYmH+dKVZaxEuvu1wlcnD6VfQvwnmfISfLJynS71B plmw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278788; x=1739883588; 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=InkFhCCRI2CAF2CvZhuAFHXRNWz5kwo2d8XJvFQW824=; b=DXIEPxL0Sl2GVNGNQaYRbaFlcikBOCvZhDJZRXK7BEPM/0c7kR1T3z/9Gcv1aWg4wK aM2I51AGG9IK4zXACATCDunvD9QzjC7arpWss7F4g4+U0u8L8puZ8HT7SoNcxD8DdUav Bpc/YJwL8t7pXtf78fp7v5itsqfL+bDCmvNiG21W+xzZEC/rrkY5Ry59Zip+T8FmmxSA 4KgADkxxtkq5AMa71WsyzOx+s6OIqhY42nqUadMAQ6cppT760KE1IDk0glJdXB+/6O85 SP0mUagnJZkWtq0dlgXHMF8MOio/Edenx6HdH4PF3oPUFjd2wO4jFXtLuDvxEXOSEoes Ds3w== X-Forwarded-Encrypted: i=1; AJvYcCXFr+KxVdtO2WYCdgQ9khEhE39wITQF+3atvX4e0OuJxs0N/y0XT07CElYSrZh/nVq2RosHLT2tBCfQ@vger.kernel.org X-Gm-Message-State: AOJu0YypSPmPfjMj1ZONtHtbxidBpWURnBZIQeAjeBHbb//u7VXHHsm7 C+KX3iCjtsPhlfLumMlFh7YkN2W/I2EhayRfDZ7UeCKpAcXCxUmty4Gs0CDIa+I= X-Gm-Gg: ASbGncucLEqHx0PGd9P8Ufz5jSbQKo+r2BSUH/t3rOk0YDrm1MMxAAwX/Ei67Be752l hLWC+NXDRS4KXutaVm6CYn/5sryGanKQcRHWrUbtd7UznyFh90T4Chjnmnu+6HtOGIHFX0VNoaS hNWc9VeMESBAlgPW8RHYs09Qr39+IJ8KcyOAkhcmkgzqw1ye/FT3U2nEpVUAgPUNzpIA3rt+UK1 sErvIIWf9IEqLG4EMv8Emmvrcimx56yk72RgrT1Gzpzx9X5uz3BBAn5d/Q/d7OpVRylkEuKTRdR oAzrb9E= X-Google-Smtp-Source: AGHT+IGAfLPxb403g1DltYd1G/OhspieSmHLtCQMNLMJXwLnZmPs+Q8SM5s4PrtfHX6wbbCamh9rKA== X-Received: by 2002:a05:600c:4586:b0:434:ffb2:f9cf with SMTP id 5b1f17b1804b1-4394cee55camr27847735e9.14.1739278788191; Tue, 11 Feb 2025 04:59:48 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:47 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:31 +0100 Subject: [PATCH libgpiod v4 10/17] dbus: improve comments in API xml Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-10-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=7033; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=cUeMTm4AJlpUcPLKsb+j9wyt+CiiE0p1BclrHiEIvA8=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m2YV8P9B19QjeNWNpv9ZDJAUnOYImBalfSp APn5UystWqJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtgAKCRARpy6gFHHX cuciD/0XIbABHtt97xk0v/AGmjCPGm/T44S32KN62FLIGTOwLjATojXG2US6BQxH+GrfG+xd+bh Tikh69RT4uQvPCeG0+jGFPsVhhf0n9Ck+6bLHKoeaVV/Vx6LUtLIpk+JedxCJEos7eHf8XSA3ee HL1C29ZvAxGFQl29+08VdJsAtKZVlyixtAEXkWvkovWiV6A2ZaoNOHuTWVxH5zVJ+hkHpsf+BmX 1VOBY2m7BswM1gUs9zJcQgV59Xd7G+zOWSVvtSX8dv9/WNYZpf+K0bUSEPJcnoHUA1Z3MUhK2KI mKASAcnYFfphu09E4NJnbdAXO4jG7wGm8u9PFIEEe/1x89EXLKXlrT3RgQIhjoML0wm6ucQMmDa RG8cyuJgnGpdCkFEGe/eYet/0qCBdIXiCgXrVo7BvEaE9IioOtp1WJ0PssWI3QWIuEMZBO8yPtR qC3JZuHLRsQc1rkTwrZ3SpCKUSyNQ/G5lnIWhuZy4EKZ0gAdpPwnZtMizupKsr8gwa4mH2o1FpI ibpn+LwR5mpZ4N4tBhDHvIZlwdGKr3g7zc2v7cWVsoblBJz9Puq9QhLVz2ohCGN1M7xdNNGEgSW kYdMAtyawlfCBWQJ3SfdFaloPVVxD/Q4fA9dh9NsJMSNc/pxYmSjbR+db9OJCh0xcpXH5NlrHSR 39QksCu8c/xbcUw== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski The current comments don't follow any particular formatting so the resulting .rst generated with gdbus-codegen is all mangled up. Use proper .rst formatting to make docs better. Signed-off-by: Bartosz Golaszewski --- dbus/lib/io.gpiod1.xml | 98 ++++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 46 deletions(-) diff --git a/dbus/lib/io.gpiod1.xml b/dbus/lib/io.gpiod1.xml index ace7d72..411ea6e 100644 --- a/dbus/lib/io.gpiod1.xml +++ b/dbus/lib/io.gpiod1.xml @@ -1,5 +1,5 @@ - + @@ -54,58 +54,60 @@ contains the list of default output values which are only used in output mode. - Available line config options: + **Available line config options:** - "direction" => String representing the line direction. Accepts the - following values: "input", "output". - "edge" => String representing the edge detection setting. Accepts the - following values: "falling", "rising", "both". - "active-low" => Boolean representing the active-low setting. - "drive" => String representing the drive settings. Accepts the - following values: "push-pull", "open-drain", "open-source". - "bias" => String representing the internal bias settings. Accepts the - following values: "disabled", "pull-up", "pull-down", "as-is". - "debounce-period" => Debounce period in microseconds represented as a - signed, 64-bit integer. - "event-clock" => String representing the clock used to timestamp edge - events. Accepts the following values: "monotonic", - "realtime", "hte". + - **"direction"**: String representing the line direction. + Accepts the following values: "input", "output". + - **"edge"**: String representing the edge detection setting. + Accepts the following values: "falling", "rising", "both". + - **"active-low"**: Boolean representing the active-low setting. + - **"drive"**: String representing the drive settings. + Accepts the following values: "push-pull", "open-drain", "open-source". + - **"bias"**: String representing the internal bias settings. + Accepts the following values: "disabled", "pull-up", "pull-down", "as-is". + - **"debounce-period"**: Debounce period in microseconds, represented as a + signed 64-bit integer. + - **"event-clock"**: String representing the clock used to timestamp edge + events. + Accepts the following values: "monotonic", "realtime", "hte". Output values are applied to the lines in the order they appear in the settings mappings. - Example variant that allows to request lines at offsets 1, 5 and 11 in - output, push-pull and active-low modes and specifies the output values - as active (as visualized with g_variant_print()): + **Example variant** that allows requesting lines at offsets 1, 5, and 11 + in output, push-pull, and active-low modes, and specifies the output + values as active (as visualized with `g_variant_print()`): - // Line config tuple - ( - // Array of line settings mappings - [ - // Single mapping tuple - ( - // Offsets to map - [1, 5, 11], - // Line settings dict - { - 'direction': <'output'>, - 'drive': <'push-pull'>, - 'active-low': - } - ) - ], - // Output values - [1, 1, 1] - ) + .. code-block:: none + + // Line config tuple + ( + // Array of line settings mappings + [ + // Single mapping tuple + ( + // Offsets to map + [1, 5, 11], + // Line settings dict + { + 'direction': <'output'>, + 'drive': <'push-pull'>, + 'active-low': + } + ) + ], + // Output values + [1, 1, 1] + ) Request configuration is a hashmap mapping names of the available config options to their values wrapped in a variant. - Available request config options: + **Available request config options:** - "consumer" => Consumer name as a string - "event-buffer-size" => Requested size of the in-kernel edge event - buffer as an unsigned 32-bit integer. + - **"consumer"**: Consumer name as a string. + - **"event-buffer-size"**: Requested size of the in-kernel edge event buffer, + as an unsigned 32-bit integer. The object path to the new request is returned on success. The user should wait for it to appear before trying to use the requested lines in @@ -239,8 +241,7 @@ @@ -287,11 +291,13 @@ From patchwork Tue Feb 11 12:59:32 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864621 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 89DFF2206AC for ; Tue, 11 Feb 2025 12:59:51 +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=1739278793; cv=none; b=CU2ck2zC/hMWuQwcdq2e305Cb14EQACs746ru/QtNqpNodZhrQl8NRH7JzXKp7QYIxgQMnYxdnbF2XyjWqkTC7+inZQ8O6fvCPgbz79Rdh7lEVSOfQpyd5S5Mmkhhwmqer/lSRvVdDiGdYsBbPKBsVsTcTLsZ+LpZ0tgyHWoVXI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278793; c=relaxed/simple; bh=vsC0ALtmeFLUJid3v92trM8BakrNODQ+xcARW6L4VGM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=sbt2ztcOVQC2eAruCDPL+VeRa0t4G/zDMVS8pUGEIGffPHA4ufVETGl7ZE1f29TcqqX/NI4F+5Cfc3riFHhOMjk2bxMTF6mK1+1gduQcG/UkjRBHtpfhlV7j57g4wCxUClXnGY7NSan70iDBEyNwVD2Xb7XxU5UJTuntXFUe6Ss= 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=lXKBoguW; 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="lXKBoguW" Received: by mail-wm1-f50.google.com with SMTP id 5b1f17b1804b1-43956e3863eso1367555e9.2 for ; Tue, 11 Feb 2025 04:59:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278790; x=1739883590; 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=kOiGJQ4r4j0cd7t2jdREclbjjrfQFirN7yKGlUgJciA=; b=lXKBoguWn/EudEz8AZVZOnj9jX/QIIn8UO1z/zELLY3vGt4cficUUeu393k4RR9SQf d3RaMdtF0FihwgtQe84/Xdkqjc0SYBDPjrsAhblNAerCz+8oK2A82S78fjylkAXqMo6C Kyf0a8f0iKb8vyanwcZ54DzLQ0pru6rMMKSR9v5C5dmInXaWsKS4NMTAt+PlvRi9bgnj dDvKZ1Gk1OV095YuteO/utf8j8eiasluuqAaYokQ9zX987WbVi2MxVdyu1ysOBvIuAB4 68vCaa/RDFQvR0Yh9swYjIKz8I4EWZ3kbiA0sjbwr0PlTcr3mPKe/Vh7Vt7yIdDnJJ9e 9vSQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278790; x=1739883590; 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=kOiGJQ4r4j0cd7t2jdREclbjjrfQFirN7yKGlUgJciA=; b=acwYgRWZ6Aw/a2omw/CLTEGVYeTkRASQ/5peap5q39pMy91X2hv9HdcdzKnjs9DWuJ b89SnEq/fjgcpXA7zzTsqxG6B9lmF9U53XsUJU06EMj+ePnt4er55EmGP6tUym1pl60N jeN2gaAjyrpfBcq48FHzBCBgx7JLA6+pXHhGx5IkTVfh1CuTmq+hAgIbMYHl5UIK7QPA fdTZA8HvVF5Uau6i3B/WeeqG3uAle7icV+wQLKdbrmf4LXtfKsnUQGCCEh2EKY2pHUvF Ops060g9EUXQyaBTbUUOGGjByd4ovTJ0ebVjyPC1bDJnAVhwtqYeGJa69F90HiqfGoJv wtlw== X-Forwarded-Encrypted: i=1; AJvYcCUNZcHDPFO+xNgyx9GI6pTDGGf03aqFy84uOAzeS5YqNwWFXuGdESI0cTjikeLiN+Uae+gVtBZTnRd8@vger.kernel.org X-Gm-Message-State: AOJu0Yy8wA1Mh5r6lWXX3hH3IzuF174PGqt3MXTABybFEkHb37YaXJQ0 LsVvflXZ1fITUs6dpZgQdXhCnq3ZxJOL3jtTCi3dBXByhShklp3k1Pw/JqsqELc= X-Gm-Gg: ASbGncvVqJGc5DyxKVisE8iiH/RS2jYdKccz8FYjKLN7C4VGvFf2oWcr58xSv5Ruvhi TXIa8v9C6CAN/QpOmnk5r/fgrx3g6f2uP6RvHQHwvbcaGK45aytUEBnLiEyqdCD7+jdD/+yMVwc V5nsEr3whSPJ1GYRJvRtQRNIZwMaGii1QF7E7wzgYmZPeqrzRKQ2FYrtmCqsD5+jFWPM3I1pn9j OkwbF7CT1/0b6U+HKFJoebMhDiDdZSSVSYSVaE1ajkH3DpVZdau0MEd+TiIGNyNESdU+pyD8kfS M3k0A10= X-Google-Smtp-Source: AGHT+IFpC8+PoiZymDghgk/nocefVKmmAKehitPNo3SWXW2iU9YSChD/4pE+hcz2oi05zLl2Ie1mWw== X-Received: by 2002:a05:600c:1c94:b0:439:5590:6d2f with SMTP id 5b1f17b1804b1-43955906f3cmr16132275e9.12.1739278789635; Tue, 11 Feb 2025 04:59:49 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:48 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:32 +0100 Subject: [PATCH libgpiod v4 11/17] doc: create man entries for gpio-manager and gpiocli Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-11-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=2909; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=ze8CjUpLFt39ID/3fvUYRUTR+iu8gp4jyehOfU7r9ak=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m3cjz3fHi2mWv60kWA4+Ddqqo2aKR93iTDi NzWFkc4FnqJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtwAKCRARpy6gFHHX ckpZD/9KjNG3wbIZTnrTajxqvUxDd5XtI4HsaGgT9Lrl/M7eFC8SkMHHMxY+FmFmSd3VwNpa4+d h2Ense4t5i52YgooTtlUbCt5MO/C+di049vSYODnuv9SRqGAuPeGeWFfWA7K65csyzdAK9/Grii 3S2jU9CK5XVyevt6kkd4o/1Kv3KUtMQ3E3zb5q7UpZSTxGCobmup8Ra71LXDXvlnGCNzabMeDwS VIr+xeC0AN+owK+ejwwHgoLdt8PTLjojV4MIDB3U8FyRaMp7ZyDLJXBrASf0IyHv9wq8554HLRv EU5mD2zwgnPexxAS3IYo5VHUBFAx5aQkRti3jX2eDw1ZAQlC4y177zau2pRSKfzDXotAnIQXUos ZCKEixWnS3tDOElGFe9sWB8mdzTgdySB0hMfr8qI1HVITSfJTTeeZP3byKmKwwUGkAETZ04kIdr 4lsMUsUOnSDbINlG3nCzDg/Dle6kt5XseQoCRIwb0le8+Y8oy0ET7cssQp9OaQL/D4Po9Kf4sM2 LrXmvzzS/FHxLfn+spQfRu4Qebytbeaof7AxBkvvV4sGVwRnWq2qJv9qMGerGX9DZky1rjcNMU5 8gciZMCcRtQSuNeNnAZ8xBGRq89fB5Sp2bQ73icS5O/8TrGMpkPAVgTz13Qg0Rjhxm38PKD34+8 BE5GTD32QZAbisw== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Extend the build files under man/ to also generate man pages for gpio-manager, gpiocli and each of the former's sub-commands. Signed-off-by: Bartosz Golaszewski --- Makefile.am | 8 ++++++- man/Makefile.am | 72 +++++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 67 insertions(+), 13 deletions(-) diff --git a/Makefile.am b/Makefile.am index c824dc4..d310e17 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,7 +24,7 @@ endif if WITH_TOOLS -SUBDIRS += tools man +SUBDIRS += tools endif @@ -44,6 +44,12 @@ SUBDIRS += dbus endif +if WITH_MANPAGES + +SUBDIRS += man + +endif + if HAS_DOXYGEN doc: Doxyfile diff --git a/man/Makefile.am b/man/Makefile.am index ddd0628..8d8bc46 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,22 +1,70 @@ # SPDX-License-Identifier: GPL-2.0-or-later # SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski +# SPDX-FileCopyrightText: 2025 Bartosz Golaszewski -if WITH_MANPAGES +MAN_ENTRIES = +MAN_DEPS = -dist_man1_MANS = \ - gpiodetect.man \ - gpioinfo.man \ - gpioget.man \ - gpioset.man \ - gpiomon.man \ - gpionotify.man +if WITH_TOOLS -%.man: $(top_builddir)/tools/$(*F) - $(AM_V_GEN)help2man $(top_builddir)/tools/$(*F) --include=$(srcdir)/template --output=$(builddir)/$@ --no-info +TOOLS = \ + gpiodetect \ + gpioinfo \ + gpioget \ + gpioset \ + gpiomon \ + gpionotify + +MAN_ENTRIES += $(TOOLS) +MAN_DEPS += $(foreach dep,$(TOOLS),$(top_builddir)/tools/$(dep)) + +endif + +if WITH_DBUS + +GPIOCLI_CMDS = \ + detect \ + find \ + info \ + get \ + monitor \ + notify \ + reconfigure \ + release \ + request \ + requests \ + set \ + wait + +MAN_ENTRIES += \ + gpio-manager \ + gpiocli \ + $(foreach cmd,$(GPIOCLI_CMDS),gpiocli-$(cmd)) + +MAN_DEPS += \ + $(top_builddir)/dbus/manager/gpio-manager + $(top_builddir)/dbus/client/gpiocli + +endif + +dist_man1_MANS := $(foreach entry,$(MAN_ENTRIES),$(entry).man) + +%.man: $(MAN_DEPS) + $(AM_V_GEN)export PATH=$(top_builddir)/dbus/manager/:$(top_builddir)/dbus/client/:$(top_builddir)/tools/:$$PATH; \ + if [ "$(*F)" = "gpio-manager" ]; then \ + EXEC=$(*F); \ + NAME="libgpiod D-Bus daemon"; \ + HELP=--help-option=--help; \ + else \ + EXEC=$(if $(findstring -,$(*F)),$(word 1,$(subst -, ,$(*F))),$(*F)); \ + NAME=$(if $(findstring -,$(*F)),$(word 2,$(subst -, ,$(*F))),"libgpiod command-line utility"); \ + HELP=$(if $(findstring -,$(*F)),--help-option="$(word 2,$(subst -, ,$(*F))) --help",--help-option=--help); \ + fi; \ + help2man $$EXEC \ + --include=$(srcdir)/template --output=$(builddir)/$@ --no-info \ + --name="$$NAME" "$$HELP" --manual=$(*F) clean-local: rm -f $(dist_man1_MANS) -endif - EXTRA_DIST = template From patchwork Tue Feb 11 12:59:33 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864620 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 040AA221D9C for ; Tue, 11 Feb 2025 12:59:52 +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=1739278796; cv=none; b=Iac7/KGM/OfovxM7CF8dk8JF4yp0GQA5mdekGY+M3jcP5fheMgtqVwmnXX6PCunk3FZSfvfvVnjg+LkYBv0Oie3KEjqwgPTMF4CGXlMuub5rfOLsPezdsSWxYIu2gqEzCdyWpzDYqILiXc8/BMdxXTnn51pGFNMoP0p0FEszHkA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278796; c=relaxed/simple; bh=Fbuw8kVL0vwogyLyeklarf4oeXGKTsGmJXfwmNJg5Es=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=TbU0bF/vFIZ3kiUcdmUQELRtfTFqYeKTRJf8GWaZtZXC87qrV4o3YW1udagpBvxCeLkvWpSeMXNuDOa7cJGpDJZrL8rplWGMHTY3cijLqBO+id6Sb6RgoksMUnW1TVgbQo41Nt0LPHmSkn+hL/WZHfjAXxinOMHJfdi9FXZj7xg= 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=TaD+Blq0; 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="TaD+Blq0" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-43946b5920cso13181225e9.1 for ; Tue, 11 Feb 2025 04:59:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278791; x=1739883591; 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=QyzLaP6BpnPLKkpaJZ4tl51k+ZRZ2BVWdPz3ztHG8+I=; b=TaD+Blq09jZIYxEGbb1DDf3DKQYVQb0b4tNeWt2frEIshXgdPw2p3cyjCpX85qTllx r1snAXH1YS9VTKExDZyh6VHRL9FX6AiF2fzSQFkA3iTlnv3/tHawPjzBg5zhU6AFo4/D CgcpuxtxyJaGmKpKfBIAAa3MMWBBeB6ryCfUBlQqhq/WG6lxrx557i1AYdrvR5pi9Yah zEz3RjrVAJnisvhOtAbF1WFs0WJvX2rxtBzKdLCSAqTcYM6sqBa6YlPApdzdA5OnQYKj z5YBCCT67iHVRWKziwzVZD0Rfi5c55ink0sV6yAN4dK3bYopCWLPNZO//5eKT5RvqeUW DvrQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278791; x=1739883591; 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=QyzLaP6BpnPLKkpaJZ4tl51k+ZRZ2BVWdPz3ztHG8+I=; b=XOEeLdww1cVV3irhsw6BE8EL1xqvk60gfpsmDLAxe+CtmzrNZhcLRBng8z7u6yS8Bf TUsaVsAUHIiLVPNpzYgynzbPlRYYKAuhew130Ur2ePvY7ivuIbg/YajLtXlIO991M0/x UHH7/6+75JZ4XW59Vs98DwbMxS4MrQxNvdiqOTtxFaznfAcQwJiohBKh6eb7m2t71+xj /BGGEW3fSokZoSXNeDb3JvRDImefoUeMY4DqaFC4+C58rLP4JvPx2gG/I1HsfyHlHqxx J55MCMq4jLt5TokjG9wLRTNxQKKagiAZfkYlTzHl4Nv6bchZ2ItMiLzcoo5qQ2jbOY94 7KcQ== X-Forwarded-Encrypted: i=1; AJvYcCUKFX6LGZ6X+2/pWoVnIboonHado5TKBv+FcPsqCJzRaP+YCZgmGbVWKfU/KtlvSr2BCdN3vuA8+eCB@vger.kernel.org X-Gm-Message-State: AOJu0YwKbwapD+0p/O6rWUhhdBUglSZxq7vS5vIUnMqa4U+CjlMfMOtb yGy1t+WqkI4RQ22crmJZQFxXRVP5+JMDUGTHjLfVO6Sb3EqqSvkgeflfxIx1Pag= X-Gm-Gg: ASbGnctJ3hQMSKoQbhpGiKxNlvjhvYyPLiljd5yKoK/VLMe45VwrdNIA4o9T0ujAaz0 /H3NnyjpTVXqxlCVf//BD1KOqQJ+l05lpWr9FVoEgs4ypQauPu8i7xUU/Jumam74cY8Uid63DHD 5WY7Akhx5GXh5CojyDbDy8VJ5WtGDxPufLoKhKGWZWq3RyCcRDG41yZkCnfPn6PMG3J76XS6td4 NRRzC5EKwFdo3MPUsAJgndncVnL8T7bsNMXTqBMG1URFyWL6Eat5zjyp5AfP8HT+wzVJJg65CWx 6kgesMA= X-Google-Smtp-Source: AGHT+IGe+Svwbv99aOm0SSzjxXO+9ArK71NgETiTbjuwbyd+74JR7nY8Cis/SkZXtC7P6aS8t69tTQ== X-Received: by 2002:a05:6000:4023:b0:38d:e420:3984 with SMTP id ffacd0b85a97d-38de4203c6fmr3619625f8f.39.1739278790753; Tue, 11 Feb 2025 04:59:50 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:50 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:33 +0100 Subject: [PATCH libgpiod v4 12/17] doc: provide sphinx docs for the core C API and C++ bindings Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-12-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=35877; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=9rUXVn/mp8astJLkdG70TrnQDDgRzJR1RRI7yGCqTcw=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m3KgnxyTKp9BRaf1Ec6J+G2s4XFY0fNhvgh weqCC53q26JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtwAKCRARpy6gFHHX crZbEAC3+E8/ToKhNDglpwhN4+ONU5fgi9gN6o3/lsFZ0N2vt/xVCImvOMwiNzYWArxNTrKSJL1 MoCNA5/TOeKxEi7NHDOryzLEgkJsPjzKYWDt2WH+wiB+QcU3j60mqcKDR+RIf/MVzNRqW2uw3S+ TsbSieXClNasV5kq6VxYQrYze8Vf/MvlE+rrC/YgP+3JhhL9RcKIVsG8el6MUDT0RQwdcfaQpgd p6wBhPl9txiqjfvDADaiXMVvCR+nsi9sdQ51V9KTxV2mnPAclTUpUD+orsz7omuKi9uHxPJR0oO ASBaHYZzYRLnLGsOuO785sFsWICxQY9J6qQ6OTX/C4MYyBlpFPhT+mfWn/HP0kLInJ1ntXci+rL b2x9i1Rocrff//AwzJ8eOW9XRzs5K7mUEOari8MyXNCmlU9PJnsy0Ru9jG9PVtG8W/itQKEyL2c ifzdgauYV5rNwTVEsI7fMMlzC96TnjBsB6KMtZDvDqaIAXWozGupjknPpeX3qbAuxMEhCkkuyRj oLG/i1yquA+ZQKA5Li6U1nVObxEtfQzDtpQzMBKn6rmGA3CJjKtqO0typtwQ8fJz02PUOtxWMDK j8aEfIVhvbH5IWEvYwFKMoyieWxmmLm/KAW8fkP1Oq32alCLGSE4/uyyTNmZ9bw7F02MG8Jt/q1 +6iraphmYQvZBtw== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Current sphinx/ contents are mostly WiP. Let's beat them into shape for publishing on ReadTheDocs. Integrate the API documentation generated with doxygen for the core C API and C++ bindings into sphinx using breathe. Update configure.ac to check for sphinx-build in addition to doxygen and make the main Makefile trigger a sphinx build on `make doc` (although the docs can also be generated without starting the build system by running: `sphinx-build ./docs/ docs/sphinx-output`). Move the introduction text from the main header into the relevant .rst file. Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where all the documentation now lives. Update .gitignore where needed. Signed-off-by: Bartosz Golaszewski --- .gitignore | 2 - .readthedocs.yaml | 16 +++---- Doxyfile.in | 105 ----------------------------------------- Makefile.am | 12 ++--- README | 12 ++--- configure.ac | 9 +++- docs/.gitignore | 5 ++ docs/Doxyfile | 12 +++++ docs/Makefile.am | 45 ++++++++++++++++++ docs/bindings.rst | 20 ++++++++ docs/conf.py | 53 +++++++++++++++++++++ docs/core_api.rst | 62 ++++++++++++++++++++++++ docs/core_chip_info.rst | 11 +++++ docs/core_chips.rst | 11 +++++ docs/core_edge_event.rst | 11 +++++ docs/core_line_config.rst | 11 +++++ docs/core_line_defs.rst | 11 +++++ docs/core_line_info.rst | 11 +++++ docs/core_line_request.rst | 11 +++++ docs/core_line_settings.rst | 11 +++++ docs/core_line_watch.rst | 11 +++++ docs/core_misc.rst | 11 +++++ docs/core_request_config.rst | 11 +++++ docs/cpp_api.rst | 34 +++++++++++++ docs/cpp_chip.rst | 12 +++++ docs/cpp_chip_info.rst | 12 +++++ docs/cpp_edge_event.rst | 12 +++++ docs/cpp_edge_event_buffer.rst | 12 +++++ docs/cpp_exceptions.rst | 18 +++++++ docs/cpp_info_event.rst | 12 +++++ docs/cpp_line.rst | 24 ++++++++++ docs/cpp_line_config.rst | 12 +++++ docs/cpp_line_info.rst | 12 +++++ docs/cpp_line_request.rst | 15 ++++++ docs/cpp_line_settings.rst | 12 +++++ docs/cpp_misc.rst | 16 +++++++ docs/cpp_request_config.rst | 12 +++++ docs/index.rst | 28 +++++++++++ docs/requirements.txt | 5 ++ include/gpiod.h | 36 -------------- sphinx/conf.py | 68 -------------------------- sphinx/contents.rst | 24 ---------- 42 files changed, 591 insertions(+), 259 deletions(-) diff --git a/.gitignore b/.gitignore index c3a29d8..7b5fa15 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,6 @@ *.la generated-*.c generated-*.h -doc *.pc *.tar.gz *.patch @@ -16,7 +15,6 @@ tags # autotools stuff .deps/ .libs/ -Doxyfile Makefile Makefile.in aclocal.m4 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f40e95f..510b5c1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,6 @@ # SPDX-License-Identifier: LGPL-2.1-or-later # SPDX-FileCopyrightText: 2022 Kent Gibson +# SPDX-FileCopyrightText: 2024 Bartosz Golaszewski # # This file is part of libgpiod. @@ -12,16 +13,15 @@ version: 2 build: os: ubuntu-22.04 tools: - python: "3.11" - # doxygen is available by default, but just in case. - # others are definitely missing. + python: "3.12" apt_packages: - - autoconf - - autoconf-archive - - libtool - - m4 + # doxygen is available by default, but just in case. - doxygen - graphviz sphinx: - configuration: sphinx/conf.py + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt diff --git a/Doxyfile.in b/Doxyfile.in deleted file mode 100644 index 9c85e21..0000000 --- a/Doxyfile.in +++ /dev/null @@ -1,105 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0-or-later -# SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski - -# libgpiod doxygen configuration - -# General configuration -PROJECT_NAME = libgpiod -PROJECT_NUMBER = @VERSION_STR@ -OUTPUT_DIRECTORY = doc -OUTPUT_LANGUAGE = English -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_STATIC = YES -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ALWAYS_DETAILED_SEC = NO -FULL_PATH_NAMES = NO -STRIP_FROM_PATH = @top_srcdir@ -INTERNAL_DOCS = NO -STRIP_CODE_COMMENTS = YES -CASE_SENSE_NAMES = YES -SHORT_NAMES = NO -HIDE_SCOPE_NAMES = NO -VERBATIM_HEADERS = YES -SHOW_INCLUDE_FILES = YES -JAVADOC_AUTOBRIEF = YES -INHERIT_DOCS = YES -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -DISTRIBUTE_GROUP_DOC = NO -TAB_SIZE = 8 -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -ALIASES = -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -OPTIMIZE_OUTPUT_FOR_C = YES -SHOW_USED_FILES = YES -QUIET = YES -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_FORMAT = -WARN_LOGFILE = -INPUT = @top_srcdir@/include/gpiod.h \ - @top_srcdir@/bindings/cxx/gpiod.hpp \ - @top_srcdir@/bindings/cxx/gpiodcxx/ -SOURCE_BROWSER = YES -INLINE_SOURCES = NO -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -ALPHABETICAL_INDEX = NO -IGNORE_PREFIX = -SEARCHENGINE = NO -ENABLE_PREPROCESSING = YES - -# HTML output -GENERATE_HTML = YES -HTML_OUTPUT = -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -GENERATE_HTMLHELP = NO -GENERATE_CHI = NO -BINARY_TOC = NO -TOC_EXPAND = NO -DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 -GENERATE_TREEVIEW = NO -TREEVIEW_WIDTH = 250 - -# LaTeX output -GENERATE_LATEX = NO -LATEX_OUTPUT = -COMPACT_LATEX = NO -PAPER_TYPE = a4 -EXTRA_PACKAGES = -LATEX_HEADER = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO - -# RTF output -GENERATE_RTF = NO -RTF_OUTPUT = -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = - -# Man page output -GENERATE_MAN = YES -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_LINKS = YES - -# XML output -GENERATE_XML = YES - -# External references -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO diff --git a/Makefile.am b/Makefile.am index d310e17..6cbae6d 100644 --- a/Makefile.am +++ b/Makefile.am @@ -50,15 +50,13 @@ SUBDIRS += man endif -if HAS_DOXYGEN +if WITH_DOCS -doc: Doxyfile - $(AM_V_GEN)doxygen Doxyfile -.PHONY: doc +SUBDIRS += docs -clean-local: - rm -rf doc +docs: + $(MAKE) -C docs docs -EXTRA_DIST += Doxyfile +.PHONY: docs endif diff --git a/README b/README index 80ad939..28a3dfd 100644 --- a/README +++ b/README @@ -333,14 +333,12 @@ bindings use the standard tests module layout and the #[test] attribute. DOCUMENTATION ------------- -All API symbols exposed by the core C API and C++ bindings are documented with -doxygen markup blocks. Doxygen documentation can be generated by executing -'make doc' given that the doxygen executable is available in the system. +The project uses sphinx to automatically generate the documentation. The system +needs to provide doxygen and sphinx-build programs. With those in place, the +build can be invoked with 'make docs'. This generates documentation for the +core C API as well as C++ and python bindings. -Python bindings contain help strings that can be accessed with the help -builtin. - -Rust bindings use rustdoc. +Rust bindings use rustdoc, GLib bindings use gi-docgen. Man pages for command-line programs are generated automatically if gpio-tools were selected and help2man is available in the system. diff --git a/configure.ac b/configure.ac index 5a7e01c..8eec855 100644 --- a/configure.ac +++ b/configure.ac @@ -328,12 +328,16 @@ then fi AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false]) -AM_CONDITIONAL([HAS_DOXYGEN], [test "x$has_doxygen" = xtrue]) +AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false]) +AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue]) if test "x$has_doxygen" = xfalse then AC_MSG_NOTICE([doxygen not found - documentation cannot be generated]) fi -AM_COND_IF([HAS_DOXYGEN], [AC_CONFIG_FILES([Doxyfile])]) +if test "x$has_sphinx" = xfalse +then + AC_MSG_NOTICE([sphinx-build not found - documentation cannot be generated]) +fi if test "x$cross_compiling" = xno then @@ -350,6 +354,7 @@ AC_CONFIG_FILES([Makefile lib/Makefile lib/libgpiod.pc contrib/Makefile + docs/Makefile examples/Makefile tools/Makefile tests/Makefile diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..86f8cfd --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +doxygen-output +sphinx-output diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 0000000..8c5b5df --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,12 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 +# SPDX-FileCopyrightText: 2022 Bartosz Golaszewski + +PROJECT_NAME = libgpiod +OUTPUT_DIRECTORY = doxygen-output +INPUT = ../include/gpiod.h \ + ../bindings/cxx/gpiod.hpp \ + ../bindings/cxx/gpiodcxx/ +GENERATE_XML = YES +WARN_IF_UNDOCUMENTED = YES +QUIET = YES +EXTRACT_ALL = YES diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..0b0618b --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +DOCS_DEPS = \ + bindings.rst \ + conf.py \ + core_api.rst \ + core_chip_info.rst \ + core_chips.rst \ + core_edge_event.rst \ + core_line_config.rst \ + core_line_defs.rst \ + core_line_info.rst \ + core_line_request.rst \ + core_line_settings.rst \ + core_line_watch.rst \ + core_misc.rst \ + core_request_config.rst \ + cpp_api.rst \ + cpp_chip_info.rst \ + cpp_chip.rst \ + cpp_edge_event_buffer.rst \ + cpp_edge_event.rst \ + cpp_exceptions.rst \ + cpp_info_event.rst \ + cpp_line_config.rst \ + cpp_line_info.rst \ + cpp_line_request.rst \ + cpp_line.rst \ + cpp_line_settings.rst \ + cpp_misc.rst \ + cpp_request_config.rst \ + Doxyfile \ + index.rst + +docs: $(DOCS_DEPS) + pushd ..; sphinx-build ./docs/ ./docs/sphinx-output; popd + +.PHONY: docs + +clean-local: + rm -rf sphinx-output + rm -rf doxygen-output + +EXTRA_DIST = $(DOCS_DEPS) requirements.txt diff --git a/docs/bindings.rst b/docs/bindings.rst new file mode 100644 index 0000000..069fc8f --- /dev/null +++ b/docs/bindings.rst @@ -0,0 +1,20 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod high-level language bindings + +High-level language bindings to libgpiod +======================================== + +The bindings provide a more straightforward interface to the base, low-level +C library. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + cpp_api diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..04c8c3b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,53 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +# This file is part of libgpiod. +# +# Configuration file for the Sphinx documentation builder. + +import os +import re +import subprocess +import sys + +project = "libgpiod" +copyright = "2017-2025, Bartosz Golaszewski" +author = "Bartosz Golaszewski" + +master_doc = "index" +source_suffix = ".rst" + +# Extract the full version from configure.ac (including -devel, -rc and other +# tags). +with open("../configure.ac", "r") as fd: + version = "" + extra = "" + for line in fd.readlines(): + match = re.search(r"AC_INIT\(\[libgpiod\], \[(.*?)\]\)", line) + if match: + version = match.group(1) + continue + + match = re.search(r"AC_SUBST\(EXTRA_VERSION, \[(.*?)\]\)", line) + if match: + extra = match.group(1) + + release = f"{version}{extra}" + +extensions = ["breathe"] + +breathe_projects = {"libgpiod": "./doxygen-output/xml"} +breathe_default_project = "libgpiod" + +# Use the RTD theme if available +sphinx_rtd_theme = None +try: + import sphinx_rtd_theme + + extensions.append("sphinx_rtd_theme") +except ImportError: + pass + +html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default" + +subprocess.run(["doxygen", "Doxyfile"]) diff --git a/docs/core_api.rst b/docs/core_api.rst new file mode 100644 index 0000000..9424fcd --- /dev/null +++ b/docs/core_api.rst @@ -0,0 +1,62 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod core API documentation + +libgpiod core API +================= + +This is the complete documentation of the public API made available to users of +**libgpiod**. + +The API is logically split into several sections. For each opaque data class, +there's a set of functions for manipulating it. Together they can be thought +of as objects and their methods in OOP parlance. + +.. note:: + General note on error handling: all functions exported by libgpiod that can + fail, set errno to one of the error values defined in errno.h upon failure. + The way of notifying the caller that an error occurred varies between + functions, but in general a function that returns an ``int``, returns ``-1`` + on error, while a function returning a pointer indicates an error condition + by returning a **NULL pointer**. It's not practical to list all possible + error codes for every function as they propagate errors from the underlying + libc functions. + +In general libgpiod functions are **NULL-aware**. For functions that are +logically methods of data classes - ones that take a pointer to the object of +that class as the first argument - passing a NULL-pointer will result in the +program aborting the execution. For non-methods, init functions and methods +that take a pointer as any of the subsequent arguments, the handling of a +NULL-pointer depends on the implementation and may range from gracefully +handling it, ignoring it or returning an error. + +**libgpiod** is **thread-aware** but does not provide any further thread-safety +guarantees. This requires the user to ensure that at most one thread may work +with an object at any time. Sharing objects across threads is allowed if +a suitable synchronization mechanism serializes the access. Different, +standalone objects can safely be used concurrently. + +.. note:: + Most libgpiod objects are standalone. Exceptions - such as events allocated + in buffers - exist and are noted in the documentation. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + core_chips + core_chip_info + core_line_defs + core_line_info + core_line_watch + core_line_settings + core_line_config + core_request_config + core_line_request + core_edge_event + core_misc diff --git a/docs/core_chip_info.rst b/docs/core_chip_info.rst new file mode 100644 index 0000000..00d06ca --- /dev/null +++ b/docs/core_chip_info.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygengroup:: chip_info diff --git a/docs/core_chips.rst b/docs/core_chips.rst new file mode 100644 index 0000000..cd6eaac --- /dev/null +++ b/docs/core_chips.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygengroup:: chips diff --git a/docs/core_edge_event.rst b/docs/core_edge_event.rst new file mode 100644 index 0000000..2ec05b8 --- /dev/null +++ b/docs/core_edge_event.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygengroup:: edge_event diff --git a/docs/core_line_config.rst b/docs/core_line_config.rst new file mode 100644 index 0000000..b217ee1 --- /dev/null +++ b/docs/core_line_config.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygengroup:: line_config diff --git a/docs/core_line_defs.rst b/docs/core_line_defs.rst new file mode 100644 index 0000000..898f2a9 --- /dev/null +++ b/docs/core_line_defs.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line definitions +===================== + +.. doxygengroup:: line_defs diff --git a/docs/core_line_info.rst b/docs/core_line_info.rst new file mode 100644 index 0000000..403c3bb --- /dev/null +++ b/docs/core_line_info.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line information +===================== + +.. doxygengroup:: line_info diff --git a/docs/core_line_request.rst b/docs/core_line_request.rst new file mode 100644 index 0000000..74e477d --- /dev/null +++ b/docs/core_line_request.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================== + +.. doxygengroup:: line_request diff --git a/docs/core_line_settings.rst b/docs/core_line_settings.rst new file mode 100644 index 0000000..e557f19 --- /dev/null +++ b/docs/core_line_settings.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygengroup:: line_settings diff --git a/docs/core_line_watch.rst b/docs/core_line_watch.rst new file mode 100644 index 0000000..8f078cb --- /dev/null +++ b/docs/core_line_watch.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line watch +=============== + +.. doxygengroup:: line_watch diff --git a/docs/core_misc.rst b/docs/core_misc.rst new file mode 100644 index 0000000..34c327f --- /dev/null +++ b/docs/core_misc.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod misc interfaces +======================== + +.. doxygengroup:: misc diff --git a/docs/core_request_config.rst b/docs/core_request_config.rst new file mode 100644 index 0000000..328063c --- /dev/null +++ b/docs/core_request_config.rst @@ -0,0 +1,11 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygengroup:: request_config diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst new file mode 100644 index 0000000..83a6aa4 --- /dev/null +++ b/docs/cpp_api.rst @@ -0,0 +1,34 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiodcxx API documentation + +libgpiod C++ bindings API +========================= + +The **C++ bindings** for **libgpiod** provide a modern C++ wrapper around the +core C API. These bindings make it easier to work with GPIO lines in C++ by +offering an **object-oriented** approach and **RAII** (Resource Acquisition +Is Initialization) principles for managing resources. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + cpp_chip + cpp_chip_info + cpp_edge_event + cpp_edge_event_buffer + cpp_exceptions + cpp_info_event + cpp_line + cpp_line_info + cpp_line_config + cpp_line_settings + cpp_request_config + cpp_line_request + cpp_misc diff --git a/docs/cpp_chip.rst b/docs/cpp_chip.rst new file mode 100644 index 0000000..c74ed66 --- /dev/null +++ b/docs/cpp_chip.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. doxygenclass:: gpiod::chip + :members: diff --git a/docs/cpp_chip_info.rst b/docs/cpp_chip_info.rst new file mode 100644 index 0000000..e81c0d7 --- /dev/null +++ b/docs/cpp_chip_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. doxygenclass:: gpiod::chip_info + :members: diff --git a/docs/cpp_edge_event.rst b/docs/cpp_edge_event.rst new file mode 100644 index 0000000..c01e01d --- /dev/null +++ b/docs/cpp_edge_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. doxygenclass:: gpiod::edge_event + :members: diff --git a/docs/cpp_edge_event_buffer.rst b/docs/cpp_edge_event_buffer.rst new file mode 100644 index 0000000..c792776 --- /dev/null +++ b/docs/cpp_edge_event_buffer.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event buffer +====================== + +.. doxygenclass:: gpiod::edge_event_buffer + :members: diff --git a/docs/cpp_exceptions.rst b/docs/cpp_exceptions.rst new file mode 100644 index 0000000..96eb815 --- /dev/null +++ b/docs/cpp_exceptions.rst @@ -0,0 +1,18 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod exceptions +=================== + +.. doxygenclass:: gpiod::chip_closed + :members: + +.. doxygenclass:: gpiod::request_released + :members: + +.. doxygenclass:: gpiod::bad_mapping + :members: diff --git a/docs/cpp_info_event.rst b/docs/cpp_info_event.rst new file mode 100644 index 0000000..cb8256c --- /dev/null +++ b/docs/cpp_info_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. doxygenclass:: gpiod::info_event + :members: diff --git a/docs/cpp_line.rst b/docs/cpp_line.rst new file mode 100644 index 0000000..f7a483b --- /dev/null +++ b/docs/cpp_line.rst @@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiodcxx line definitions +============================ + +.. doxygenclass:: gpiod::line::offset + :members: + +.. doxygenenum:: gpiod::line::value + +.. doxygenenum:: gpiod::line::direction + +.. doxygenenum:: gpiod::line::edge + +.. doxygenenum:: gpiod::line::bias + +.. doxygenenum:: gpiod::line::drive + +.. doxygenenum:: gpiod::line::clock diff --git a/docs/cpp_line_config.rst b/docs/cpp_line_config.rst new file mode 100644 index 0000000..51b5374 --- /dev/null +++ b/docs/cpp_line_config.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line configuration +======================= + +.. doxygenclass:: gpiod::line_config + :members: diff --git a/docs/cpp_line_info.rst b/docs/cpp_line_info.rst new file mode 100644 index 0000000..7c9c59b --- /dev/null +++ b/docs/cpp_line_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line info +============== + +.. doxygenclass:: gpiod::line_info + :members: diff --git a/docs/cpp_line_request.rst b/docs/cpp_line_request.rst new file mode 100644 index 0000000..0e356f5 --- /dev/null +++ b/docs/cpp_line_request.rst @@ -0,0 +1,15 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. doxygenclass:: gpiod::request_builder + :members: + +.. doxygenclass:: gpiod::line_request + :members: diff --git a/docs/cpp_line_settings.rst b/docs/cpp_line_settings.rst new file mode 100644 index 0000000..1892d59 --- /dev/null +++ b/docs/cpp_line_settings.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. doxygenclass:: gpiod::line_settings + :members: diff --git a/docs/cpp_misc.rst b/docs/cpp_misc.rst new file mode 100644 index 0000000..ed57fbc --- /dev/null +++ b/docs/cpp_misc.rst @@ -0,0 +1,16 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiodcxx misc interfaces +=========================== + +.. doxygenclass:: gpiod::timestamp + :members: + +.. doxygenfunction:: gpiod::is_gpiochip_device + +.. doxygenfunction:: gpiod::api_version diff --git a/docs/cpp_request_config.rst b/docs/cpp_request_config.rst new file mode 100644 index 0000000..26f4388 --- /dev/null +++ b/docs/cpp_request_config.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO request configuration +========================== + +.. doxygenclass:: gpiod::request_config + :members: diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..8dcea20 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,28 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod documentation master file. + +Welcome to libgpiod's documentation! +==================================== + +The **libgpiod** project provides a low-level C library, bindings to high-level +languages and tools for interacting with the GPIO (General Purpose Input/Output) +lines on Linux systems. + +It replaces the older, legacy GPIO sysfs interface, which has been deprecated +in the Linux kernel. The newer GPIO character device interface (introduced in +Linux kernel version 4.8) provides a more flexible and efficient way to +interact with GPIO lines, and libgpiod is the primary tool for working with +this interface. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + core_api + bindings diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9866547 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +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` From patchwork Tue Feb 11 12:59:34 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864619 Received: from mail-wr1-f53.google.com (mail-wr1-f53.google.com [209.85.221.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 07F8C215793 for ; Tue, 11 Feb 2025 12:59:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.53 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278796; cv=none; b=U09bi9F0E28R7PEWjWyGSmFvlzXu8mcOn/vgSw/B8fGKZcliFr3o4QEex0dgwa3fKz3E0T3fSK84PReVlRT4+3n65eQqjVEgILzfH0MdtDzwKM4lXJfDcQGQ7w/djDVVVk1UXO8k/fF4rtXEaKM+rwKmYohkEYVuC4+ycsjB1K8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278796; c=relaxed/simple; bh=sv5jd+aZKb5A3ehW0lDT+74RH9tP3fBs93kGmvNBXdE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=Hc1FXwEwohIebF/feGZGFrNxJsdgP384+qcwZ9j4kLfDG1yB8YqzTeSIcEZ2L/VaYUMqkJ1frEeIjOcRaHURHWctzU5PjlXzI+XxdaH+WxSQt5edHDrWXAemILuyK12VHGlZBN4lgjNfkumyvMVxK7HVM542OcjF3KVyGUWYW90= 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=s91DYsm1; arc=none smtp.client-ip=209.85.221.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="s91DYsm1" Received: by mail-wr1-f53.google.com with SMTP id ffacd0b85a97d-38dcb7122c1so3517044f8f.2 for ; Tue, 11 Feb 2025 04:59:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278793; x=1739883593; 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=UkUmUcKe4VndENMhfh4iGMZVtl5QOXM6snLn+fIOv70=; b=s91DYsm1rrQGJPFPvQVXTYEwyEG7w4CMMPV1ppDEgqzXA8wWaot5OTVZK83YOQQfPM JGX1sdCKW4rx6jH5ij3BUDSy0CHnczTq2F0G6ynAFpWphLMZQvrEtpqIMsp91vL2cmcl aeqcWaTKCeZAzi0RjVNNW4iR59tYIyDk3hbNiBZV3qHBnwUVF2Wmad3r4NeY4DIH85RR 9P6jC1XtQz/W+n6D+SruWiHdoq/yvsvBrLTV16PilkixtV5YvsNx59BtwIwZa9q9wcqp dJPTV1AcVnuqCQlZSHwq5MMRrTT8eNcZVamv0XyfUGzH7eieyOcP8d7VIK/bnv+hIvLI Rypg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278793; x=1739883593; 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=UkUmUcKe4VndENMhfh4iGMZVtl5QOXM6snLn+fIOv70=; b=CAqKjn2lTJ5+xop90tlCfRU053gcuCtY5irS7bYbNF0sapMmFzTwNJFVfo0/boPMRI njQrTznVuHE+xdEmWOBHJV3A6U2dPllfdxJHHXhglBJSvCNX3mPpjMAZLHx9NcgM7BoC GUrj4Qz7lgeBst2AUI2fReYMZ/Q/l8mMumCB7mLoth0bPFvLJseI3mava3thTQKuQE2w YJglSpMhMimNDRudt494FCnnNMI59v7cu//BSD8QMxaS2ihrhR7+ySYofySGoshYNZEE waQZOzxcxdPjCV9MuXkf4ZjEoA1/J/D46Qz59Sb6yd0jQXKuZ6+htznK3cKW9AIho/zS 3wAQ== X-Forwarded-Encrypted: i=1; AJvYcCUcNdwjjvqYjICHK7ASSCrsJs2pFvY5iKE1A4JHTt7VLhaO1MPZ5OnBKA8+j/smwXcR4shXGC/wpYz+@vger.kernel.org X-Gm-Message-State: AOJu0YxC0TZIm6KCzgQ0UEBYNOYwQl618CsE5agBwjibou6gTgonAmEo p6RCc/xxqxjneByT1ySR2cpv5Hr25GKBwJ6xoJYq79xKhp9qbzQe1eJ0KSclexE= X-Gm-Gg: ASbGnctRnIo+Sg/pdehL0ORMxQUQC4Qm47uC3XIqNNJhfHdtp3jrrICt6a/hVLMmJA7 9xiKM/4rL5RgELS4A8lZ/sOXSUS6L8YYatZBxxLEUkGAdy1gDQK5/P1xtD1pkfAKSDwpSCDkhlo YgzNukr6+hLv5dYlpugAp0Qu+g+fYCgF16xBhjtpA1TIYbTqB8+8PtXvDvpqbX/9v1P7hIeKPmb 8xzXp9726w7Ic2xTlqVxsHEm3VnlaPgYWlOq3ASzJIMJyjiM0rwlyc91sW6k+cVkyMI/AtPQXjb aGiMj8I= X-Google-Smtp-Source: AGHT+IFEevF5GvJCbsqGDVstDocQFRz+S6f/+xQ07qcYTbrHEFI0rFPkgWYX6QkY5SSYdUGflnBn1A== X-Received: by 2002:a5d:6d8a:0:b0:38d:dfd7:cca6 with SMTP id ffacd0b85a97d-38ddfd7ce1cmr6590364f8f.22.1739278791552; Tue, 11 Feb 2025 04:59:51 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:51 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:34 +0100 Subject: [PATCH libgpiod v4 13/17] doc: add documentation for python bindings Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-13-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=8739; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=ak0DM9dfmdpdTsuqo+gHwS6h5DiMw4tEQvjTklsChCA=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m3ArUfX4jRFuDeqvYG7kXnECsPhBnXvwN5X VcgKZ1or7aJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtwAKCRARpy6gFHHX cqCtEACaFdNcew+XFKGJ3kbYNMqVR7FYMzQR8b3Ui9V6ZIolW/nRGxqAlmhiRjlfJniS0rz9GVw EQevG1YRfNjco5TYFfCd95T2bfi+GIB1PSp1DZH28BsH62q0Q6QchgDMj4YO51KsyRu48kq0mTe Z2F9EzTy75VRUgGXDfII7tzgsbSgycL9KIQ1Nqs4X/6P/G60UCcurTU2i8fL0g1eL5ElhVYdktg tBnP3PvpBI5Rx6xopnHP7DrnVx9HXYda5Kv9rzdAVCHQz0h9dgqVh/8dT2y01zX1AeS0V7DkWm4 7/k0qnA8QNiDAcPtlMuurnD53OQvUFQbKfp+44TFdKmyhFcHxcw/u87wInXrTacqJV3c2bRc9xD sbhPETbucNP6cms0eUOP26Q4XSkdPUIjRkSEg0LD07HP96gLJZj0vt7xhyDfCjNIKs9csNLr1Z4 jDt1vsSNiEkYcpO6a0P1J5v2WZ9NKvni//MkqxffGAfgcE6uZ9m0kryJr74riae6GlNwQMlvtlB 6A6uD0dV7qxm9w1tbaOL3u5DsXZbBhd/WW5ObJ+u8y1ngDwfj9KXrwXvcXf9wRR9sVFOKkMBlGW Li08A2TARRTFCkhQk9njt77AewtJpuNLQwb1s0uXNBOOGY9YqqYSUlKOg+AABNr6tXngMJDA1Y+ YWxsuruNTMzH1fA== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Integrate python docs with sphinx using autodoc and the import mock feature which allows us to avoid having to build the C extension. Signed-off-by: Bartosz Golaszewski --- docs/Makefile.am | 13 ++++++++++++- docs/bindings.rst | 1 + docs/conf.py | 6 +++++- docs/python_api.rst | 33 +++++++++++++++++++++++++++++++++ docs/python_chip.rst | 12 ++++++++++++ docs/python_chip_info.rst | 12 ++++++++++++ docs/python_edge_event.rst | 12 ++++++++++++ docs/python_exceptions.rst | 17 +++++++++++++++++ docs/python_info_event.rst | 12 ++++++++++++ docs/python_line.rst | 27 +++++++++++++++++++++++++++ docs/python_line_info.rst | 12 ++++++++++++ docs/python_line_request.rst | 13 +++++++++++++ docs/python_line_settings.rst | 12 ++++++++++++ docs/python_misc.rst | 13 +++++++++++++ 14 files changed, 193 insertions(+), 2 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 0b0618b..0cfa4d5 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -31,7 +31,18 @@ DOCS_DEPS = \ cpp_misc.rst \ cpp_request_config.rst \ Doxyfile \ - index.rst + index.rst \ + python_api.rst \ + python_chip_info.rst \ + python_chip.rst \ + python_edge_event.rst \ + python_exceptions.rst \ + python_info_event.rst \ + python_line_info.rst \ + python_line_request.rst \ + python_line.rst \ + python_line_settings.rst \ + python_misc.rst docs: $(DOCS_DEPS) pushd ..; sphinx-build ./docs/ ./docs/sphinx-output; popd diff --git a/docs/bindings.rst b/docs/bindings.rst index 069fc8f..ed7ec69 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -18,3 +18,4 @@ C library. :caption: Contents cpp_api + python_api diff --git a/docs/conf.py b/docs/conf.py index 04c8c3b..cbe1691 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,7 @@ import os import re import subprocess import sys +from pathlib import Path project = "libgpiod" copyright = "2017-2025, Bartosz Golaszewski" @@ -34,11 +35,14 @@ with open("../configure.ac", "r") as fd: release = f"{version}{extra}" -extensions = ["breathe"] +extensions = ["breathe", "sphinx.ext.autodoc"] breathe_projects = {"libgpiod": "./doxygen-output/xml"} breathe_default_project = "libgpiod" +sys.path.insert(0, str(Path("../bindings/python").resolve())) +autodoc_mock_imports = ["gpiod._ext"] + # Use the RTD theme if available sphinx_rtd_theme = None try: diff --git a/docs/python_api.rst b/docs/python_api.rst new file mode 100644 index 0000000..00b30cb --- /dev/null +++ b/docs/python_api.rst @@ -0,0 +1,33 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod python bindings documentation + +libgpiod Python bindings API +============================ + +The **libgpiod Python bindings** provide an interface to control and interact +with GPIO (General-Purpose Input/Output) lines on Linux systems using the +libgpiod library. The Python bindings allow developers to manage GPIO pins +easily through Python scripts, enabling tasks such as reading input values, +setting outputs, monitoring events, and configuring more fine-grained pin +options. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + python_chip + python_chip_info + python_exceptions + python_line + python_line_info + python_info_event + python_edge_event + python_line_settings + python_line_request + python_misc diff --git a/docs/python_chip.rst b/docs/python_chip.rst new file mode 100644 index 0000000..8f56004 --- /dev/null +++ b/docs/python_chip.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip +========= + +.. autoclass:: gpiod.Chip + :members: diff --git a/docs/python_chip_info.rst b/docs/python_chip_info.rst new file mode 100644 index 0000000..c6db865 --- /dev/null +++ b/docs/python_chip_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO chip info +============== + +.. autoclass:: gpiod.ChipInfo + :members: diff --git a/docs/python_edge_event.rst b/docs/python_edge_event.rst new file mode 100644 index 0000000..b316665 --- /dev/null +++ b/docs/python_edge_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO edge event +=============== + +.. autoclass:: gpiod.EdgeEvent + :members: diff --git a/docs/python_exceptions.rst b/docs/python_exceptions.rst new file mode 100644 index 0000000..260dc3d --- /dev/null +++ b/docs/python_exceptions.rst @@ -0,0 +1,17 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod python errors +====================== + +.. autoclass:: gpiod.ChipClosedError + :members: + :show-inheritance: + +.. autoclass:: gpiod.RequestReleasedError + :members: + :show-inheritance: diff --git a/docs/python_info_event.rst b/docs/python_info_event.rst new file mode 100644 index 0000000..b89cdfa --- /dev/null +++ b/docs/python_info_event.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO info event +=============== + +.. autoclass:: gpiod.InfoEvent + :members: diff --git a/docs/python_line.rst b/docs/python_line.rst new file mode 100644 index 0000000..ec8f09f --- /dev/null +++ b/docs/python_line.rst @@ -0,0 +1,27 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line definitions +===================== + +.. autoclass:: gpiod.line.Value + :members: + +.. autoclass:: gpiod.line.Direction + :members: + +.. autoclass:: gpiod.line.Bias + :members: + +.. autoclass:: gpiod.line.Drive + :members: + +.. autoclass:: gpiod.line.Edge + :members: + +.. autoclass:: gpiod.line.Clock + :members: diff --git a/docs/python_line_info.rst b/docs/python_line_info.rst new file mode 100644 index 0000000..06f526f --- /dev/null +++ b/docs/python_line_info.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + 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..9a58d47 --- /dev/null +++ b/docs/python_line_request.rst @@ -0,0 +1,13 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. autoclass:: gpiod.LineRequest + :members: + :class-doc-from: both diff --git a/docs/python_line_settings.rst b/docs/python_line_settings.rst new file mode 100644 index 0000000..b1d594e --- /dev/null +++ b/docs/python_line_settings.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line settings +================== + +.. autoclass:: gpiod.LineSettings + :members: diff --git a/docs/python_misc.rst b/docs/python_misc.rst new file mode 100644 index 0000000..3ba1e2d --- /dev/null +++ b/docs/python_misc.rst @@ -0,0 +1,13 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +libgpiod python bindings misc +============================= + +.. autofunction:: gpiod.is_gpiochip_device + +.. autofunction:: gpiod.request_lines From patchwork Tue Feb 11 12:59:35 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864214 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (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 2430A215799 for ; Tue, 11 Feb 2025 12:59:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278795; cv=none; b=S2UGLTTHpUBpYuCwi6jIzJGxYMhkz5wuZt6iItO8xg/2I/auL/6z+n/fUYVJRJlcRaaSByu1LQSyYY2+AC224Q9/lg71PVrbauWytfbRgelNl0N9EcDSz6g5NMnT/xewYfMp7PpSE830Rpznl0Gh0pRDHcUgPpRLdyVGQhblQG8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278795; c=relaxed/simple; bh=xtY16JuTPGy0f0AsElIlHsFkNo85eg7KSmoHacYE07Y=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=LDQUFiEk8GfidVANPEcgpJI3V6dXkyzFARLW8TX8IT789V108tewIQYNuNrg2sFrssFwpr94B1AWrWNgcph4yM65Sts2m1RYm98onYiYc6m3iqpKX2bkBrVklfNQNxUaO2hw6NVEi9AciFBrTEsyHsvuST6vbC2amYWnBhtwwEE= 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=n6YoOPWY; arc=none smtp.client-ip=209.85.128.51 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="n6YoOPWY" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-43618283dedso55382625e9.3 for ; Tue, 11 Feb 2025 04:59:53 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278792; x=1739883592; 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=ZPH+Pxwqlyrx1DSr8zde+bZJyhr4eJxNgQrIhm0XUcw=; b=n6YoOPWYk4H21/OcZX9AHpSZj40FhscfqFDEb69S8zRvrDkOElpJHzVrIMYeGQxs8b U9S4z8snGMzJDe8+xEdBqADO23s1tbODQPmxS/NbpAvAl5y9HOurogHNV/mGeshl/ItX ppSBxhSzRBL0XfUVDAiJpAPD1gzk6w5yVA6a/BhVoEcPNoE3Il9iortLcJHyRYJhlmyf tNPwdglDo/3ZlrpZIErYvwYN/NmSdtNoeOwieYZp/5/w04EsPtTvGshtL9VTt0XMPWWV a+J5Kivc27IetM5/hKUpIlQtufGKgPc3dlHFZ8qyAwcHNCGQBypz4VHRWFrEs9/n/xrT NVVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278792; x=1739883592; 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=ZPH+Pxwqlyrx1DSr8zde+bZJyhr4eJxNgQrIhm0XUcw=; b=cQ2oADK9CWi19YIYCiNC4VeLq387aMXVOd2vyQfAelEClkW+ScWrSjV5sPCiXGzith MYBngWwZ+H9Dp71kvyC0pD+u8UGci/5fuKlqC+fGQ24dnrVB//28ZOyk47y9VDWBJtyJ RZKhDg+pDvTEh66mf3QJKCyAf+RQvgqri6bfdOy1B9pHeL3HNMo4bo474BroVmNPNTTD qTSElYnnVOIiAawW4CqVIX6pQgV19Y2rLEXYTtLybkY5J11Z6F8muH734iEexO6UwlsQ rdvPqVcIUrVP0hlERmxQ5o6R7p691IoFEQHyPTiXvpuvykMW8yybXXUTneNEr+ntoheO kp5w== X-Forwarded-Encrypted: i=1; AJvYcCVBvTZj8Df/8vZt12RzBsMzNUFtZVqBYIFKr8U6miP0EwltUVSZGkbKlDTUZI85K1Tp6rTbsyYyz7Yy@vger.kernel.org X-Gm-Message-State: AOJu0YwihtTxQ+guuwfv5uW0BR/w7OcijiK1YJ4bVJ/Kp+8K1+cA3Ztg 6HArQTiN3x4VOlwKKW4Nxkql/AfLOWN9b5AbBGAZs8WaVz7tcUv7Rhb2eX/R7qHUJkPPeGNaPkW FswE= X-Gm-Gg: ASbGnctBJurZRiYh+5uHARYv2UdTOMSJ8NtjmfvLFdz0HdChLJluS3fa4z6OrWfSiZ9 9AxXD8CcskKQ0U5V1gAw+aqxNnjlQea5j8/2+oootx8LzAGngYdRi3k7C72p8Ymnd2GVaOBA22C ActhgrNVy5d3Num8IMqvYuXf3XrBXlMXbQxA/eoycipID/DFe7IM1qaz1+OnFXsajmFd52uJeJX Or4WYAVufLfBGMDa0jZpXmATZRhdqCXL4itglmR1d/NG3/9Yw9qbHIDXzg6zRn+KzFsLE+gOToU T1blDPs= X-Google-Smtp-Source: AGHT+IGVukhVj+2UDHcUjYTJ8XrXssPEQf3cnzaLKeDWU+q7Zt74VcW7bQ6FzmFsVsUHe+eLjVV80A== X-Received: by 2002:a05:600c:44c9:b0:439:34d3:63da with SMTP id 5b1f17b1804b1-43934d36692mr107533195e9.10.1739278792384; Tue, 11 Feb 2025 04:59:52 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:52 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:35 +0100 Subject: [PATCH libgpiod v4 14/17] doc: add documentation for GLib bindings Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-14-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=4189; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=en4nI9CttlbGrQfJ+gSjxV0dUmu73WEAI1tpbSKo/VQ=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m3ZqWwQkl/QUHNexSH96NxoU9+DquCFB/u9 0mK9icIC1KJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtwAKCRARpy6gFHHX cvQ3EAC1aKFcA6wjSWUwLVR2YIN9rY4aZli7vj8tOSCeapM7Fgvv/KV4BzaViD5WBsz6vou133y o9GlRXizMXMhBQQcZrTIgcwFhak2ezc/tmGUzOOx0xduO0l0ExveKzjq8+x64g7lpQl0eTZdpOl e7300mrxt6KGV3G5A03sstlfLQaMK8kjLriClU67BqYXNupP6cdyExHNsUzpHRWDtzaALxHEBgq 1UxpFZnCHnB9TXCZ/fCdixedEWlHR1EXtrwk08tPhDuIbNRB7JocplJyy60wBCXAD/2cIoGWPbn WT+zId5mSEY2c60RijYEMFwuWTJ+1zGMUZ/LZ1mC2djMjlY90uxVI7g1gkG/84OVK6UeZM+0uES ND0RcQGCuQ0Ixkvgk/jQCrFCWzVUwcApkqsuxI9khoCEii/D2UFNWSGdpfqlPCrUM9Lh2cwEY0A OHS/8bDbFrbaWr9Y/GCbQRKWjHytzyAgT1KSA8EjI/sQzI7DyTqU6ZYR5jpwUzaxdqF68/oCXeh g/n1aWlPMbOBXOlqbNyQBhE6RvCirwQ0GoRFSdvIf4DrnLf9FDxb4Owp1fJywvdlaRHn0YIU0cJ ARa62sbfdh1iArJFRwAFNYDadSnq/dokr7PdEsylKAlg8bQZcqZFOhDm91T4ezBps2wBWor/+DJ OZxBjMhTZcS5B2g== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski The GObject docs are generated with gi-docgen and there doesn't seem to be an easy way of converting them to sphinx. Let's put the GLib docs statically into the sphinx output and reference them from the bindings chapter. Signed-off-by: Bartosz Golaszewski --- .readthedocs.yaml | 9 ++++++++- docs/Makefile.am | 1 + docs/bindings.rst | 1 + docs/conf.py | 41 +++++++++++++++++++++++++++++++++++++++++ docs/glib_api.rst | 23 +++++++++++++++++++++++ 5 files changed, 74 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 510b5c1..97086fa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,13 +11,20 @@ version: 2 build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: python: "3.12" apt_packages: + - autoconf + - autoconf-archive # doxygen is available by default, but just in case. - doxygen + - gi-docgen + - gir1.2-glib-2.0-dev + - gobject-introspection - graphviz + - libtool + - pkg-config sphinx: configuration: docs/conf.py diff --git a/docs/Makefile.am b/docs/Makefile.am index 0cfa4d5..3d5c1e4 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -32,6 +32,7 @@ DOCS_DEPS = \ cpp_request_config.rst \ Doxyfile \ index.rst \ + glib_api.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/bindings.rst b/docs/bindings.rst index ed7ec69..73f1262 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -19,3 +19,4 @@ C library. cpp_api python_api + glib_api diff --git a/docs/conf.py b/docs/conf.py index cbe1691..9d80bde 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,4 +54,45 @@ except ImportError: html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default" +# We need to know where to put docs generated by gi-docgen but app.outdir is +# only set once the builder is initialized. Let's delay running gi-docgen +# until we're notified. +def make_glib_docs(app): + # For some reason on RTD we're in the docs/ directory while during a local + # build, we're still in the top source directory. + prefix = "../" if os.getenv("READTHEDOCS") == "True" else "" + + subprocess.run( + [ + "gi-docgen", + "generate", + "--config", + f"{prefix}bindings/glib/gi-docgen.toml", + f"{prefix}bindings/glib/Gpiodglib-1.0.gir", + "--output-dir", + f"{app.outdir}", + ], + check=True, + ) + + +def setup(app): + app.connect("builder-inited", make_glib_docs) + + subprocess.run(["doxygen", "Doxyfile"]) + +cwd = os.getcwd() +os.chdir("..") +subprocess.run(["autoreconf", "-ifv"], check=True) +subprocess.run( + [ + "./configure", + "--enable-tools", + "--enable-bindings-glib", + "--enable-introspection", + ], + check=True, +) +subprocess.run(["make", "-j"], check=True) +os.chdir(cwd) diff --git a/docs/glib_api.rst b/docs/glib_api.rst new file mode 100644 index 0000000..307f5f7 --- /dev/null +++ b/docs/glib_api.rst @@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + libgpiod GObject API documentation + +libgpiod GObject bindings API +============================= + +**GObject bindings** for libgpiod provide a high-level, object-oriented +interface to interact with GPIO (General Purpose Input/Output) lines on Linux +systems. These bindings leverage the **GObject framework**, commonly used in +GNOME and GTK+ applications, to wrap the lower-level C API of libgpiod. + +.. warning:: + The documentation for GObject bindings is generated using gi-docgen and + cannot be easily integrated with sphinx documentation. Please navigate to + a separate section dedicated exclusively to the GLib part of the API. + +`Navigate to GObject bindings documentation `_ From patchwork Tue Feb 11 12:59:36 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864213 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 0EA9D21E0A6 for ; Tue, 11 Feb 2025 12:59:54 +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=1739278796; cv=none; b=RGFQUEtwe51BH57dfu45X/DxvUEw4Pyn0O8bqJBAO7DfGy2GfU1KmAJJlaEy90npe0xgzeclAd1LO/Ctjh3eEdM7XN28uKwIE6nWjE5OVE9wQ/9U/o+yxOcJrGe944Jm0vaCH0VoRqFt4P3l56lkuwLa/cQvBz31Ab+wr0uOXZ0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278796; c=relaxed/simple; bh=p911NYjePCvIy4unFKbNijnZ/wrz7z1YubSGlF53/nI=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=Anv6tCte7mNXUTvI4QH+Fb30tVx01dr0DJuvxUsTKHKKRfQjErBDt8BAboLWv6LF9d/nNu1ONosQLP+ZMi0/slYZe5AtjO8cFmfZHrvDLoF85utqCb7UD+YMRZHGowEYOCPEdnd5bA7IKdX0ppoBlU3zc7GkIEm0M2FJ0ha0Qw8= 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=tYD6ehRE; 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="tYD6ehRE" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-4361b0ec57aso55627765e9.0 for ; Tue, 11 Feb 2025 04:59:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278793; x=1739883593; 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=Dbvm9ZUkmh1TMfOZuNbEptwzOSI59vlfaRilfSxDrlA=; b=tYD6ehRE86PmIxBUzLTgEqIxTt9tLGATToYTLFzsi+0xBxvvIcZhmcz0BtRDYP5NX5 7g7PWX9kfjB+XwONzj+box0yhzAX0aKL/zV1V+GRWJfrcH2lCETt0jYe2t8FLwt7PEfW r8ZQL44Fy/N7NKN9CRaohLzvNdsOeUo+tuEcw5ZglglD0tmpjua8Btt+gCVlZftidk6j +QdiQUabjpo15/YBNy/XCTI7DUh5Jybv0/WS1P5hA8KmwofR5PW+aZ2EsH/zJyrfO4V6 A94vwQEyPCDDiSvvwazEHNZrOQcFfp0QHf0jidaEhss8y0+vKVKgbvYgYFk8YpAE6WPp 32pw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278793; x=1739883593; 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=Dbvm9ZUkmh1TMfOZuNbEptwzOSI59vlfaRilfSxDrlA=; b=RoaBadkMfrcPbQdfUwJSv1k2rBLGg+WX2LUmDRerpC9nn+rZ8/3UBBLvDV90xnhuQH zlCPCd3mHocRc7/znrNsFsKomg2CkPo2KtNUEaLcaRnDqLElX9nQZ+Kpa+f5xnQeqdjk JrlWo0V9b5v0YU0gjhxiffIjTJIzvFWGbeduqhlQVxYPFUxPgEFAwRp/tANWW4TfHPbA DkV0Vto3ZrUzkZ4e0zoahBxm84KpxZDZLWrtTVx0G04DY9IgZDrI2IUnHAdIb9V1gbE7 7eUiH5bxCbFqoeI7Fa4IKyza5pzDmKic7cIuSp3qEGVu91+WYP3oVvb58J2eSDSXzVsc a8Gg== X-Forwarded-Encrypted: i=1; AJvYcCWFm5zshzf9STY6HMxK0Qdmu2A5AAZZD14Q6OIbGJ1T8wDvzGQ3HYBBczN6IdCfv6IXtFSPG1xAbLbW@vger.kernel.org X-Gm-Message-State: AOJu0YxUzehsKviQ/x9vrBQcKvcKqbD1LZiYIXCmjMl895AdlR09icWC MVXsaJqEMO1D5lqYUjHh5krxJ22DazbqgPCdNBNLWrHRcCAyc6CUQlCxPbIj9UA= X-Gm-Gg: ASbGncs/fk+2RY4mTnbsGEn5PwY2A61tk0djIuAG36m+RKs2d+C2drp8Gl0e5FMbs32 9WBo5DJNr4VNJemli4bYRmDPBnb7/0kLm+1vC9KKynpndaXdXD04ZA2Y66WMoTwXkt4B2nzlEmm pP1IOTevYnCLeiDctbjEb1Eqs+VXDWZ4N+E+2QiCsvePSRrUODaXB96DXLjeDsMRltici23Zl/c HQH2w9qPUTRJ6tJ0MBOlrB0MxBhUohL1hHwKzJ2x5+3JoCTIPMsAHbVw2BUreDJqCQepmPOBi71 jC/DA3I= X-Google-Smtp-Source: AGHT+IEbG4vCKNMOsBCIm2MSlTCCABTVjXd0hdIK9/6/0r8h/umWaqxq+bZWgJbI7fk32AjbzhvTtg== X-Received: by 2002:a05:600c:4451:b0:439:4c83:2b8b with SMTP id 5b1f17b1804b1-4394c832cc2mr32944925e9.19.1739278793345; Tue, 11 Feb 2025 04:59:53 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:52 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:36 +0100 Subject: [PATCH libgpiod v4 15/17] doc: add documentation for gpio-tools Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-15-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=5206; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=9PAQCU4EfRjqJRUASzq50a8SnFgx0AaBDmM7QTHUeNo=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m3dCw4YVMRm+8L3/2QiYWOoSV9tiy69MeXp /Y6OQyYvFKJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJtwAKCRARpy6gFHHX cn44D/sG7a3diSI5gDyeELsywifKHI56AqiNtmEmVvhxeh8++AuHozP0AHUxgVndccEtizTRCla 8j6+fZxrkKpMZfVuJHz/KM+rWnGnPLlh6Epg/CtdQ+D/oDQJs9rHyKCCTQKc8+OzvmAa3jIrm2A M9Mx4yOT3FGQomRsbUtWB1rN8QhP03eeFmeT3UO2H1hnhMLWLyw7J3SJbQBeegDgg8cPh641Q5o zYndZLfGWujELq4ULYwUg3cg1CEgQv6zBHSlZHlRTRBBkAC+wbxJYzJrvStllzhJgdSB3knE/tU GQGOZzY8TI2rV3Thtli22rHQ0fK5MvAzDBzA2sniCAOOyvwGBX3QDmC7TROhWB1MCdiODCjS2JM 2NKO9GBjmrU3nfpeiyuMmTWmQkiwtLsIb1qXe4xowitOUY+c10HFKtgVWtAbeW47EY/i434HTqE W8/Ai5lT8CmYVqrCH6VPhws3xsu+KnjmuRlvC1xVvanfKq5gU+FMuaFMK9q9Pz1eJQ7G/q146dR GqkfQsOUrCInl8LMYPrl8DbHi2RForFKtDGgmDOdhFDdLt9Gard1h86wTIpUB+qZKJcjNYetnsW mTh1j030t/hKqXZy65WHiAbC6Yl6k2KA0cpcP4g4hwgM7Cxa8rFYTrxjk5QQ91q7DLhg/NZ7bjI TwxRXpxLl11tBCQ== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski We already generate man pages for gpio-tools. Let's use man2html to make them part of the sphinx docs. Signed-off-by: Bartosz Golaszewski --- .readthedocs.yaml | 2 ++ configure.ac | 32 +++++++++++++++++++------------- docs/.gitignore | 8 ++++++++ docs/Makefile.am | 1 + docs/conf.py | 22 ++++++++++++++++++++++ docs/gpio_tools.rst | 25 +++++++++++++++++++++++++ docs/index.rst | 1 + 7 files changed, 78 insertions(+), 13 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 97086fa..c2b0a7f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -19,11 +19,13 @@ build: - autoconf-archive # doxygen is available by default, but just in case. - doxygen + - help2man - gi-docgen - gir1.2-glib-2.0-dev - gobject-introspection - graphviz - libtool + - pandoc - pkg-config sphinx: diff --git a/configure.ac b/configure.ac index 8eec855..af5d53d 100644 --- a/configure.ac +++ b/configure.ac @@ -327,18 +327,6 @@ then AC_MSG_ERROR([systemdsystemunitdir not found - needed to enable systemd support])) fi -AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false]) -AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false]) -AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue]) -if test "x$has_doxygen" = xfalse -then - AC_MSG_NOTICE([doxygen not found - documentation cannot be generated]) -fi -if test "x$has_sphinx" = xfalse -then - AC_MSG_NOTICE([sphinx-build not found - documentation cannot be generated]) -fi - if test "x$cross_compiling" = xno then AC_CHECK_PROG([has_help2man], [help2man], [true], [false]) @@ -346,7 +334,25 @@ fi AM_CONDITIONAL([WITH_MANPAGES], [test "x$has_help2man" = xtrue]) if test "x$has_help2man" = xfalse then - AC_MSG_NOTICE([help2man not found - man pages cannot be generated automatically]) + AC_MSG_NOTICE([help2man not found - man pages and documentation cannot be generated]) +fi + +AC_DEFUN([DOC_PROG_NOT_FOUND], [AC_MSG_NOTICE([$1 not found - documentation cannot be generated])]) +AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false]) +AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false]) +AC_CHECK_PROG([has_pandoc], [pandoc], [true], [false]) +AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue && test "x$has_pandoc" = xtrue && test "x$has_help2man" = xtrue]) +if test "x$has_doxygen" = xfalse +then + DOC_PROG_NOT_FOUND(["doxygen"]) +fi +if test "x$has_sphinx" = xfalse +then + DOC_PROG_NOT_FOUND(["sphinx-build"]) +fi +if test "x$has_pandoc" = xfalse +then + DOC_PROG_NOT_FOUND(["pandoc"]) fi AC_CONFIG_FILES([Makefile diff --git a/docs/.gitignore b/docs/.gitignore index 86f8cfd..c9ffb90 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -3,3 +3,11 @@ doxygen-output sphinx-output + +# Automatically generated .rst +gpiodetect.rst +gpioinfo.rst +gpioget.rst +gpioset.rst +gpiomon.rst +gpionotify.rst diff --git a/docs/Makefile.am b/docs/Makefile.am index 3d5c1e4..1b5a46c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -33,6 +33,7 @@ DOCS_DEPS = \ Doxyfile \ index.rst \ glib_api.rst \ + gpio_tools.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/conf.py b/docs/conf.py index 9d80bde..06fe932 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,8 +91,30 @@ subprocess.run( "--enable-tools", "--enable-bindings-glib", "--enable-introspection", + "--enable-tools", ], check=True, ) subprocess.run(["make", "-j"], check=True) os.chdir(cwd) + +for page in [ + "gpiodetect", + "gpioinfo", + "gpioget", + "gpioset", + "gpiomon", + "gpionotify", +]: + subprocess.run( + [ + "pandoc", + "--from=man", + "--to=rst", + "--standalone", + "--wrap=none", + f"--output={page}.rst", + f"../man/{page}.man", + ], + check=True, + ) diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst new file mode 100644 index 0000000..7372de4 --- /dev/null +++ b/docs/gpio_tools.rst @@ -0,0 +1,25 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + GPIO tools documentation + +Command-line tools +================== + +The **libgpiod** project includes a suite of **command-line tools** to +facilitate GPIO manipulation from console and shell scripts. + +.. toctree:: + :maxdepth: 1 + :caption: Manual entries + + gpiodetect + gpioinfo + gpioget + gpioset + gpiomon + gpionotify diff --git a/docs/index.rst b/docs/index.rst index 8dcea20..a52cc3a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,3 +26,4 @@ this interface. core_api bindings + gpio_tools From patchwork Tue Feb 11 12:59:37 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864212 Received: from mail-wm1-f54.google.com (mail-wm1-f54.google.com [209.85.128.54]) (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 AE51E21E0BA for ; Tue, 11 Feb 2025 12:59:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.54 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278798; cv=none; b=YPNj5pJdK6FCtSQQeCTo9yHbyLa50GDi4ZJBxfWk35/+01tbTB0XGfZcQRmY3i6OLWxbS43VqwgXjsUIihrbWjJCSHJVPlgGdkcAUwacOtH8jmK9vJNnXJGmaosmMOzEacINp9EJamwhl0iSif4+atFaR8F/+USlSPfg/v39nBA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278798; c=relaxed/simple; bh=pZcR0PzqmqVwp/+EGp/cSk8P1KY7qKy2EamThKb/SIU=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=ZeF8pW/53YlTkWM30hpVqCr2rk3eGZ1g3fs6tT5ig+YaRnG8FRewtXJefnwoi9On/nKTgOiVn36+zD58qvWngHLKiJAfZcr4Momh2hXGu9WmgF9RCp0Aglq/bFATag0CuklIjpW9PIlLkeAK7T3eHC+ZgKX0jwJg0ZsMl4LB+44= 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=qCHBMgKp; arc=none smtp.client-ip=209.85.128.54 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="qCHBMgKp" Received: by mail-wm1-f54.google.com with SMTP id 5b1f17b1804b1-4361b0ec57aso55628095e9.0 for ; Tue, 11 Feb 2025 04:59:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278795; x=1739883595; 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=8vVZCU+yHAjmiNaJEaScySLgV9S9u7F+Ea2dbInUSdc=; b=qCHBMgKpaUdEyzJ7H9K9HI7M5Vsco2563Z3DOh2eo1hn+OwMaJ/Nv9NjEA2HWOTcNB 18pWbf1RRXW+extqr/aXnrDC4PmjedBVG0TaxKgdTgMWqVhxuGnHNtZw8hE0/S5f0Ypz dLb+SivhmGXyQNvpB1AVyar5v330XqIwTPRTl8VSSFD9Q1IrfYNLO59Up5K0M4eIxcQA nVHRde/xWFGkIOFPXFIP4oT0ETPbAOpJvtPaubXGf2k1FKATDxP5KT+ppizGg1II0p7K 2F5iY1FLyyGRd0G8QEULzB5EQ1Bu7pxndQUuwursX6TR7DmybzunvbUc8Q4IOM9+7RBi f+hg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278795; x=1739883595; 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=8vVZCU+yHAjmiNaJEaScySLgV9S9u7F+Ea2dbInUSdc=; b=J2MW8+xV2P6zXDqFz5WJ/BJO5ShvzwLd2eDZbIjyP0rFaxQS0GP0nnCVtiMXirrE2y MYwyskgs7qslw5aIPlY6cEXAr+LNEqN/EQ32wcamj8c5Dgfa39VEkmvgaFcJogP6pCIm eErmmjaxE0LwAR9HfI275Pibq5CYiHN6nuJHgqW+DCYehPbJZ6SfYwS8qx2Kp90uiwNo LvzSdOWZip+cdb4fDgXW98lCOgVBY0YzzKz/vvbpMnr64qkdL0rooWwsaJXqGl/yrkBg bKO0lSPxvxlUqqIMmiEEY8S6hB+6XVkw6mQ8YObZn9lxZRm8kqKsUFU/EY4nPGaA5yy6 P/1g== X-Forwarded-Encrypted: i=1; AJvYcCV9kLmgXrU0nOnCfv2/kVPJyOJ2GZFpHmlt7IGdgLUmMB4nlHi4bM5hmTv16zg274vwINm2xvMjj5yk@vger.kernel.org X-Gm-Message-State: AOJu0YxW1Q0gCDQ8OTFbaHvPRnKAwPpGS025radp+VSQ75EmnRAWG+Rg Rzt1dRqrOo9uxB70U2DoLlozWcvfOwczY7JQ4a6yEJHfqzZ54SSz8ncQGCh7Sbs= X-Gm-Gg: ASbGncuEGLsIiD396p/N7+v2AWpSuM3Epm4jFUqN6wPkuR/PlShjs6M9Tft6bhasOy5 ooPofuwIdVXh39juFQxqo2yPBiJjmcL25p0C/1u1nGx+I+T1GUFuZba+PhMEj2ejWqfs85FjOnr smPhzNxirvDuo5Lp+g5QbJZ0lAMfb4VcOoIDHdLUcs+BxT6DGhy+C7ooYQGglytTRuADKdB9dh9 tlDnqicwwX/j8Mta4CaKVS1zU9ULSsISF5npwwriYsYN7Jo4Ak05ciY90y+O9dj9nh/TXMNzPsW /Z5To8Q= X-Google-Smtp-Source: AGHT+IFd9Iey+TrXktzkRgh2SpKzh8WbuKb6qsKF92O2fFh2BOzxBLnQfobdOWetFdmkGiLNKQujmQ== X-Received: by 2002:a05:600c:4f8b:b0:439:40c1:1338 with SMTP id 5b1f17b1804b1-43940c11470mr101560955e9.11.1739278794527; Tue, 11 Feb 2025 04:59:54 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:53 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:37 +0100 Subject: [PATCH libgpiod v4 16/17] doc: add documentation for D-Bus API, daemon and command-line client Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-16-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=5329; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=GJVRfzZrXSyYmVo4vfibVn9csqUua3+DjonZU5isJ2E=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m4q8eNE+Mie7AVQMvjwCxdcO7uX8hQ2qkBz qQr7/yefH+JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJuAAKCRARpy6gFHHX cm9HEAC6Lop2TQwWjSLZBDIulGrzUdeUVhBFOtWqKgrY9t2q0QTXiFNVhUmUERlkR6RBXsikW44 ke3jPNM9IaQ5PTvrgAxIkiSWYvXPFSKzUJJRliX9Nb0Bpuw8yupyswaqzPIFAMldJXJrwIcvD0u nLKkKBgZEXLSlqLdyATPhB/sTse0pTkK1kU4e7yMVEtTBpF88GN0xrvoU5ii0e3Zyv5Zte4tst1 ZRWFI5QAVwkfOZ4Gt9wz9nMvKZ10b8cr5YCfnXuwtuqWvwyu5DVqK/UtUYWM6RN8CC3VB+32Ej8 t+3IkDSDxv+8dxIYbiBZ+CgcKxaFzS3eGmrHHgOwyboR0fKnxXmJr/OPjoG+8fV1Gz+T5CjkvfS 7s37+pDDuCVTMBj4do7CTbieAxCzzEVGlucS6pkuPE4/vxbi7VR3NqdxfbQNw2YshdHTRmHe6tJ 0kVyK6NR6JwUUqEO2iD2HeCEvXTKTbBfY1ERT3DKX6I0+NlxTa2H4Memq7+Equ+aryWaBDfSuPi JbmOvB4nFCY8zY3yJQ5iocuYKpSyzDpdKxLLCHKRAKlwW3SK2r2f0xdxxEJyjF/FuN6LiKZw1HJ P2AU3RTcOmcJ4DH11eiFvqK6yBBRh2uNsJRUkLsd37DNdv3wvLiieG1uob/4O9G/65LXg34dNQu hzDUY+z3on4ofLg== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski Use the man pages for gpio-manager and gpiocli + some manual labor to provide sphinx docs for the libgpiod D-Bus API. Signed-off-by: Bartosz Golaszewski --- .readthedocs.yaml | 2 ++ docs/.gitignore | 6 ++++++ docs/Makefile.am | 3 +++ docs/conf.py | 17 +++++++++++++++++ docs/dbus.rst | 24 ++++++++++++++++++++++++ docs/dbus_api.rst | 23 +++++++++++++++++++++++ docs/gpiocli_top.rst | 29 +++++++++++++++++++++++++++++ docs/index.rst | 1 + 8 files changed, 105 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c2b0a7f..5f4f5ac 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -24,6 +24,8 @@ build: - gir1.2-glib-2.0-dev - gobject-introspection - graphviz + - libglib2.0-dev-bin + - libgudev-1.0-dev - libtool - pandoc - pkg-config diff --git a/docs/.gitignore b/docs/.gitignore index c9ffb90..61dac9a 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -11,3 +11,9 @@ gpioget.rst gpioset.rst gpiomon.rst gpionotify.rst + +gpio-manager.rst + +dbus-io.gpiod1.*.rst +gpiocli.rst +gpiocli-*.rst diff --git a/docs/Makefile.am b/docs/Makefile.am index 1b5a46c..e03ca22 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -30,10 +30,13 @@ DOCS_DEPS = \ cpp_line_settings.rst \ cpp_misc.rst \ cpp_request_config.rst \ + dbus.rst \ + dbus_api.rst \ Doxyfile \ index.rst \ glib_api.rst \ gpio_tools.rst \ + gpiocli_top.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/conf.py b/docs/conf.py index 06fe932..6fb399d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,6 +92,7 @@ subprocess.run( "--enable-bindings-glib", "--enable-introspection", "--enable-tools", + "--enable-dbus", ], check=True, ) @@ -105,6 +106,20 @@ for page in [ "gpioset", "gpiomon", "gpionotify", + "gpio-manager", + "gpiocli", + "gpiocli-detect", + "gpiocli-find", + "gpiocli-info", + "gpiocli-get", + "gpiocli-monitor", + "gpiocli-notify", + "gpiocli-reconfigure", + "gpiocli-release", + "gpiocli-request", + "gpiocli-requests", + "gpiocli-set", + "gpiocli-wait", ]: subprocess.run( [ @@ -118,3 +133,5 @@ for page in [ ], check=True, ) + +subprocess.run(["gdbus-codegen", "--generate-rst", "dbus", "../dbus/lib/io.gpiod1.xml"]) diff --git a/docs/dbus.rst b/docs/dbus.rst new file mode 100644 index 0000000..0dcbb81 --- /dev/null +++ b/docs/dbus.rst @@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + GPIO D-Bus API, daemon and command-line client documentation + +D-Bus interface +=============== + +The **libgpiod D-Bus API** provides an abstraction for interacting with GPIO +chips on Linux systems via the D-Bus messaging system. It enables relatively +efficient, asynchronous control of GPIO lines, offering methods for +configuring, monitoring, and manipulating GPIOs. + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + dbus_api + gpio-manager + gpiocli_top diff --git a/docs/dbus_api.rst b/docs/dbus_api.rst new file mode 100644 index 0000000..6192949 --- /dev/null +++ b/docs/dbus_api.rst @@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + GPIO D-Bus API documentation + +D-Bus API +========= + +The following set of strictly defined interfaces allow users to use any +**D-Bus** library in order to interact with the **gpio-manager** as well as +reimplement the manager itself if required. + +.. toctree:: + :maxdepth: 1 + :caption: Interfaces + + dbus-io.gpiod1.Chip + dbus-io.gpiod1.Line + dbus-io.gpiod1.Request diff --git a/docs/gpiocli_top.rst b/docs/gpiocli_top.rst new file mode 100644 index 0000000..52e3295 --- /dev/null +++ b/docs/gpiocli_top.rst @@ -0,0 +1,29 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + GPIO D-Bus command-line client documentation + +Command-line client +=================== + +.. toctree:: + :maxdepth: 1 + :caption: Manual entries + + gpiocli + gpiocli-detect + gpiocli-find + gpiocli-info + gpiocli-get + gpiocli-monitor + gpiocli-notify + gpiocli-reconfigure + gpiocli-release + gpiocli-request + gpiocli-requests + gpiocli-set + gpiocli-wait diff --git a/docs/index.rst b/docs/index.rst index a52cc3a..3101e14 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,3 +27,4 @@ this interface. core_api bindings gpio_tools + dbus From patchwork Tue Feb 11 12:59:38 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 864618 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 06B9121E0A6 for ; Tue, 11 Feb 2025 12:59:57 +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=1739278801; cv=none; b=AMVhlSJsCOXNGx8DZ/+p8VD68w8qL3k7JB2rNn5uhicMwTfM56MjParZea+RPC2aI/3K4S+ZpPp8vIVzWKnNlu0bxJlgxLcQh838Iru+UhS3dOXTVWLIu1z/BeLzx1STSAz6XiAO09ieZtJbXnqCWNz13sDEScmjjDvIYBHEK2s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739278801; c=relaxed/simple; bh=72xGtHJB4fP3RR98QVNJAvUG34smJ57FuXh9c+iIQ5I=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=IrAlJpbIurVx4XsF5m4vF+RlFchDlC/7FekBT/RkQOgA2O5SwwOI+U5x4iUR6aL93X44k9E6+05d6u27lD2NoMipa6SK/oZQeAa6MpkBJiCQhKYQL38lz3poK1sN+FOIlr5sfwJskJsKtsmLH0476REItqc7U+cd3ecy3xgzSiw= 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=c3pH4IXq; 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="c3pH4IXq" Received: by mail-wm1-f50.google.com with SMTP id 5b1f17b1804b1-4361e89b6daso38331665e9.3 for ; Tue, 11 Feb 2025 04:59:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1739278796; x=1739883596; 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=i8voa9ADlsml+0nY/JUsmlfVRvqjETLDgn2dCqqicC8=; b=c3pH4IXq7Qwd48gHCr3E4PzWZ+2mZD/o8ogJ4EM7LEIcHQZj9142UFydu+I6ah8/rM zAADCcuGoxwKjN8K1B79eV7qyJYicpJ15pNVvadsAwkzTCNhD5cLdbP+GqinaTlp4rfr FsKgjrP5dVGkAkBwILzcWU9bZUjftQifUsXMFpM1gWcameyTIBIMiHpTOnHpqmWOqxYJ xFry5ANVlbw7zhZRb+AYeWNGNB6Pdif9tL/FwSKcZ4pSi+60Booy8UxDLEuSK9HBkFLS s4j1oEm3V6jbmSBNn0KtfDH5xk2a/qNK1Zlr5e8LYuMZtTTsgc20khGiUgT4W8MplqhT JgVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1739278796; x=1739883596; 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=i8voa9ADlsml+0nY/JUsmlfVRvqjETLDgn2dCqqicC8=; b=E6o/MnMBe7Oc8IZH62r5lCnIUVENpTh2wAMsmh9DaXzv7/niyVIi/cCEFnO+zYQGJJ yELDOSXwOLOQAuqei/4Cg/M2VgljOWFodqjTZllUEk8h5E9fJvxdWSCDsMe555P9FpxU a5POl5CJvjuXxvwLBrzj4gn9hIGIwW4wD50n7Fdce8UsxL+zyq/dfJGwevOD4vLsNazf GbMIDLMnLg8nGCKRaBKkqcu7JJsyx46ERNGfsN1Nvqa+RaS8XN6UrWIOdqjWQ7r4LDEp YTQ4UnmgK2ckFWjnMDx65DBnsbPfkRng2uwXolGppBLFN92HKPRPnYefYkrAiOFxgi/w Ue2A== X-Forwarded-Encrypted: i=1; AJvYcCU8sGNhY4l40iD4zQYZUDhoqP1xN6jtBYTClXbEynjzbilnXwXiqkciTNtJM7/5j+pqkpjc5MXe90Bl@vger.kernel.org X-Gm-Message-State: AOJu0YxPrcUy57psmBQoDv424XilcWnMJFHl0+o1gv+p3G0QxYf8+lfN PjCa7AZ0COyIsgAgQXwZiGD0r28zFbAxToV/DG0wXb5gVT+LynJu11Is/G5FDI4= X-Gm-Gg: ASbGncvSx08TobKUjUh4WkdV4bi1ViLMMzIbCRHw12otuRVX6dNtVddSA9xU22H8CQ6 xcUgbil+wMsf8GQQSNof+Le0sgyDITEuaULkGVjvaPAJhBVPe7EngD/6MCzPSUmkGX895Em5g81 HOn4r1FpjbcyvyDot/hx0eVVnhRNG+imJLKuC9N4FVqP2bCZoPoXScOJi9FNXhJE3vMBibQgpYm rcsC7/O78mESWvbePDbddaHIvcxV4BdRE9XwCoxVDno/wk9SVrZtFA7k33ooK0uqZpTjsJ0zEYP 7jDsa30= X-Google-Smtp-Source: AGHT+IE1gB22UZstCGksFM5915DbubVCPH3rUETAEfoIf/eJrbv5pMJRaTVlflWJBFJwXBSEA90nlw== X-Received: by 2002:a05:600c:3d97:b0:439:34f0:cf86 with SMTP id 5b1f17b1804b1-43934f0d067mr98469435e9.20.1739278795705; Tue, 11 Feb 2025 04:59:55 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:561:8978:1d41:636a]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4390d94d40csm209844095e9.9.2025.02.11.04.59.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 11 Feb 2025 04:59:55 -0800 (PST) From: Bartosz Golaszewski Date: Tue, 11 Feb 2025 13:59:38 +0100 Subject: [PATCH libgpiod v4 17/17] doc: move README contents to sphinx docs Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-Id: <20250211-improve-docs-v4-17-dc56702c2ca8@linaro.org> References: <20250211-improve-docs-v4-0-dc56702c2ca8@linaro.org> In-Reply-To: <20250211-improve-docs-v4-0-dc56702c2ca8@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=40436; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=r3RWVf+MVT12zUv6W8eDJ/UpO3wTzh3nZzuyn+InUuo=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnq0m4tKokK95RkKdt/zFb+oIqDiKEErKdmmQQl wM9k7cl8wuJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6tJuAAKCRARpy6gFHHX cpQhEACnGWz8PJwc+35WJ7bB7jAZZloojmZIDvJfJAs9xUPKiidut07dO+Z+s2F7TXOfNTwG+CB SRllAaim5mLXDqM/TSC0EVuDjZKX0c0rB30eNULQPzFT+BT3Je5xs3UwpSDem+DSxekDkBo4fJe 0ukIBIvPAcxbUTuXRbxBFmMq7zmNeYeBtG239zcCYIv8KatP4Ah+xMgzc285QExeyLgBGhHNDjI NYxz7WWTwwOWUouuoSGAaY4ZLI46d9sum5FbndieBnPR8zemkvHFX9KoNFKXVaZ3QbPBDM2NhGZ 12YPq72nIEGxpjNjtaI+jVREPcy/vG+8UCpDLhcZy2KyoHC59eAetryE+S70bleH3RMy37/eclI bwmNlEas4OnqNtw3d+ycmTkPPjo2RM5Mmcq0OiufIsFxZxZDSB1Wqbwc/tFTJTF/mAEoWqqzNK+ TGUiqiGMrnoB1AiPTQqHpNT5Sgo1ZHt8m2tO3sMNuhrqac778mjUy7tX55buZNuvn2anoFHqeUr 0gGtYA+QjTC0cFiMcgr3fTCGm1+mxOn9FOfQ5bahkjYi7JfXl09KVWJUhX6CyPRgDuUf/tCv1kT lq5B6xcQDdIAwr5rV4Pbt9xn7F2hVDwcDN/J36fkPOJYUUrOBF40jnuR+5VOunSOJBAGqEi8ZjS lyiiSOV9y/JERVQ== X-Developer-Key: i=bartosz.golaszewski@linaro.org; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 From: Bartosz Golaszewski We now have comprehensive documentation available online on readthedocs. Let's not duplicate docs in README - move all information into the sphinx files. While at it: make the remaining README use markdown. Signed-off-by: Bartosz Golaszewski --- README | 384 -------------------------------------------------- README.md | 11 ++ docs/bindings.rst | 9 +- docs/building.rst | 74 ++++++++++ docs/contributing.rst | 45 ++++++ docs/cpp_api.rst | 3 + docs/dbus.rst | 19 ++- docs/glib_api.rst | 3 + docs/gpio_tools.rst | 216 ++++++++++++++++++++++++++++ docs/gpiocli_top.rst | 81 +++++++++++ docs/index.rst | 23 ++- docs/python_api.rst | 8 ++ docs/rust_api.rst | 23 +++ docs/testing.rst | 46 ++++++ 14 files changed, 551 insertions(+), 394 deletions(-) diff --git a/README b/README deleted file mode 100644 index 28a3dfd..0000000 --- a/README +++ /dev/null @@ -1,384 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski - -libgpiod -======== - - libgpiod - C library and tools for interacting with the linux GPIO - character device (gpiod stands for GPIO device) - -Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use -the character device instead. Version 2 of libgpiod requires GPIO character -device uAPI v2 which was first released in linux 5.10. This library -encapsulates the ioctl calls and data structures behind a straightforward API. - -RATIONALE ---------- - -The new character device interface guarantees all allocated resources are -freed after closing the device file descriptor and adds several new features -that are not present in the obsolete sysfs interface (like event polling, -setting/reading multiple values at once or open-source and open-drain GPIOs). - -Unfortunately interacting with the linux device file can no longer be done -using only standard command-line tools. This is the reason for creating a -library encapsulating the cumbersome, ioctl-based kernel-userspace interaction -in a set of convenient functions and opaque data structures. - -Additionally this project contains a set of command-line tools that should -allow an easy conversion of user scripts to using the character device. - -BUILDING --------- - -This is a pretty standard autotools project. The core C library does not have -any external dependencies other than the standard C library with GNU extensions. - -The build system requires autotools, autoconf-archive, libtool and pkg-config -to be installed on the host system for the basic build. Development files for -additional libraries may be required depending on selected options. The -configure script will report any missing additional required dependencies. - -The command-line tools optionally depend on libedit for the interactive feature. - -To build the project (including command-line utilities) run: - - ./autogen.sh --enable-tools=yes --prefix= - make - make install - -The autogen script will execute ./configure and pass all the command-line -arguments to it. - -If building from release tarballs, the configure script is already provided and -there's no need to invoke autogen.sh. - -For all configure features, see: ./configure --help. - -TOOLS ------ - -There are currently six command-line tools available: - -* gpiodetect - list all gpiochips present on the system, their names, labels - and number of GPIO lines - -* gpioinfo - list lines, their gpiochip, offset, name, and direction, and - if in use then the consumer name and any other configured - attributes, such as active state, bias, drive, edge detection - and debounce period - -* gpioget - read values of specified GPIO lines - -* gpioset - set values of specified GPIO lines, holding the lines until the - process is killed or otherwise exits - -* gpiomon - wait for edge events on GPIO lines, specify which edges to watch - for, how many events to process before exiting, or if the events - should be reported to the console - -* gpionotify - wait for changed to the info for GPIO lines, specify which - changes to watch for, how many events to process before exiting, - or if the events should be reported to the console - -Examples: - - (using a Raspberry Pi 4B) - - # Detect the available gpiochips. - $ gpiodetect - gpiochip0 [pinctrl-bcm2711] (58 lines) - gpiochip1 [raspberrypi-exp-gpio] (8 lines) - - # Read the info for all the lines on a gpiochip. - $ gpioinfo -c 1 - gpiochip1 - 8 lines: - line 0: "BT_ON" output - line 1: "WL_ON" output - line 2: "PWR_LED_OFF" output active-low consumer="led1" - line 3: "GLOBAL_RESET" output - line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io" - line 5: "CAM_GPIO" output consumer="cam1_regulator" - line 6: "SD_PWR_ON" output consumer="sd_vcc_reg" - line 7: "SD_OC_N" input - - # Read the info for particular lines. - $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET - gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0" - gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1" - gpiochip1 3 "GLOBAL_RESET" output - - # Read the value of a single GPIO line by name. - $ gpioget RXD1 - "RXD1"=active - - # Read the value of a single GPIO line by chip and offset. - $ gpioget -c 0 15 - "15"=active - - # Read the value of a single GPIO line as a numeric value. - $ gpioget --numeric RXD1 - 1 - - # Read two values at the same time. Set the active state of the lines - # to low and without quoted names. - $ gpioget --active-low --unquoted GPIO23 GPIO24 - GPIO23=active GPIO24=active - - # Set the value of a line and hold the line until killed. - $ gpioset GPIO23=1 - - # Set values of two lines, then daemonize and hold the lines. - $ gpioset --daemonize GPIO23=1 GPIO24=0 - - # Set the value of a single line, hold it for 20ms, then exit. - $ gpioset --hold-period 20ms -t0 GPIO23=1 - - # Blink an LED on GPIO22 at 1Hz - $ gpioset -t500ms GPIO22=1 - - # Blink an LED on GPIO22 at 1Hz with a 20% duty cycle - $ gpioset -t200ms,800ms GPIO22=1 - - # Set some lines interactively (requires --enable-gpioset-interactive) - $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active - gpioset> get - GPIO23=inactive GPIO24=active - gpioset> toggle - gpioset> get - GPIO23=active GPIO24=inactive - gpioset> set GPIO24=1 - gpioset> get - GPIO23=active GPIO24=active - gpioset> toggle - gpioset> get - GPIO23=inactive GPIO24=inactive - gpioset> toggle GPIO23 - gpioset> get - GPIO23=active GPIO24=inactive - gpioset> exit - - # Wait for three rising edge events on a single GPIO line, then exit. - $ gpiomon --num-events=3 --edges=rising GPIO22 - 10002.907638045 rising "GPIO22" - 10037.132562259 rising "GPIO22" - 10047.179790748 rising "GPIO22" - - # Wait for three edge events on a single GPIO line, with time in local time - # and with unquoted line name, then exit. - $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22 - 2022-11-15T10:36:59.109615508 rising GPIO22 - 2022-11-15T10:36:59.129681898 falling GPIO22 - 2022-11-15T10:36:59.698971886 rising GPIO22 - - # Wait for falling edge events with a custom output format. - $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22 - 2 gpiochip0 22 GPIO22 10946.693481859 - 2 gpiochip0 22 GPIO22 10947.025347604 - 2 gpiochip0 22 GPIO22 10947.283716669 - 2 gpiochip0 22 GPIO22 10947.570109430 - ... - - # Block until an edge event occurs. Don't print anything. - $ gpiomon --num-events=1 --quiet GPIO22 - - # Monitor multiple lines, exit after the first edge event. - $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17 - - # Monitor a line for changes to info. - $ gpionotify GPIO23 - 11571.816473718 requested "GPIO23" - 11571.816535124 released "GPIO23" - 11572.722894029 requested "GPIO23" - 11572.722932843 released "GPIO23" - 11573.222998598 requested "GPIO23" - ... - - # Monitor a line for requests, reporting UTC time and unquoted line name. - $ gpionotify --utc --unquoted GPIO23 - 2022-11-15T03:05:23.807090687Z requested GPIO23 - 2022-11-15T03:05:23.807151390Z released GPIO23 - 2022-11-15T03:05:24.784984280Z requested GPIO23 - 2022-11-15T03:05:24.785023873Z released GPIO23 - ... - - # Monitor multiple lines, exit after the first is requested. - $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17 - - # Block until a line is released. - $ gpionotify --quiet --num-events=1 --event=released GPIO6 - -BINDINGS --------- - -High-level, object-oriented bindings for C++, GLib, python3 and Rust are -provided. They can be enabled by passing --enable-bindings-cxx, ---enable-bindings-glib, --enable-bindings-python and --enable-bindings-rust -arguments respectively to configure. - -C++ bindings require C++11 support and autoconf-archive collection if building -from git. - -GLib bindings requires GLib (as well as GObject, GIO and GIO-Unix) v2.54. - -Python bindings require python3 support and libpython development files. Please -refer to bindings/python/README.md for more information. - -Rust bindings require cargo support. When building the Rust bindings along the -C library using make, they will be automatically configured to build against the -build results of the C library. Please refer to bindings/rust/libgpiod/README.md -for more information. - -DBUS ----- - -A commonly requested feature for the GPIO character device was state persistence -after releasing the lines (as a kernel feature) or providing a central authority -(in user-space) that would be in charge of keeping the lines requested and in a -certain state (similarily to how the sysfs ABI works). DBus API has been -provided to address this requirement. We define an interface covering the -majority of the GPIO chardev's functionality and implement it from both the -server and client sides in the form of the gpio-manager daemon and the gpiocli -command-line utility for talking to the manager. - -DBus support can be built by passing --enable-dbus to configure. The daemon -is bundled with a systemd unit file and an example configuration file for the -io.gpiod1 interface that allows all users to access basic information about the -GPIOs in the system but only root to request lines or change their values. - -With the manager running the user can run gpiocli to control GPIOs by asking -gpio-manager to act on their behalf: - - # Detect chips in the system. - $ gpiocli detect - gpiochip0 [INT34C6:00] (463 lines) - - # Request a set of lines. Note that gpiocli exits immediately but the - # state of the lines is retained because it's the gpio-manager that - # requested them. - $ gpiocli request --output foo=active - request0 - - # Previous invocation printed out the name of the request by which the - # caller can refer to it later. All active requests can also be inspected - # at any time. - $ gpiocli requests - request0 (gpiochip1) Offsets: [5] - - # We can print the information about the requested line using the - # information above. - $ gpiocli info --chip=gpiochip1 5 - gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull] - - # We can now change the value of the line. - $ gpiocli set foo=inactive - - # And read it. - $ gpiocli get foo - "foo"=inactive - - # We can even reconfigure it to input and enable edge-detection. - $ gpiocli reconfigure --input --both-edges request0 - - # And wait for edge events. - $ gpiocli monitor cos - 21763952894920 rising "foo" - - # And finally release the request. - $ gpiocli release request0 - -For more information please refer to the output of gpiocli --help as well as -gpiocli --help which prints detailed info on every available command. - -Of course - this being DBus - users can talk to gpio-manager using any DBus -library available and are not limited to the provided client. - -TESTING -------- - -A comprehensive testing framework is included with the library and can be -used to test both the core library code as well as the kernel-to-user-space -interface. - -The minimum kernel version required to run the tests can be checked in the -tests/gpiod-test.c source file (it's subject to change if new features are -added to the kernel). The tests work together with the gpio-sim kernel module -which must either be built-in or available for loading using kmod. A helper -library - libgpiosim - is included to enable straightforward interaction with -the module. - -To build the testing executable add the '--enable-tests' option when running -the configure script. If enabled, the tests will be installed next to -gpio-tools. - -As opposed to standard autotools projects, libgpiod doesn't execute any tests -when invoking 'make check'. Instead the user must run them manually with -superuser privileges. - -The testing framework uses the GLib unit testing library so development package -for GLib must be installed. - -The gpio-tools programs can be tested separately using the gpio-tools-test.bash -script. It requires shunit2[1] to run and assumes that the tested executables are -in the same directory as the script. - -C++, Rust and Python bindings also include their own test-suites. All three -reuse the libgpiosim library to avoid code duplication when interacting with -gpio-sim. - -Python test-suite uses the standard unittest package. C++ tests use an external -testing framework - Catch2 - which must be installed in the system. Rust -bindings use the standard tests module layout and the #[test] attribute. - -DOCUMENTATION -------------- - -The project uses sphinx to automatically generate the documentation. The system -needs to provide doxygen and sphinx-build programs. With those in place, the -build can be invoked with 'make docs'. This generates documentation for the -core C API as well as C++ and python bindings. - -Rust bindings use rustdoc, GLib bindings use gi-docgen. - -Man pages for command-line programs are generated automatically if gpio-tools -were selected and help2man is available in the system. - -CONTRIBUTING ------------- - -Contributions are welcome - please send questions, patches and bug reports -to the linux-gpio mailing list[2] by e-mailing to linux-gpio@vger.kernel.org -(add the [libgpiod] prefix to the e-mail subject line). -Note that the mailing list quietly drops HTML formatted e-mail, so be sure -to send plain text[3]. - -Code submissions should stick to the linux kernel coding style[4] and -follow the kernel patch submission process[5] as applied to the libgpiod -source tree. All shell scripts must pass `shellcheck` tests[9]. All files -must have a license and copyright SPDX headers and the repo is expected to -pass the `reuse lint` check[10]. - -The mailing list archive[6] contains all the historical mails to the list, -and is the place to check to ensure your e-mail has been received. -Search for "libgpiod" to filter the list down to relevant messages. -Those also provide examples of the expected formatting. -Allow some time for your e-mail to propagate to the list before retrying, -particularly if there are no e-mails in the list more recent than yours. - -There is a libgpiod github page[7] available for reporting bugs and general -discussions and although PRs can be submitted and discussed, upstreambound -patches need to go through the mailing list nevertheless while release -tarballs should be fetched from kernel.org[8]. - -For more information, refer to CONTRIBUTING.md in this repository. - -[1] https://github.com/kward/shunit2 -[2] http://vger.kernel.org/vger-lists.html#linux-gpio -[3] https://docs.kernel.org/process/email-clients.html -[4] https://docs.kernel.org/process/coding-style.html -[5] https://docs.kernel.org/process/submitting-patches.html -[6] https://lore.kernel.org/linux-gpio/ -[7] https://github.com/brgl/libgpiod -[8] https://mirrors.edge.kernel.org/pub/software/libs/libgpiod/ -[9] https://www.shellcheck.net/ -[10] https://reuse.software/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..664dbc5 --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ + + + +libgpiod +======== + +C library and tools for interacting with the linux GPIO character device. + +The project is hosted at https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/. + +Documentation is available at https://libgpiod.readthedocs.io/. diff --git a/docs/bindings.rst b/docs/bindings.rst index 73f1262..dbe36ad 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -10,8 +10,12 @@ High-level language bindings to libgpiod ======================================== -The bindings provide a more straightforward interface to the base, low-level -C library. +Bindings provide a more straightforward interface to the core, low-level +C library. Object-oriented bindings for C++, GLib, python3 and Rust are +provided as part of the project. They can be enabled by passing +``--enable-bindings-cxx``, ``--enable-bindings-glib``, +``--enable-bindings-python`` and ``--enable-bindings-rust`` arguments to +configure respectively. .. toctree:: :maxdepth: 1 @@ -20,3 +24,4 @@ C library. cpp_api python_api glib_api + rust_api diff --git a/docs/building.rst b/docs/building.rst new file mode 100644 index 0000000..958c6fb --- /dev/null +++ b/docs/building.rst @@ -0,0 +1,74 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +Downloading, building & installing +================================== + +Downloading +----------- + +Libgpiod is packaged by several linux distributions. You should typically be +able to install it using your package manager. If you want to build libgpiod +from sources, the upstream git repository for libgpiod is hosted at +`kernel.org `_. +together with +`release tarballs `_. + +Building +-------- + +This is a pretty standard autotools project. The core C library does not have +any external dependencies other than the standard C library with GNU extensions. + +The build system requires the following packages to be installed on the host +system for the basic build: + + * ``autotools`` + * ``autoconf-archive`` + * ``libtool`` + * ``pkg-config`` + +.. note:: + Development files for additional libraries may be required depending on + selected options. The configure script will report any missing additional + required dependencies. + +To build the project (including command-line utilities) run: + +.. code-block:: none + + ./autogen.sh --enable-tools=yes + make + +.. note:: + The command-line tools optionally depend on libedit for the interactive + feature. + +The autogen script will execute ``./configure`` and pass all the command-line +arguments to it. + +.. note:: + If building from release tarballs, the configure script is already provided + and there's no need to invoke autogen.sh. + +For all configure features, see: ``./configure --help``. + +Installing +---------- + +To install the project run: + +.. code-block:: none + + make install + +.. note:: + The above may require superuser privileges. + +This will install libgpiod under the default system paths. If you want to +install it under non-standard path, pass the ``--prefix=`` +option to ``configure``. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..e46d50f --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,45 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + Contribution guide. + +Contributing +============ + +Contributions are welcome - please send questions, patches and bug reports to +the `linux-gpio mailing list +`_ +by e-mailing to ``linux-gpio@vger.kernel.org`` (add the ``[libgpiod]`` prefix +to the e-mail subject line). Note that the mailing list quietly drops HTML +formatted e-mail, so be sure to `send plain text +`_. + +Code submissions should stick to the `linux kernel coding style +`_ and follow the kernel +`patch submission process +`_ as applied to the +libgpiod source tree. All shell scripts must pass `shellcheck tests +`_. All files must have a license and copyright +SPDX headers and the repo is expected to pass the `reuse lint check +`_. + +The `mailing list archive `_ contains all +the historical mails to the list, and is the place to check to ensure your +e-mail has been received. +Search for `"libgpiod"` to filter the list down to relevant messages. Those +also provide examples of the expected formatting. Allow some time for your +e-mail to propagate to the list before retrying, particularly if there are no +e-mails in the list more recent than yours. + +There is a `libgpiod github page `_ +available for reporting bugs and general discussions and although PRs can be +submitted and discussed, upstreambound patches need to go through the mailing +list nevertheless. + +.. note:: + For more information, please refer to the ``CONTRIBUTING.md`` file in the + libgpiod source tree. diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst index 83a6aa4..4c76b56 100644 --- a/docs/cpp_api.rst +++ b/docs/cpp_api.rst @@ -15,6 +15,9 @@ core C API. These bindings make it easier to work with GPIO lines in C++ by offering an **object-oriented** approach and **RAII** (Resource Acquisition Is Initialization) principles for managing resources. +.. note:: + C++17 compiler support is required to build the bindings. + .. toctree:: :maxdepth: 1 :caption: Contents diff --git a/docs/dbus.rst b/docs/dbus.rst index 0dcbb81..98d2cbe 100644 --- a/docs/dbus.rst +++ b/docs/dbus.rst @@ -10,11 +10,24 @@ D-Bus interface =============== -The **libgpiod D-Bus API** provides an abstraction for interacting with GPIO -chips on Linux systems via the D-Bus messaging system. It enables relatively -efficient, asynchronous control of GPIO lines, offering methods for +A commonly requested feature for the GPIO character device was state persistence +after releasing the lines (as a kernel feature) or providing a central authority +(in user-space) that would be in charge of keeping the lines requested and in a +certain state (similarily to how the sysfs ABI works). **GPIO D-Bus API** has +been provided to address this requirement. We define an interface covering the +majority of the GPIO chardev's functionality and implement it from both the +server and client sides in the form of the **gpio-manager** daemon and the +**gpiocli** command-line utility for talking to the manager. It enables +relatively efficient, asynchronous control of GPIO lines, offering methods for configuring, monitoring, and manipulating GPIOs. +.. note:: + DBus support can be built by passing ``--enable-dbus`` to configure. The + daemon is bundled with a systemd unit file and an example configuration file + for the ``io.gpiod1`` interface that allows all users to access basic + information about the GPIOs in the system but only root to request lines or + change their values. + .. toctree:: :maxdepth: 1 :caption: Contents diff --git a/docs/glib_api.rst b/docs/glib_api.rst index 307f5f7..f6d8665 100644 --- a/docs/glib_api.rst +++ b/docs/glib_api.rst @@ -15,6 +15,9 @@ interface to interact with GPIO (General Purpose Input/Output) lines on Linux systems. These bindings leverage the **GObject framework**, commonly used in GNOME and GTK+ applications, to wrap the lower-level C API of libgpiod. +.. note:: + GLib bindings require GLib (as well as GObject, GIO and GIO-Unix) v2.80. + .. warning:: The documentation for GObject bindings is generated using gi-docgen and cannot be easily integrated with sphinx documentation. Please navigate to diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst index 7372de4..e4bf584 100644 --- a/docs/gpio_tools.rst +++ b/docs/gpio_tools.rst @@ -10,9 +10,29 @@ Command-line tools ================== +Overview +-------- + The **libgpiod** project includes a suite of **command-line tools** to facilitate GPIO manipulation from console and shell scripts. +There are currently six command-line tools available: + +* **gpiodetect**: list all gpiochips present on the system, their names, labels + and number of GPIO lines +* **gpioinfo**: list lines, their gpiochip, offset, name, and direction, and if + in use then the consumer name and any other configured attributes, such as + active state, bias, drive, edge detection and debounce period +* **gpioget**: read values of specified GPIO lines +* **gpioset**: set values of specified GPIO lines, holding the lines until the + process is killed or otherwise exits +* **gpiomon**: wait for edge events on GPIO lines, specify which edges to watch + for, how many events to process before exiting, or if the events should be + reported to the console +* **gpionotify**: wait for changed to the info for GPIO lines, specify which + changes to watch for, how many events to process before exiting, or if the + events should be reported to the console + .. toctree:: :maxdepth: 1 :caption: Manual entries @@ -23,3 +43,199 @@ facilitate GPIO manipulation from console and shell scripts. gpioset gpiomon gpionotify + +Examples +-------- + +.. note:: + The following examples where creating using a Raspberry Pi 4B. The pins + will be different on other board. + +Detect the available gpiochips: + +.. code-block:: none + + $ gpiodetect + gpiochip0 [pinctrl-bcm2711] (58 lines) + gpiochip1 [raspberrypi-exp-gpio] (8 lines) + +Read the info for all the lines on a gpiochip: + +.. code-block:: none + + $ gpioinfo -c 1 + gpiochip1 - 8 lines: + line 0: "BT_ON" output + line 1: "WL_ON" output + line 2: "PWR_LED_OFF" output active-low consumer="led1" + line 3: "GLOBAL_RESET" output + line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io" + line 5: "CAM_GPIO" output consumer="cam1_regulator" + line 6: "SD_PWR_ON" output consumer="sd_vcc_reg" + line 7: "SD_OC_N" input + +Read the info for particular lines: + +.. code-block:: none + + $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET + gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0" + gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1" + gpiochip1 3 "GLOBAL_RESET" output + +Read the value of a single GPIO line by name: + +.. code-block:: none + + $ gpioget RXD1 + "RXD1"=active + +Read the value of a single GPIO line by chip and offset: + +.. code-block:: none + + $ gpioget -c 0 15 + "15"=active + +Read the value of a single GPIO line as a numeric value: + +.. code-block:: none + + $ gpioget --numeric RXD1 + 1 + +Read two values at the same time, set the active state of the lines to low and +without quoted names: + +.. code-block:: none + + $ gpioget --active-low --unquoted GPIO23 GPIO24 + GPIO23=active GPIO24=active + +Set the value of a line and hold the line until killed: + +.. code-block:: none + + $ gpioset GPIO23=1 + +Set values of two lines, then daemonize and hold the lines: + +.. code-block:: none + + $ gpioset --daemonize GPIO23=1 GPIO24=0 + +Set the value of a single line, hold it for 20ms, then exit: + +.. code-block:: none + + $ gpioset --hold-period 20ms -t0 GPIO23=1 + +Blink an LED on GPIO22 at 1Hz: + +.. code-block:: none + + $ gpioset -t500ms GPIO22=1 + +Blink an LED on GPIO22 at 1Hz with a 20% duty cycle: + +.. code-block:: none + + $ gpioset -t200ms,800ms GPIO22=1 + +Set some lines interactively (requires ``--enable-gpioset-interactive``): + +.. code-block:: none + + $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active + gpioset> get + GPIO23=inactive GPIO24=active + gpioset> toggle + gpioset> get + GPIO23=active GPIO24=inactive + gpioset> set GPIO24=1 + gpioset> get + GPIO23=active GPIO24=active + gpioset> toggle + gpioset> get + GPIO23=inactive GPIO24=inactive + gpioset> toggle GPIO23 + gpioset> get + GPIO23=active GPIO24=inactive + gpioset> exit + +Wait for three rising edge events on a single GPIO line, then exit: + +.. code-block:: none + + $ gpiomon --num-events=3 --edges=rising GPIO22 + 10002.907638045 rising "GPIO22" + 10037.132562259 rising "GPIO22" + 10047.179790748 rising "GPIO22" + +Wait for three edge events on a single GPIO line, with time in local time and +with unquoted line name, then exit: + +.. code-block:: none + + $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22 + 2022-11-15T10:36:59.109615508 rising GPIO22 + 2022-11-15T10:36:59.129681898 falling GPIO22 + 2022-11-15T10:36:59.698971886 rising GPIO22 + +Wait for falling edge events with a custom output format: + +.. code-block:: none + + $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22 + 2 gpiochip0 22 GPIO22 10946.693481859 + 2 gpiochip0 22 GPIO22 10947.025347604 + 2 gpiochip0 22 GPIO22 10947.283716669 + 2 gpiochip0 22 GPIO22 10947.570109430 + ... + +Block until an edge event occurs, don't print anything: + +.. code-block:: none + + $ gpiomon --num-events=1 --quiet GPIO22 + +Monitor multiple lines, exit after the first edge event: + +.. code-block:: none + + $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17 + +Monitor a line for changes to info: + +.. code-block:: none + + $ gpionotify GPIO23 + 11571.816473718 requested "GPIO23" + 11571.816535124 released "GPIO23" + 11572.722894029 requested "GPIO23" + 11572.722932843 released "GPIO23" + 11573.222998598 requested "GPIO23" + ... + +Monitor a line for requests, reporting UTC time and unquoted line name: + +.. code-block:: none + + $ gpionotify --utc --unquoted GPIO23 + 2022-11-15T03:05:23.807090687Z requested GPIO23 + 2022-11-15T03:05:23.807151390Z released GPIO23 + 2022-11-15T03:05:24.784984280Z requested GPIO23 + 2022-11-15T03:05:24.785023873Z released GPIO23 + ... + +Monitor multiple lines, exit after the first is requested: + +.. code-block:: none + + $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17 + +Block until a line is released: + +.. code-block:: none + + $ gpionotify --quiet --num-events=1 --event=released GPIO6 diff --git a/docs/gpiocli_top.rst b/docs/gpiocli_top.rst index 52e3295..3b50b91 100644 --- a/docs/gpiocli_top.rst +++ b/docs/gpiocli_top.rst @@ -10,6 +10,87 @@ Command-line client =================== +With the manager running the user can run ``gpiocli`` to control GPIOs by +asking the ``gpio-manager`` to act on their behalf. + +Examples +-------- + +Detect chips in the system: + +.. code-block:: none + + $ gpiocli detect + gpiochip0 [INT34C6:00] (463 lines) + +Request a set of lines: + +.. note:: + **gpiocli** exits immediately but the state of the lines is retained + because it's the **gpio-manager** that requested them. + +.. code-block:: none + + $ gpiocli request --output foo=active + request0 + +Previous invocation printed out the name of the request by which the caller +can refer to it later. All active requests can also be inspected at any time: + +.. code-block:: none + + $ gpiocli requests + request0 (gpiochip1) Offsets: [5] + + +Print the information about the requested line using the information above: + +.. code-block:: none + + $ gpiocli info --chip=gpiochip1 5 + gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull] + +Change the value of the line: + +.. code-block:: none + + $ gpiocli set foo=inactive + +Read it back: + +.. code-block:: none + + $ gpiocli get foo + "foo"=inactive + +We can even reconfigure it to input and enable edge-detection: + +.. code-block:: none + + $ gpiocli reconfigure --input --both-edges request0 + +And wait for edge events: + +.. code-block:: none + + $ gpiocli monitor cos + 21763952894920 rising "foo" + +And finally release the request: + +.. code-block:: none + + $ gpiocli release request0 + +.. note:: + For more information please refer to the output of ``gpiocli --help`` as + well as ``gpiocli --help`` which prints detailed info on every + available command. + +.. note:: + Users can talk to **gpio-manager** using any **D-Bus** library available + and are not limited to the provided client. + .. toctree:: :maxdepth: 1 :caption: Manual entries diff --git a/docs/index.rst b/docs/index.rst index 3101e14..8c02c6a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,17 +14,30 @@ The **libgpiod** project provides a low-level C library, bindings to high-level languages and tools for interacting with the GPIO (General Purpose Input/Output) lines on Linux systems. -It replaces the older, legacy GPIO sysfs interface, which has been deprecated -in the Linux kernel. The newer GPIO character device interface (introduced in -Linux kernel version 4.8) provides a more flexible and efficient way to -interact with GPIO lines, and libgpiod is the primary tool for working with -this interface. +It replaces the older, **legacy GPIO sysfs interface**, which has been +deprecated in the Linux kernel. The newer **GPIO character device** interface +(introduced in **Linux kernel version 4.8**) provides a more flexible and +efficient way to interact with GPIO lines, and libgpiod is the **primary tool** +for working with this interface. + +The character device interface guarantees all allocated resources are freed +after closing the device file descriptor and adds several new features that +are not present in the obsolete sysfs interface (like reliable event polling, +setting/reading multiple values at once or open-source and open-drain GPIOs). + +Unfortunately interacting with the linux device file can no longer be done +using only standard command-line tools. This is the reason for creating a +library encapsulating the cumbersome, ioctl-based kernel-userspace interaction +in a set of convenient functions and opaque data structures. .. toctree:: :maxdepth: 1 :caption: Contents + building core_api bindings gpio_tools dbus + testing + contributing diff --git a/docs/python_api.rst b/docs/python_api.rst index 00b30cb..2c4f59d 100644 --- a/docs/python_api.rst +++ b/docs/python_api.rst @@ -17,6 +17,10 @@ easily through Python scripts, enabling tasks such as reading input values, setting outputs, monitoring events, and configuring more fine-grained pin options. +.. note:: + Python bindings require python3 support and libpython development files for + building from sources. + .. toctree:: :maxdepth: 1 :caption: Contents @@ -31,3 +35,7 @@ options. python_line_settings python_line_request python_misc + +.. note:: + Python bindings can be installed from https://pypi.org/ with pip by running + ``pip install gpiod``. diff --git a/docs/rust_api.rst b/docs/rust_api.rst new file mode 100644 index 0000000..1408b5c --- /dev/null +++ b/docs/rust_api.rst @@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +Where are the Rust bindings? +============================= + +.. warning:: + There's currently no good way of integrating rust documentation with sphinx. + Rust bindings should be documented on https://docs.rs/ but due to a yet + unsolved build problem, this is currently not the case. Please refer to the + in-source comments for now. + +Rust bindings are available on https://crates.io/ as the ``libgpiod`` package. + +.. note:: + When building the Rust bindings along the C library using make, they will + be automatically configured to build against the build results of the + C library. Building rust bindings requires cargo to be available on the + system. diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 0000000..e645e71 --- /dev/null +++ b/docs/testing.rst @@ -0,0 +1,46 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + + Contribution guide. + +Testing +======= + +A comprehensive testing framework is included with the library and can be used +to test both the core library code as well as the kernel-to-user-space +interface. + +The minimum kernel version required to run the tests can be checked in the +``tests/gpiod-test.c`` source file (it's subject to change if new features are +added to the kernel). The tests work together with the **gpio-sim** kernel +module which must either be built-in or available for loading using kmod. +A helper library - **libgpiosim** - is included to enable straightforward +interaction with the module. + +To build the testing executable add the ``--enable-tests`` option when running +the configure script. If enabled, the tests will be installed next to +**gpio-tools**. + +As opposed to standard autotools projects, libgpiod doesn't execute any tests +when invoking ``make check``. Instead the user must run them manually with +superuser privileges. + +The testing framework uses the **GLib unit testing** library so development +package for GLib must be installed. + +The **gpio-tools** programs can be tested separately using the +``gpio-tools-test.bash`` script. It requires `shunit2 +`_ to run and assumes that the tested +executables are in the same directory as the script. + +C++, Rust and Python bindings also include their own test-suites. All three +reuse the **libgpiosim** library to avoid code duplication when interacting +with **gpio-sim**. + +Python test-suite uses the standard unittest package. C++ tests use an external +testing framework - **Catch2** - which must be installed in the system. Rust +bindings use the standard tests module layout and the ``#[test]`` attribute.