From patchwork Thu Feb 6 12:21:58 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862738 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 9F50522AE71 for ; Thu, 6 Feb 2025 12:22:16 +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=1738844538; cv=none; b=jX1v2WD0LtzYjfEp4WJCHteX2daS8h48KdY3H+kDzQsEdRqK+O/VP8X/sD58Q9Vl1GcrAaLDsnKOi3Zp5QUyl9voBOtxEGkFBXMuDazouqq1Z3EQWf1836I79HzrOCY0Zt2j76/fyMQxNFkUazD8iXrxnuiUaDRUBhaEUI4nuQI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844538; c=relaxed/simple; bh=hoHBTR9TOL1ZwazPya3p072s+4nDSW8c30s00S0GpdQ=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=fDYtdO8hfNzkD3l6Nr4XGaQxrtNuQAGEWRHuS90cVnO7KwlHwclKvWdiSUBHCW5PyFP3sucRfsqkG0PXXvu3UkfILpnK6cZ0XAV5oHumDgeEo0C3MyInnE8noz1OYCgug980lUq90JAsfHatKYUCMWWNyHWpBG5M2hZUR7Mzg0M= 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=OJK0lDTP; 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="OJK0lDTP" Received: by mail-wm1-f50.google.com with SMTP id 5b1f17b1804b1-4362f61757fso8086355e9.2 for ; Thu, 06 Feb 2025 04:22:16 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844535; x=1739449335; 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=OJK0lDTP8DBucCH3KM+HjuBV+D3MbuNwGaNMQ96He2rUUVJDdvrGOlvZkJ0MzF+L/1 13DdY6x7VFqDxYyifc1rpGjxB9pDk5d945/st3NlQNzsdN8lU/GmwC1i44GqX9+LGwYh F/WY01wNg8mzqpTIr70SFygoOGonND8IdQjkvuDnG74MI4s1iV68g8sdup13sEflRopg KmqtkzFzEs1Nm+m7Q+sbxTXb9zHd4p/SRv0KCELV2kz69wyVDzJOxJPp9PXOD+MqVC/g IUI6uLyEigL9Ynf3xIwgyVTgzUp26+H2skD1TdFKdZc1RmjUFEutS43SB2j9rsV0OcWp DctQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844535; x=1739449335; 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=VAdTRLpJHgyBgZrhL8a7qEvIuq1yCr+PSNLlM0YYmRB7FeJBrIYgI55hpg7PlxNsu3 jLCD0HyJot9uP4JjgTVU5rAP4/jPnbJeUc6JQY4NnIr6Sd6+yNTv7iFXLhO+d8OGWqIw zY/A4gQLQ71ZfB4uOjY7bQrhraBFejuuqXssnCs8UxkA99Nd8hmeAGDpdX8Ot62XjyCk At2XeQkGfZI5pX2JITz0BOD/eV6O263EFtOmlZngHEYVMYKrtLU/JpsVAriSjo1UpXjA VUiT89FTN6iS4Hyh1uzqkKNgFq/8mlesoagNd74BHcxSFMCBBmUx7TKhs1FE6Y/2bgLg mXUA== X-Forwarded-Encrypted: i=1; AJvYcCUudbnrn9Kek/8dtNcSG4CBMpnrQB1kIj7LY6r700kppXVqU0KujI0jW6+E6yEbtxOPi+7lOsXCAsVJ@vger.kernel.org X-Gm-Message-State: AOJu0YxZ3iR39zZxqGQM8DxWFMvvaF36S16bvTgBHjR/Vaqm2U9v1XGp B7hg6NK8NmSAytjMDUT2igJ+G+KTfzH64JxZQVg9rvb5eZ4Kl5RMUpfxVwrWOv4= X-Gm-Gg: ASbGncsv7tEbCHaRQx0vNiioeVwFkV1a64wRt5784azO05XqZkHEKkTK3wKEUZD5acy /lIP3z29VfjdRs/t3lY23XgWkICHsS1GnlZcyIZ9FrFIPn8alDhAgt2PA7wode7yH959aOpDtb6 qiPr2sCaw/o1tvvr4pMbzEs2SnjCmEPQt4F40sIH/D3LYeaB6EH+ZnZFwtONYbze0XS+cAHbvCc bvmly0Zl7YEtrp451MOUxK/p3RBjLUwKh0QrDw73Tbprphj+Uq0tv3fWgkY/QXzFO/GD3WhMZLh XW1FZQ== X-Google-Smtp-Source: AGHT+IHD/i6FPSpQnN88faaaeReMB0NIKxQa4cq8I2+dAHkcCEgAezsXvUWqj99m8a/GPGy0gS9vCw== X-Received: by 2002:a7b:ce93:0:b0:434:9c60:95a3 with SMTP id 5b1f17b1804b1-4390ef6ab3dmr63729315e9.11.1738844534796; Thu, 06 Feb 2025 04:22:14 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:14 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:21:58 +0100 Subject: [PATCH libgpiod v3 01/16] 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: <20250206-improve-docs-v3-1-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlx/3itXAtU9RhRXquHJBzi4umN2Nwm63aTV FFl0ALkZ8+JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcQAKCRARpy6gFHHX cuT/D/9UZFYtPst5iXvUeh9bR5cB+8062M6a8OVDE7vKtPmsTmmojmdCbNtoKPnvWDJUUAjNcMU O2UeKfUWx0HNKIvrZJt0voE2V8vi9Nk4WCiIcWgY9G2pZt36VENnYuNXMbQzg1pZUoCvoZ8eANH X4tBFPfeF9mJzefypKYTNex7DWpZ0Aj+oQ07vr+1OLrb5HfhEI6JrfSpHQCuIqShqN+rJshhlJs 5hZa5+NWeIPhlLymtIw9iHKbWNEf1R/8v6o7WrKrIGm1mZDb0+y90RiZ4rQUXwp6o4d2mh4hJ8C Up3ybq1T0emcBaOZSEYyRipqVOQpC0DtPLldLRouNLg3zOTMc9sXPatyOJylCH7VK8aPNxDBZbq FXAXGIt6tMijyNFpPnwnW/1MdwDyCU53Y9nDR/khw1bZ69cvrCeDQkeaSRvi8cx6u6yMEvCKsCv qTsBge3phHogiHkXfHpT5IZw/IoCO0VE6nmFjzOJyB0r3w6P8zEal9bk0N9RUdYnsPCgQe4LawR +by1JIVUEWFgppiQN6yrnAqzVOq96Yv5zsPh5rG+0pmol1W64op6zDNMhy/pvCFh7Ov7QtQ3uVP zN2BlA2z8mYAiV8tID2sD+HQEI4hnQ1gVWlXQnGE/dG6sG5L8fCRwSxMGO4mxboqczPPs2ZlDAT Z64hFseSd1m0KPw== 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 Thu Feb 6 12:21:59 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862737 Received: from mail-wm1-f52.google.com (mail-wm1-f52.google.com [209.85.128.52]) (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 AE0F422B8C4 for ; Thu, 6 Feb 2025 12:22:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844540; cv=none; b=EanlquLbdZJBziYdGkxZFbNvSr0W1gkie8WklyNiEBGEw6ltLha85vjLPzoyrAAkJNfaGclYCA74j0efnexoC9daYYImxAlCz+TSW4qXQm59kU2UzNi5iz/Tlc70GYUVVVzQxf3ddHb0yp/9YQsDo5RWcweMTgpSNCO77BY9dY0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844540; c=relaxed/simple; bh=0kbUWR2z9wlXm8RVPEQnbnh1RvUEhAz6KQpoEXpU1o0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=RjmonVmiFqbxSMbN5JekWpvK3SGO8lnk9WHZzQZ4RShvmp3ybHkU2vRbBpvhvkPN6JB2aA9QF+0Qq5LaHnSnYGenw82KR1/yuEqBE39m9cGuK8irJEKu8ks2f4k5kHSDdfSomiRLn/VrX8KfAc8aV9+JjXUNUe1QMHEE+w4IMTI= 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=BddWtKZp; arc=none smtp.client-ip=209.85.128.52 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="BddWtKZp" Received: by mail-wm1-f52.google.com with SMTP id 5b1f17b1804b1-43622267b2eso8451045e9.0 for ; Thu, 06 Feb 2025 04:22:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844536; x=1739449336; 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=BddWtKZpmCNd17BtaYia55SfeDb0zZvi7CRyyXbMaWXgvQi2UVPFYZXRrLLE+RtkI+ aCVoPR8qKpwMm1ywsJ7HnGIDVp1OCodUwF07zfcpkhyFDS5xSj7l9PI2q7QzAfFxHTc6 3MNjF09wjLB8dM+unrNkrQeimQJB9hweSPDdIim7R9adjZv58PivPRMk0TpitdXKzROL 6TXhp35ghLsM9QYIv5GokscAf6iw4fxinhZiFJX4BaH7I73ogqwoEoYI3R1qAlEDKNnE PmdpXHDQBnCt0+xNCbXZ6BsqZ69rq+W8CblYh+/eF8i6aUJE8572yQ9xbpPGkDjBUpnn P5xg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844536; x=1739449336; 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=ccmy8gnLcYIOz6hr5I3KjhbBIX0GqaCEVdT+Vj8B7EdEfNVkldg13vVHpefcb5jHGN ls+ldx6Hjtg324yaD+RGnwfv/Wi+EVHCaGG/VpO+5idqTjD+9NhpOBUl9ShqZxD2ZMX2 RZLJBW3ltc4hdEZiNuAgiiErfaDuhV3/6tKqPDRf3HYXmev+gJCFCbY16a6mrOp+VbhL bN1b2546rxW3+xXFYrvLJP5Nsmb8Po5B47vArdJActlrGRZVC8JIFZVR5G+dheAfp8r3 q4PEsEyqB1D6+FBm7NjWzlKH7PNL1nX1X8qeN0o3ARLSCRrGvs4xy3PplLw6oE9/3tUc 5aDQ== X-Forwarded-Encrypted: i=1; AJvYcCV0petwPY1xIYqUfseli2KryWVekkI1R959HN1ebUR50AiSZIevZFk+ZU6iQS7f/MDE2dkV5wFp1dUd@vger.kernel.org X-Gm-Message-State: AOJu0YzMg6SYuBABSJbNOXx2dmNcWlVOcRmkR5TE71hDKMmsoQ3j0w/E L641ZfIS1U9dn/7aqXKaggLjbPwfzjuHAnud2tUml0wCSz4mgg7qT7BXlU60kbY= X-Gm-Gg: ASbGnctuNO8nap62QNkORjtE2QlgDYnwkNLYoxljon8ZgXlZ97dZ7WvAOXlIsBF31Z8 rLbJzeXLunIbUgLEofWIxPGYsExHdvh9Ri9LMc1iQiBV4v+Ve3NjPGI9sQS2+6pWzrsetzypJx4 GvS4CZlVnt5ELmomxt9X6Sm1Bg60Z3DdHSkxnYcTsZBuGnHz2CA1o2Dkrjq407KFxIpCva0s9vI E++mtCPXxeHSiq4s/nwuhNpnfVucjTBMa9zXzgwQ123qgHydqDCWUSSHOJnGx2qcXmKHFR/l42s SNzjkA== X-Google-Smtp-Source: AGHT+IFFW7XlgXEe42kFyzSAKFYqUc4XDJfg88CbNSoG+dhklMg9g/32VuZzXglOufmkYIZbLKHlrw== X-Received: by 2002:a05:600c:5129:b0:436:f960:3428 with SMTP id 5b1f17b1804b1-4390d56c1d8mr54064255e9.29.1738844535882; Thu, 06 Feb 2025 04:22:15 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:15 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:21:59 +0100 Subject: [PATCH libgpiod v3 02/16] 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: <20250206-improve-docs-v3-2-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlxyptGPsA2Uyvfc5LaeCPD8SULtJTbzXk7f r1oKaWA//uJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcQAKCRARpy6gFHHX crJlEACTLYRt1Syn1tQFnrqUrT3VcWdFAhC0C0cRUuXIl53qJ0g2xdCSd6bfyZSo20/kuD0nVqn HAlEpsctJpVx/hjUQcq838HDLETMw/sRdRrUs6p2iYHB87c7j3AQ2H6cZ18gLWm5E4aHdnpgu8Q 7/mJ+LxdZDHBH87kYajMN1swG+gb+6A7Zcc7RcPdzePCeG8VprURRTq/UhbDMvf8YdIccIMkQDn SRdTEFzB3FgCR7jbZFDneh8R4CtfvCsq0I4dekrPqpTYIPSCYsN6cqzeGUrrcUCn8sBkCqnP/ek ggY9QG+txE8RSL+gNenSeSWqcNWqdkCxPK38QkzCOKHqOrLgexu8dMmSi3u6xFr0wzflDnoBdGO /yFUv5X843ff5OdZiPnfDSHa4Ruio0XI4Qpjx0308NuSCAVhwx4uv5rmbuOb1wXCs1r81Q9+5wM h9hzhrBpz+mjUz1tgsAq/kIBQO/hZTRStji0/E+j3rJgf4W2mz4I61pqHEsOKkuiT0PL0ULtvEF 73MfSrh0KtJgZaf24kXySZ9NWwdvNq3xaceSjJc08kfL8sefHpBVMhwebxZeI1VrCupv5eusFTF Qgq7dUCuBXzJ9jefdWZtzrGHyCR88gOgzcY/wzdEd9FAkB2Gh8XESxMKkziVg2XDQdCx+EiHAKB j13xitom3RRAKJA== 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 Thu Feb 6 12:22:00 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863423 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 9AF3422AE71 for ; Thu, 6 Feb 2025 12:22:18 +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=1738844541; cv=none; b=hecJatb3ADUlFSyJMTDxRx60WrXlcjsTTStGrbcAJuqEvaAoaBi9M7EYqw14mETWeXpSHPSBF1kl95MjsUnGPLa2O0/7flwAmzCvBYytpmRP2JWvWDB/zhBDRnlfhrEgVeQYthxEvyWUHJKTB+aYRLRZpLEYlNSeeIbwgRDmSIo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844541; c=relaxed/simple; bh=Xhx8I1RT8tRAlh1w32C6GuYPL3m92Qx4xndok+mVN0g=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=JNUqpzzSlGuEW3f7X2/P6MkD9TkPQbhUExiQzLJtcCOrzVSf2/YtmWdGSFU8RcCGOvBlX+ARPuvLQHF+nzQZ/QmwrMh9xCmL2YIBAeAX4F05WCtF0/C1mgeSomh482a40icarA/2QQPdcTx7Rqu6lFi0o1WcxVAlCF/lD+WMis8= 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=WFaAdEfJ; 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="WFaAdEfJ" Received: by mail-wm1-f42.google.com with SMTP id 5b1f17b1804b1-4363ae65100so9462585e9.0 for ; Thu, 06 Feb 2025 04:22:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844537; x=1739449337; 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=WFaAdEfJsuOpMBu6iaSGADH9HNP1/KvzjMqlslg0hHoOAaI1vrT5VpPBqsg6etAmxV ZAH0lfbEJdqbiV8lZgAqiT9qwyZ6QVJ1mHx/QH8xIQaQJtj9iJRZoqk4z3Igvp47vgI3 pJr8FlAWSH77KTO13Yv5/jRMOhf6XzHHcSjFsGY326j0qPLJBvn9SPArpeOJzRR8KLui oXgnDCGkEpIp86irv8gUxKvUU1dGrdyAndcwjeQOo0L3nOlzn3W2HqmWO6kihp0prIRs E6K0kp2oJrEGxLASawlr/2OudoaDwxcAqY9Ek+93W4YRDHDU4iVxsEH72KQY3mKLmoU8 Gbsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844537; x=1739449337; 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=Eiz2atsEn+Uv+S/NK78WzkFO2XiIB/CBqln/EdujhaCiRwUGk6lj3kSYEK/c/zNEiF OyP74GKRNbtiugln0efcLZ9ER4hVZi92Fj6wFMSxmtvVXLOxDI19tg/ZDDt43EXZVEvd 0MhqFJzOY4j9eLeAWk26uM87BSyL8Aw3p+yMYvyD8RrmPmvLKJMTPGq+JPKXav0PIkKC IH+raPv8llrHBnGGoW9oWES0G3PEciFNowgZJwjwX4ZpvijtAzN5JwDhuJDL2kDo9ZTv S2cut9WjTAQah4DcjzhYFovqaKI+DRrTFZ0vEXcBUncUjuOTsyBg+WCfi8CEimBuqnlD mirg== X-Forwarded-Encrypted: i=1; AJvYcCWV6Icn30IdxB6Me7CGLcwDt2m4pqM4AU3NRARQ/pHDL+rVWjGCUYcEERg/KMN2uKubX2TwbzCSXDE6@vger.kernel.org X-Gm-Message-State: AOJu0YyIIT1nZu3qZIZ0y/FXL7VxeWZ47sEKxt0WC4mmKruOiqMST9yf feIA/0Q7QERPG+d7e2qXAoizpFzR7A5fS9gfSmYVp3K9Zsc5shYA/vqgGDI22B6eozQstQnbtcE thCY= X-Gm-Gg: ASbGncs7D3kQyimTQZVvwxWynbDC3008I4J8wQP9/CO4OgcCw39PQ++3deiGSVhViFA scVtk1o+MWk7pYUdiuQN8ktnE0JKlQnCi/qwzmLWp4oJMoyvHkEYgL4BmbojpoJSM+F4YS6UkvR JbR0ib5fzXHbwcybfVbL8Ug3RxMOblsqYEwi8m+mYosUU4FBFBplupoG2jDnMBPNwvEd3gBjibQ hjUNKLvzI+tHBaWatk3QbnBhDPgk2uWtctXOKe8iPt0692+TVwD2KH9vFbhEPzGavsX4BnQiJs/ zyBwFg== X-Google-Smtp-Source: AGHT+IEeowtlsIxV/reCig3GgB86JfqunFCcgAp4LU7zzYfKhu6FHU67IAFksZIvUIyfccdUO7KtBQ== X-Received: by 2002:a05:600c:4f03:b0:436:2238:97f6 with SMTP id 5b1f17b1804b1-4390d42e6cbmr53142275e9.1.1738844536844; Thu, 06 Feb 2025 04:22:16 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:16 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:00 +0100 Subject: [PATCH libgpiod v3 03/16] 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: <20250206-improve-docs-v3-3-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlx5JW45M4hspetQ4+InI9DqnsmGUoqlhbKl vncJC/S3u6JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcQAKCRARpy6gFHHX crYQD/9xs8Ucu/gtnAZNYLxZO6xkQpBIyiG/EUzvy6b7QXsU/MnT2wGWPgls1+9EMtKD5SiqsGA 9dM2Xyg+l8xqy2bPi91v3He5xnKW59p97EpbSwhn5Z2WxrhMKuvn4zTzxEdDL4PWOxUQW2Op3dd kgjSSb7/JDZ/zePWuYBJQ6fJ0HoB9zkx9tA/aOLgXZSKCspmc08/z7dYIVajKzXFrypsW5u64JE IKBogWKIyu+Mi/8Gq/WPhGL1C7hCG94wKmAOCx1IiYPzUAGc8Xb47w2eTbVSD9oO4aMyADMOqOY CuaTvFvPIkacJstAb1j8SExpIIpTnQ3zYFx2a6x3DHq+ZbffwoKdQlbEO4xLPUikjJPHtnGGy9W rpWwczsevcT4FbASuwMXCqjuF88Fjs9VcS1zfNq51vsf0fQK1osRBFfCsy/pojaFKzHkEzzt61I tn72Tk0v29IrXkGXB85unz5r0s2qp1TiE73uRpV7vgTTAOKwfgkuxJrxOeq0ISUCm8hpWUVRzmY WdrAFU/PuSRvZBhq1AAE6Mo+lds/646siC5udxiARq0ZG3bOAXvm7nzz9aBC5pC9weZwZjj6B1f BEES2XiOigOgJppijVYFqXL/kVbRoTMW3wLTFQQHlJHLySIEQDhus+8jj++rGQ3L/eB+G1p2CNy MrBOkWmfHevYxhA== 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 Thu Feb 6 12:22:01 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862736 Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) (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 15EA322D4E1 for ; Thu, 6 Feb 2025 12:22:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.47 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844541; cv=none; b=atK+L3eQIpbxrqrDICVmHeKqIpySXSWZmbrnX5ujk3SAYxLmIN4jU0Rji7HzQGOcWImlMxdWS+70GJTgY3rRYMgsDiHzeWEO6R7mirkXGiRzsyOc5Yhe2KpeoNNpMOzKYawp6PMlQQth9l4mU80OiRVRDSUW21jgnQnV9hnCK1A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844541; 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=JynfCht0LX5nqpywVZei3a8Z1sicTq1ghJXTMIxGMqaqu2b1EEbwGXsquw0cdjN8oPvBCsCChxEx5/a2ZiYoUfQKrhjdsuXbmb4lmaJpokjU37tQJxGOcPgC5j1K0xtjTQOxgMQGIaDydkHkPagmasamjMIdJhGwKGM5xjpfrHo= 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=ylmppqFf; arc=none smtp.client-ip=209.85.128.47 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="ylmppqFf" Received: by mail-wm1-f47.google.com with SMTP id 5b1f17b1804b1-4361b6f9faeso4659935e9.1 for ; Thu, 06 Feb 2025 04:22:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844538; x=1739449338; 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=ylmppqFfiCArKayXuscqCsZ+r0+cTa+Z6yGJ59D5nwFZ/R9z4tSu76Ifc0ultbNyyj ZXWyLUkM4rDQzCgl45SsH+WxfkhUmdqHacM81gZ2462d1YR0A0yr/GgCybLYx7nqmFvb MEKZTcL5adAIiefoHz2CSDbOjotR531WkyBL332c5V0JX2SySddWurO8l/zf5R1AUZCP zE/tOBY0RFquwcP0oDjR7kW7DyUHauwjqrdXXw/oFil2VxTy23YQng6Ww+KEfSpxNIYM 3b/aQSBAsH14fsW5N3FSF3CZ9atYbzstqrUg+g0g8/FpyLUL4vXAYcGVAh3ZMIywhyPb 9sEw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844538; x=1739449338; 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=DhlBZ/v/5ioeioMzYTtPdikmzGE2ZDk2H/W8RTvhqNALJs5PNkD6GGNe7W6qQC36e1 bBQDqu8f8mIKnlCSPRyxs5dISrUEi69Nryb4nRQ1eFFPjtKB5wSyGKmbhJq1IyHdU4i3 FS9AxTX7G+Ki8O2JH9RBDVvj37zYUXWjbGC7TZDX9mOovSh3jqkIpopKAOddR94YJi/T 6MMIVn2dGV3fxcB7Lh+9Kx9iBzKgmqcnP7fik+lsXzLp3mQ/BPW2eo6NNVi4b6EsT73w ohju3VbZZ14y0ozts7XZUI/rEpdyUBhSt6q1ZX6ZpWgwq+str2ENhNa/CIYrrfTKwjSk 7l6Q== X-Forwarded-Encrypted: i=1; AJvYcCVbKHvm2KwLimzrv1jJYlNQq7OT1JYuG9/RhLR3oq1VDKvW7lXvO3+8fW3bi9T0yqYdevph1BsG2tXc@vger.kernel.org X-Gm-Message-State: AOJu0YwhpCoLNWIoc/jthFrGXx5DinB2+EsvayKE13uNm/rL0qcu2dPE DXU1FGOThN55ZQWR3tijKnRI1qaf+bAa113ZU3/0fm+wwmdBuDCZRZtFg4H266c= X-Gm-Gg: ASbGncvxSKInx7Sj9QHf45g7ECvze4DSSq2Ezmvxm6aN4VPq3JozdyKGU1Dti8Wb6r9 6nuWtG5kGg5NlSeQY5edGw2TGPe5Ri/bjXzSGOA3AoT0zPaapCzrqghzZclUOjdAAAP0vCAH2sa +Zc/liyTXm2IEcaTWjzzCuXvo2Zc06/a14Mct11HQ2KDH5uLf/M2g4/Mdkcl8h6EWsxVsWBPLY8 xXIJAB9LpT2iGQG7+rt6Ro70QRv3Xu8PGsJ0leuaxDmMFnditHbbX+SHRD/qL1xayvDhZyaOwHC CkUnJQ== X-Google-Smtp-Source: AGHT+IHzca4JOmSJBmaPXUfWi9XX8jR8+oBYlRCIrRQ79Nyaipf6ArzWEzvHyuJ0LwjZTQZqn9neEg== X-Received: by 2002:a05:600c:6c01:b0:436:1b77:b5aa with SMTP id 5b1f17b1804b1-43912d22565mr22043685e9.8.1738844538326; Thu, 06 Feb 2025 04:22:18 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:17 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:01 +0100 Subject: [PATCH libgpiod v3 04/16] 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: <20250206-improve-docs-v3-4-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKly610GFGad8wT8/b23A512qXV60i88jIf+H olZgl4WUw2JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcgAKCRARpy6gFHHX cokFD/44TyNpcANec+mYLed69RjfkfZy5J6iBMuEX0krWLecSxqIzjMw6uw1Ec7JN4ovedyZHCk G/v8xiDcYYopsn3yrVWUG35MAn60d+0x3Trj69Fk6U870+JpNrFyHQBBaiZU4yr5j8DBOQqs/cH iBFASPK08/XzIlS+NEkwIlmtA/VkI6WQPNMD8cZS0w1j5s+NqTkL3KB0jqVIQP6N79lPk7XlxyR IdHMzAU8ywViEC8w6fc9zAnGehzlEm1/K2kb2fSiJzy/4ysiTlDbuSbLZfO1e5MQgLTodK0AuIM fh7YfArZxjmm9onTP1RltYbNjSailehDG/p80y0LH4Exo6EouuLj61PFrkp/K8+oq0ApP4mKd+5 YLNPXHKf5kJlhWLMe6tPV/BR9xXqtwIXK4dtFRqKA5K0jraCVViZLvW8s5PdTLekl/bicuSFLvj Z+XizpZHrzpBcVFmzmdC3Pnycc2xEFgLfLxiGeW7j6MKiyTLjutMWgAHxswo8viVR1ufyrzpb67 85qP9YiQEsf4/sTwbL+cjQfxYYc/XzETKkwrKyzfWNfnLrIxMnz9YHPTr/2VfW4Ery0jNp/zi5V dt087Mas7e1m5gyNjUOioa0OK1epNLembcQ0blFVWXPQdBn33rTI/7VWfjqDzGDy/UHyDZLCSS+ szyJZ3fwA3Jeylg== 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 Thu Feb 6 12:22:02 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862735 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 3745F22D4F0 for ; Thu, 6 Feb 2025 12:22:21 +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=1738844544; cv=none; b=Uja+a6DXYTBmHFfdWsu6xbXigja2awBG9RuSCVIAaI7LasfmigwzvLySU4/iX2MQ6x9+CzlzSVj5+zo1RzeRj6VGPtV/7lD5cvFRAiAhw9hJxiFi6Z87Fyu+SL7Nryk+bmK2DtxccVKZIaI9xgTM4bGAGW6jiOtRa9Tr1umUcIU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844544; c=relaxed/simple; bh=NhCfl+Kf5EQ2UwVelToJ1q07HgJ+U6QdzNQaf1Pr7sE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=BEk4J0wfbKqKumYAS4gIGbaFm863AN13zWd8JOEUSxm8K8yib0EYTj6GFsj3ohDVOg4Ap5mUotbnk1G7aEv8RxpTbnmD+iSTeh7VKLukuxUm/aAg6rGbnqzS3bgZnGFOKdkdUM3SIP2yZ8z7FGfrObuFDq3NLYplPbuey8OFrG4= 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=QSqU5rM0; 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="QSqU5rM0" Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-43625c4a50dso5360305e9.0 for ; Thu, 06 Feb 2025 04:22:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844540; x=1739449340; 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=QSqU5rM0cTBdo5TctKOU72p1M7F3IMmamK7EhMFmlcuhv3xpyJDcJWWH+aEgH08Ff4 bjjjcvbQcS8lk0ERWofCygAlTs8RRRaoROi9miMpjSfaPitXi8LsUyGmaSr4ad4lS88p 4FluIwUFR8Z4iFvEGq7gNWiUNFudUG71kiyDr7tz07inEr+VHuV3lb3OaUs1K1qXsAot p9HcVu7UTXYO3gf7T0t3s9Qd61Ih9UAJbEHaM4CYxauGvc5g6R68B/kg2OM7xjtoD5Zu 2Xn6aUBn8qHUAkfI1D0hBnCXZPc+1GRSJFgfyPaBCWKDLn2y/e4rT2tYGPc5ugbUqPuk wV7g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844540; x=1739449340; 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=L8nDwlbNq1r8oR1vFRo5jD8GtXvP2J1dyMg8hT0vTqhqehfTj6ywWv9d5O6OoLJaa4 cZ01/Lw04oventNk2smfzjEU0h3EdqYaWyFTlh70BK8AfUcOEkxxlBn0EglufYwDTV4D nw6sOWKIWq/jbDA4vIfc+noV10QOlSfnOXeUsVbA7eHol/FQlVERevGIZqrhvy3fVT9L K/bsK9qAFN3J4TmJ7hSKb0aOrJC9ZOQ58TcRu2NDz3aAvzixJT/8Tr2GwjfR2Dm4TSgW dDZ04RLWKK+r5il03iV4yirIKpHxshkRzijCo8EE84aZzs+/OuGbsLMC5ugaAGZhV/Px hNQQ== X-Forwarded-Encrypted: i=1; AJvYcCVaNUl3LyDm1kBd244S1syyIc5CwAbAimB+CxOB9cfbIvxl8ByLYURHIflKqKOgwKsQq+Sl2sexfcz1@vger.kernel.org X-Gm-Message-State: AOJu0Yz3CBvhFJmozxFOQPya59jayBgMEV2LIo2YtxNoU4N+OS7bhJ1e Xfu6QKFnpHuN7MCnv99cfpjfSHFnxtL4RHrkd8TNPl+cjVYDtPrrnTm/H4uTCdw= X-Gm-Gg: ASbGnct7idIbp18OpaH9H72FD9AFvbQkeVXGFGyNf0niizfQ7DqUVlrHIrbxiXdi4pm yahXHqTtZwXEA1E+K3oGGxzG3BatiHWJ2+RPvnLnouTPr5F4quH7ipIJNQFGDmUZRN+Z6OEdtN+ qo9Tih9w2TgIvxUWrI5M9EDMxfWEhrGVpdZbM5qyz/w900zZeTa0RSK7P5BTmZEVeLYElKaePPh 6Ib1vSyFPx8fnVZ+1SA5bBDYMIwEKQNNeO92we0/KgcD6He4PvmQYyHHhXzXXqPIXHssExAwZZM 1hIT8A== X-Google-Smtp-Source: AGHT+IFVrgW7M/Bp6vaCcU6VMr/fVkTgOefFFGZY/dcvZovk80jpgvBmbXnVUiXJKCH9k/kTPzl2cQ== X-Received: by 2002:a05:600c:45d2:b0:434:e2ea:fc94 with SMTP id 5b1f17b1804b1-4390d4360cbmr68166635e9.11.1738844539733; Thu, 06 Feb 2025 04:22:19 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:18 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:02 +0100 Subject: [PATCH libgpiod v3 05/16] 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: <20250206-improve-docs-v3-5-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlyeMNUzETV2gmoXt7gFdB7Xsg0c6bLjUZNB dFslbOoiT+JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcgAKCRARpy6gFHHX cpPLD/9PTBw0+0Zf7pMfKWk+YJMZcnmgtl52s5DNi9+ftSKpKgpK8sQhLv3iZ+6gudJyHLo98xu RKfCKB1i9JOQTgzgc2A/Kj3EimVIvjsTE4s4mq7b+Uhw/mugE1bNf/Kje4o5sIcx5N5RBvILgwH OBDBmAORHQtWm0VIAE2z2vwMfFJApZMnFnnzTtmNyZjjR3R5yvFsprKVzMOvQp+ltJrNwALehMU NNvb1M0nY8t40ChJTw1/l/0XxLYB5sNKDllHoqVN7zuSMwtERh8ygW71Vdv3k8f4bhJ6ThstMmM 0KVYHGmMF/R7UoTGJdvJOJ7twH2+miPJmTOpgxJeSMSOJxhwSyS2EbOxEMUw42udiaCih1zNxH3 Yd1hXJUNo9HI3cLNlggtcep52sA54K3fmLDSMTp9LN0u+SDR9U4LpNHoyMr/j1KNDhsGgHLioh4 BeQvgLrkgGrl91nI0W5+i8G89NFwjYKbP27JbOZoyMSIAx9S/LYnGQ7ddwcqphoR1O+SdG2oaw4 iikwBE6c5rggg/3pGAp5lx9XR/1k84Rb3f01d/tXk6uuzNHWBGc5zSdZdqRfC1FDxYtcOGYr3fR /2mgQgzPDgNj1m8bN/A/BpoYrUnp8+UvHCMRJy9WKoOiaVZTN55AkKOPZ14z33CNojoPZvZsetU 15kcmjYyilvqM8A== 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 Thu Feb 6 12:22:03 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863422 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 35DCD22D4E1 for ; Thu, 6 Feb 2025 12:22:22 +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=1738844543; cv=none; b=U/OKE6RG0S2Y30kESUkbhy+ichewhc9aD0AvVXsK2WYELKUr0Vk9oZz5G4ullM04fzPsMF+FT6OVxLRq14x40RL5vWsKd4xVmkb7i6dumSsTuQmSy1RK1smJWszhbvHxU32mDx7Wr9rT5SoF28NU0uaWqZvYIS03dB4FJSS+kC0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844543; 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=pkQ4xW8z1Re2ZqU2R6SFWmI1UkTkVH/d8934YZFklkFyuIaMpiqaCQ/5n0/S9K4tphYlPLwj6GI6nvunQauYE7tjo4+o4utIsQzZneNvj8g0FAR2xP58AdWG1KxhT4s5Q4R3zr8c8hRnsDI56wzvCmy4D78r05tGTn28voOVGWM= 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=gjqZnT6B; 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="gjqZnT6B" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-436281c8a38so5539925e9.3 for ; Thu, 06 Feb 2025 04:22:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844540; x=1739449340; 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=gjqZnT6B6hSzhPTH7Q4uQ6ioxtbmlTlWvPnuCRw1TBicqwsW6utrsNol4aAibBP15Z vH8m3d7l+y31uu+5JUGEnWFazLXPBcbaXLYXmPKmLAXdf77qSZUXwRPFxQASEtnvNBf8 f6yybgawRmiqzd4SUUchNTnTtz2/phbkJ2UAxfCJlf9QjBghf4DKPWCryDWPz5Qo8YO8 vZFvmDXk4qs50fV2tBPue74R7G1mOHHMsjdzfGHW7+XVDG413Q7CAT6yE7KQQ25NbfBu 42gHCE3mBMNwn78fb910KPWRMziND2nr7KahT89MJjbTEQI3mDTuNV44iocaqAf66F8a dhqg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844540; x=1739449340; 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=MtdIiQaogqAgqmEti7LNkybdDflbS6qDh0NhZeLml7jOUN6OY8bPVjCDgQFnuywIgH AN1RHg6N2NzWfWQZexa40YkRy3Te0VGG0bOce+srxL3pr7XYXdsq9oGp/C07vj0gJ7Ph nxM8KKGWKpof7iXUxj/FUoS1kqCBK7UL4qzrRM8uqDRRe73WFvr28HdHNVJ/v+8AtiaT +qxj72V8lNVfmr1atZfkGqByJr455KAYce+tpnXVMkadcH8zBjUGrLbaw5h9glVVtvr6 A553KG1mOeWfJ1x6f0UnWfOZfKZP9JA+YiQMJKd2CjrzGzTu0moM71/cMt2gjXCwJvYu AfTQ== X-Forwarded-Encrypted: i=1; AJvYcCUGuZqYod+ebQx+xoGfGiMxDRHNeRjBHT3Fl9JsMlC6jH5IioRVHufLBJX8ulWqENy6/6ME5TntmVVy@vger.kernel.org X-Gm-Message-State: AOJu0YzjEfdjq3mo3hY7eoA+AI/8jpUET/rVKgTw02PjHfLBxVPT7Lsr rq5tMWPXzAgtVBh/z0CTEIcbvZqxY6nt1lNPAxSaMflY+wydTbr6Z9+2a6UuliM= X-Gm-Gg: ASbGncuSly/zf1SuBEDMUelTC7/AqOSSpki+f/soYbMuIORIQXefZs5JAySEHUGgTw0 DHZzN8Co+58r5BEeg0vsDdShP+Tzva9WsiH314bDO+ljtjYk6nKD/qe9CUdw4Wy23jFJ5mL4ZoA XXX+Be8/lV3N09A9f2YhpgWaSbh9M+1q2zNNeW72/+3NHpGAYtbGLK7RZvyrrPsUKc7Ek6MUeVS OfgRqaQMTZ8+kwb/rnJicAMEUFnZPsENRKN4nauZ8kL6un3iyTNRgnS09EfdVg+YzBE17pFxY+A yH6tTQ== X-Google-Smtp-Source: AGHT+IFt2sXTId+sDdmqiODOQ4lfYFAcZV/J+RIsBBKuHGrOww3a1NncB9GOIJyLmgNjM90nVWVk3g== X-Received: by 2002:a05:600c:1e02:b0:434:faa9:5266 with SMTP id 5b1f17b1804b1-4390d43d1bfmr53802535e9.13.1738844540561; Thu, 06 Feb 2025 04:22:20 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:20 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:03 +0100 Subject: [PATCH libgpiod v3 06/16] 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: <20250206-improve-docs-v3-6-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlyWaJylLuwUtSpKyBddEkCH3auBBrpxWxXa eS89Cbn/WmJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcgAKCRARpy6gFHHX cgopEACcm6vorKRY0025340FihqZQ1XCsnV+IDYeXPwpaCfovCkBISnnPSG36f8yEH1/Mrx07Uo PJIj31eSCqP1l9HimyMf4NQOVRetb9YKUWWvq9hQk8lYJ5N60YIJZUqDTm9dPyD77td3cHaW4ub MMc6qCNHQTzeNfra7StyLPgjkkq5IzYqBQn/U/ve/+Icczoe7+0xWDvAv6NtCL/kryLNvybHoCm 2J8gwusBd/L3sExlG64kUs0KoGBlilgel7EW8bGQVxA1hJ6Ft4ciRjQO0iY73GoVP74b0SGsR+G rHnw/rcQs6/bPIVIE6gk+LSNAd59EDT1MgP5LNiqUkFHaMVtzayTjD/4r5qYxkU5yRx5xwHTDOC vfeROzqKvqMCF0SVA5qNOeAFjlcK0v6y+I1RKOhLF4F5NqjK1DHl51bAVvZPTiWoNY8ZUV7vSfx /616c67hlZCkJXzNyLNvpc1lTaDU6xjSWhscKFVbwuaV5mQcQxrmm9Ubw5P3b84AaeYLGHjV1iK gxkwvlj3uvCBXZpdP+0YDDhTlSibMcsMcnFcO3SBKi3/apiLG70L5OztKYFbEOPT2LUBwYOlgzz hOAbUqkZNw4lPz/e9Ou55HAMgZ5+Bd4KGD/z4y3Qww0E62L0l7fezE/9arezAD71/F33S/UeT3e t8gN3GUvQzpJ1HQ== 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 Thu Feb 6 12:22:04 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863421 Received: from mail-wm1-f49.google.com (mail-wm1-f49.google.com [209.85.128.49]) (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 78C0E22D4F2 for ; Thu, 6 Feb 2025 12:22:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844545; cv=none; b=XjYqdbVnYqEDuZFsY2Pxk7MOUa6Y7+ngU6hBPXc5U8n6SHALljv1l4GPyq8AwLNN1G77G5AAdlFqb7wMulyPtuJmN3RfQ3+qE4/wqixKnn9+1bsOYg41Nt4naBND7W18jdS+WTHF5IHEBkGdkwESjNss8mQh2YkyAiceL9FVF6g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844545; c=relaxed/simple; bh=WB7fTYVpBhCtObrR7qdfc3t8+TkfB83AoOsP88xUS08=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=iW8RnPAkrO7QFV7p+zc+ca+4TepjO0U+wPJGriKX2oXWdOMKQCRc59HCFtiiylh3nf/1rT09A8CjdhIsbIRUsWDpQQfYaL92CTkyPVfUq8veSNDlHL3+H1Mw6S7fsJgxVK9udzRfMIi5Ip055xOBTcbKljnxE2iNoqBiOGEnlng= 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=htD1q8DI; arc=none smtp.client-ip=209.85.128.49 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="htD1q8DI" Received: by mail-wm1-f49.google.com with SMTP id 5b1f17b1804b1-43634b570c1so5719645e9.0 for ; Thu, 06 Feb 2025 04:22:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844542; x=1739449342; 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=htD1q8DIhixy+PKXspxc5l8R2W6b5BaN5KsRXFyjT8RydBb6pd7/DXBhR7ejywJcX3 MyO7B8zm4zOzM0f7lKFd/Do+SdObciLNNpBq5eRtCOOMGFwI0tETuMewVrr3qPm64Zre vkLi3GYNJkTqyU2LQmBeLoDWqXtlgsf5WgLuxcJVPphNlqNNaUtekO/8hf6SGOEqXjqM WinJAiCuJec9Hy6bccFXxFkwsXVXIherE3SS9Gmaxb8PP16/ddTqJyfI5lxZRCJkBySM Buggp/Ex74S0uKRDrQW3EiUj5lAN387bJHLXIHpkdJbPrlBnkISITFVclpCyBkkqIXB1 9UQA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844542; x=1739449342; 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=VrIzlMxsUHAl7bhqW/dayksictBslwKtXVw6T6Zc9aMatEpUbSKb7rfxxkfjJscnA2 OHzkD+Qv6o0ZdyeIOh8YbvNuS7n7eIHfDJKEKnUyCI/vDkl8jG4Oy/lVgpL4h2EE+Vrj K2HRLxzoqf7I8qRNMTW8Kig3IoMi7AZGxrhGYy0FQqFlzgy7EuL75Rm2J+gVPo0ppFm1 IZ3KcqmqxJStusWysUgJnm8tEOllTqVfxPv0W/iDyepp33F0puklRO3ufy8bLG/EvQMz 1UAoecOYMkmpyyoeCD0OYX48hn86aQOob4zWKD6eXHU1fC+DsVSUP4PnOYRNC8txpGFT QmTA== X-Forwarded-Encrypted: i=1; AJvYcCUNMXiW7uiRy/guQXByOAYIDVNG+0K4/A7xfahtfImz3KGzSPHAB+HE013drL+C1LQESaKIckaP5Fk+@vger.kernel.org X-Gm-Message-State: AOJu0YwD0EMGX8RTxgYnU1nPdn2wS7/og+yHoHJOJX7D2wp1tQ0fZS2j 8Rps/X8iQaTSz4bXXXNf/sY7a1iYcPJ5uYTa4V/lHDoNteXDOqOTfgeyT4RLqkQ= X-Gm-Gg: ASbGnctfuma8675QaoViVo4wPCMS54HVbtKrHeT+u1oeTQFIk+WM5HMPQ0jvxtayUo4 7aTIRtOSPFwQdLcnfzNwLKLJ7kC+/3VLMcBF41EtY8w2+tvgdZgU2jfyRNi6cQMLakOrDtmaae7 RQSdtO6rB0jaOKRaeP3BYMmcy8f+wmM/lwbDHzD65rWZVScMbVKFlOCVpZI3+erUTwMsrx5ruLA /hLRmFWeMGc+t+LDQSz3+QUiUZfkl/9V3lrqXd7LrL9vnoSjJ2c2Opl+OUMAgIJAWAjjgVumi8g O7i6Ig== X-Google-Smtp-Source: AGHT+IHU4e9j9Ou32yJRqVxT3xxqD6bnT5z+/0labmdZ+UtwE06oWmz+7ieL818aTi7bv+f/blIEag== X-Received: by 2002:a05:600c:310b:b0:434:eb86:aeca with SMTP id 5b1f17b1804b1-4390d43401bmr57028615e9.10.1738844541641; Thu, 06 Feb 2025 04:22:21 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:20 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:04 +0100 Subject: [PATCH libgpiod v3 07/16] 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: <20250206-improve-docs-v3-7-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlyr9dywyY2++x3efiBMMqf/6i1xNYSP4wkL 5eqwEfAn2SJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcgAKCRARpy6gFHHX ct5qEADgIn02cxtTzoC8AQ5sbUlHfvNc9ko9bMk7+QxxDJ5zwpTmyqdCdyZVCAFo9hBr3aUKkih d20eW194mEsSlrMP9hOKtjNABQImoPn8xzPzu1KCHQx1TNNYaM8Ls1/yv0ajwuQqViUAoBoLjT2 UZbyg3IpjxG5z5DwaKCWTJBk41UsoBWIwcTtetoymUqT8tPNuAJIav/ig3XeT8SGAKBXRrGlHnS eVDzVB5+bNjY/D5wEYJoEoqma3FG8Z5UkrQ0AaZvHwdf/pauzpWT1A0YbpVw4P2Yg0jbF2bhNop VvD+a0UdJwJg5rfYQkflUeqTMf4XTQL0i/iaYP2ol3AaiAUuQPui4TfQbLyfza3O7Ym+wAHspUH 9uCnRBNMOpxErWiQ2RyJMet+83SvGbxL9jWGISj2f9DCnInuiFsOH00deb0bO00qp70KOA37OBv cq+9kmzMMjSLqMACV0NNcy4F7JvzG7i1topWVFQTJOGpvQIvoOMBoNNPe7Pv0nBdnUtnaIFGlRh ipP9O7c69vUohPWpCoEnYcd8bWCcCNmbdnfKpIaU7hukCoiG6tvxKldaUi0OPc5IaPCl9djzg/s xQoJj09gKZPYBBHWMEKNcTbYI2R7P4/rq10SwFCEfBBfNvKD8yTzg8jk5MbBTEyZdrEt3aT4JKf Owy3F8xkCwszH/A== 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 Thu Feb 6 12:22:05 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862734 Received: from mail-wr1-f45.google.com (mail-wr1-f45.google.com [209.85.221.45]) (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 8C81F22D4F0 for ; Thu, 6 Feb 2025 12:22:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844546; cv=none; b=o9EgKrJ9JiHP7S/UbiAT7PXwi2gOr/BbGM3RuBkynjtCWzKKOr943UT+nIs8ZQ94uWQOoeswL4vzyWkcGfkf+6/5IQpDgi3N273c9vGkN/AtmJ2/4vq9RDUkglR4GTHgHv6m41lIYzaS8pmdHTVhiU8RRGWYohXNYq3wqm26zT4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844546; c=relaxed/simple; bh=YlPGh4pmtCOE7xtDJOAWZkfON+rqq1FB9jCLbTzmsKs=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=JFbAxSpQu7I3OG6EIZ/kSFmTNdUNFbBj2eu5uQeCYrAFzJA7Y6ODNBjwMe+UT6aUindfrNDnwfWTdDX37tZEaR9Ipr7r0K9w8DpRo0QuWXXPNXhoyZ9MRLcuwxU15yDbv1h2DBWqYDCnHDVenxcMz8nGm5NhrIOIUCqReHM/ngw= 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=vf9nOdLF; arc=none smtp.client-ip=209.85.221.45 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="vf9nOdLF" Received: by mail-wr1-f45.google.com with SMTP id ffacd0b85a97d-38db909acc9so590836f8f.0 for ; Thu, 06 Feb 2025 04:22:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844543; x=1739449343; 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=vf9nOdLFKy8rTTimBHbERDYVo0wK/UE734WSQOrHc7uMDASMmuMijZSBVb50r2Z+hE o6yDZSvaqQRr+TswOp/CiLnQenmEqrRQ0UQ7ivUJrWYyNuN1dKB7GXTCnXMx4obTJApC thM01qhsHycGc2FZfGQEclzcMuNwoqGoA3YXrFZSrt48j4nKxhXVB/Bo3oxH5JkQg5+g 1WcF4J9JTOgR8TwfpmE7y5sfn7V5V1SdKzdzvt0I5bWiuJ+QHTVzGZJfbElev4hOXnDE 1PPqyX/DpuaEjrEW+kMW8GCizUN0bbzrm1NrSpqoX9BlrAIkiOddDklkbcoB0T30TJ9a p7NQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844543; x=1739449343; 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=GJJQvm/lhnpm8BVgm9jOCxeHHPNJZ6AvGtZPQzrsIwI9HsK//yHCNh4Z+iZHEx0EXR 34T5vSn1fkA5FbEFFWZ56S/SLSUnfHV1i+24guos2D01yyChKAkSdjF2V+5peTfGIyBJ mKqIM4KBJWX97hIF+onoPQVvO98heF4YKTE4+uL+vvfxx6x6FiI7o+i77HjhbhsygEpx lksaG9xGe6CsJA76oxsdoC4wzOR8EkzLQEeYCFXwxnSKTyYQQXDfFCWWR7EGdqj8EFny h/dZQf45cILoiL8ewMJ3EOOMuZIGsnF8pNn54UbZ04taZ/7l1ZpaN9V+ONBxP+YRGvgi PjCg== X-Forwarded-Encrypted: i=1; AJvYcCUno/qbJFD76JUv/vJy+Fies8dkgFgGOkUk+TZrn+YcI6vrztMmJ2hkYvuNn9Bi+h5MSQShdY02fme7@vger.kernel.org X-Gm-Message-State: AOJu0Yxdfb/AmEV8UL0Et6wPhy/HHGujN9nwxQ8UAEWSzzZii/xCmYGs jE1AMqolZekKrHxQ0Dpm2evx2yLwbTQbdhJZ0oxMGnRLmiTLtSgp7KLezaG52WQ= X-Gm-Gg: ASbGnctqiluxCphDRx7oGJK2HNMaSXC2pr5T3XVQgGA/nGViQZqnANJWvPlxZSwOicU oVwuJkVzSfuM3trPlS+2jaTU79l4gHL0gQk+RrE6yAa3lg/DimMM/i66ABK4mar5jAkvQblIi74 jIwifow9z32v0cBM/yuBSBiRmavhRCWlTpWbBhiSv3ZsKCr/fYzJvoOfXF87JBusWImhO1tztYB VRnJS4fY0eEfeDzv9yfmZeUy6MacihZeVjA9ExfWiOx21Ze5tleH8CIxDXs2BUM5YdLaOpFjLgN +iVYCg== X-Google-Smtp-Source: AGHT+IFvsvMKBfxHRzcqZ/ayXsoPsc+ctQ3ORl+O7IinL+vgD3xFq8YvN076qV0UhVHgmW+n/6z61g== X-Received: by 2002:a5d:64af:0:b0:38a:88bc:bae4 with SMTP id ffacd0b85a97d-38db48bdae1mr5006501f8f.18.1738844542624; Thu, 06 Feb 2025 04:22:22 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:22 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:05 +0100 Subject: [PATCH libgpiod v3 08/16] 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: <20250206-improve-docs-v3-8-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlys/p5RhROCQKCQEoDXM3eahMHNsIAZTxcH 5NT0tIpnAKJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcgAKCRARpy6gFHHX ctD0EADf6pkpBiLFgfTQXDlve0xtdYoetn0XaOnGVvZ1kpezDSpuV11nrO4ksvzf+g+pbzkGqA9 I9+3Qy1zeS+kFK847EqxlRJigZ7u0Zd220ZAOs5Qr/I3AZ6xKvb4Vd1fXfHrBfqdrsfHz76914i ark3GIp9H6FyQA1S4+w8u014NbQ1aooNcE3xk3oCxK0JpYxpa43QSGndrS3SALchaC2w3zWgrAO 61Rl4MqkcTUjLQ72TU0UKwbYPV8lw6PgqoNekYaBNpG41UStJbnXFiSYspq6ORuGBlwpxTBwCbV vBjYBUc/yBH4Koyf0fqfj88T8NVf8lyApfWZ0yX1dyXGeauwZD5uKXJTikeP7/b7mCQUKPL457N DQzDU77lLVUH/MPnTA3sfcsnbFkzjWTPhtAmS0XJprY/jLnPSFXXqNaLbDslHsRLEThFN8TQhVS T5lFzx/D8aAN20jzAyfwgs6JPHbqNSJQKxSGWyd1cJvB+DqKpyDww0hwOPe2gysO5H4iHuoZtQi Qtsqukh0w4WsZ0j16oMcdcCkfX5nQTYxwjVAPm80+VC/Ux5sL6kK2xQnOdCCNxHmjdD30Zhjbz6 mPDZWHpSzmHlw6D3gopuNgL0/yhOmmzPu+EsAzvdaEQAl11wVFMbCJcmfEceNRM++dXnjo8qhj6 7h3g4mn89Y6vchg== 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 Thu Feb 6 12:22:06 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863420 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 5D75222DF89 for ; Thu, 6 Feb 2025 12:22:25 +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=1738844547; cv=none; b=WeNsFneqg4HwJCgbNC+LU4ZiZd+ppZ4xcPRsRhJjUvUHOpteiefdmC+MD3zjFVHuSnVRkmo2FgQB+4TTIah4aynZVzOeMOnaAhW3M6G3KArT6BaGt+NLYuyJ7e+k6dj8QrkY6roXKmqBgA8DdE0rSNMWHiWDTjfswu7VDZLIqng= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844547; 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=eGsyhGJTAu8j2KG08hizbouPXjWm3YCCxPO/AkXG8LgAQUHrlXfdfBxv8rZysfxYP/4dRv2h3iUONblZkEnHcOQ7aD+3Ga2vO41C7qlR94FaV6z/e9neRQbbVlcf/GOxyt3wJOVDjIPPpdJ6OFqX1nQWOmQ9/NjQugLOqakdsL0= 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=M4gTKgW8; 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="M4gTKgW8" Received: by mail-wm1-f41.google.com with SMTP id 5b1f17b1804b1-4361c705434so5691695e9.3 for ; Thu, 06 Feb 2025 04:22:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844544; x=1739449344; 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=M4gTKgW8IPwIoq7gPDV/WX0p2qABjJto7o0Qm4aJ288o9wIghk8YKlkQFqfQPDn6vh Sq1Am9x2b38LUCqD8+/eVbPVdI+tLMdKZKER5jZftuioMCF8fJ9nZdG7yNbmXetOpkX1 CO40LKe9Cwi7pwAyamncr/w6VbV79BkHkNzS1D2V6Rxv1YWyRb/zQzOFEnQVP3IjHeJv c5BpGCX/Z3P94yJ7MRptoSrPaPN7LcTFeYXvL1h42dscuZo/GVU5bFG6uN3w1RIUMTyu f/famR1YPt9v62oErd5bqf6wgqvwRK801FAoHVIacJpaaCBLDrHUZANNtMtvXul+W1Rh kBtQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844544; x=1739449344; 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=TFbLBi93pJqOAtx7wFl7Iy6OXpvpoLgdQvZQ6tYf6/oqwgkU1PoFwbtFl0ZxoM3Rbg 6AjoY+POzda2VIWyJUc4ibpwPQNojEnkI4J62iQlcydoJeQwKHZyYInvi9H0FvyVkz8N u+dARzt58G9zEK7J3SA8Q8xbrUaP8vgzMgsZ1JwyezRRchTMSKJrN8ugMvcxb22pBAqe z4eaJyll6xnFuHc95e5GGhl52+Er494dElZot/BeeYguVhTuFVB1PTHMVG1ZTvTR0f5y 35NlfKGqxfw69a99mqLlbaoze9yzTvCzV5tAl5yXk+8q7TcKiL2Tx4e9lEcWsi66JFTa m5sQ== X-Forwarded-Encrypted: i=1; AJvYcCVSpygEkyLt421wkrgYb2gxr7ssOkSSRQcD9tThInXTk6oZji3p+UAO8/KLgs7OYcV7Bu0l6r+jGoJj@vger.kernel.org X-Gm-Message-State: AOJu0YySRWS1lTjxKtlz8TMhZqo+EbegX20l+LH8MjlBpUVQ4Fc/T6Br mnZV9IqJV/10Nud2OzfcVOdYel5N1Ymx7FUqI6PTwxb7GHm+tXAwNHPH/6A9qtY= X-Gm-Gg: ASbGncucXk0Qoy9tnbv5bo3Bv0G+83M2RoY8/X4A3HslTvgs3W8upBtPW4WfbdHY23z eE3+H+wthDHfMLNSVnZjgo1K/HVnQPxUjBxdrNvvRvGCtnjnHG//GficClnhdToNuLd8dEDURMA 0jf/bUejxZpHyqbvH7rLn665dySH3HzudEobJ0jsC+3W/eOt8GmN59EneCEm+p9//Hhy9fQMQDB yJOsQELw3EnXZbbAkIQxZgJNpH5vyNqxyQ58Y1f7rRaH6RPouGif0yX/YqMmVb42LaFLWeo0Sht iUsqOA== X-Google-Smtp-Source: AGHT+IHfJVHXcnfMqPnZKHXlcFb2MFK/pjnfr5tt0Za/lefI5nSX7qAKRVp1lWgUuLdapE8PeyzLlQ== X-Received: by 2002:a05:600c:4253:b0:431:55c1:f440 with SMTP id 5b1f17b1804b1-4391466908emr20315405e9.30.1738844543748; Thu, 06 Feb 2025 04:22:23 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:23 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:06 +0100 Subject: [PATCH libgpiod v3 09/16] 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: <20250206-improve-docs-v3-9-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlzgGZl3VuPRbMxkTY+qJPRQZUEFOUroKmu+ eloDGzLUIiJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcwAKCRARpy6gFHHX ckUBEACHqaPoY5Rk9F8XDVXD9bNdN2EqbP8F2MiorSs25jTXpugwx+dPmxDa1/b4kvfIZpD0DpI Uuay/LVMsOlWm+DdGqaqOpr0RrvXA9FXEH7Yg87RNuCeR80IZgHtHCyzb8I8mRyqg9YuYOoC/yY ldXhVcyRyr2KIKElAoIbPCJpHPmphK4JlLjVFr7EvCQwjb28MCAf40OdSpkO5+faC9m9HU8j+pt OTEwS89pidqHQShyjwZLNa2OmnEAoTsHdSHUjXJyPJybYtxbvzD8RvpchstT84OBuSx/Bnx1z67 D5nUA70frx/fSOjXVda6UrBmhVXOLczjnaevuEOjw/z9R81x94vZj7iTT1KEyNMbipH9KmtKEKN /5Oxgq/L/W4WmJCoE0cilNotbJPXrihn45aQX8RelL50B/1VPmbqaOitRcfCFHG+Ax5jHA67Arv DAr071vWD/jpsFADAraY10av5JL27Eemnfr8zW/BvrLIjLpkIctiO/1tJCxLn52YZgMBXKsdWMk CGWbLn8nI+ZRd8oiWCfEsVxPNF4tiCYrwFa0g76cAj1JCzU2z9Xr5hYwQcjDlNgPftSjyWSkS1r nj6we8Q6ZnnGxzVrRdl+kS1zrSvz+Rr+Te3/jpqCN+6naNbZTmlX8/AR9T0STsgzegmTyE0JckK AyBcYT+AolPdJXw== 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 Thu Feb 6 12:22:07 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862733 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 6EB4922D4E5 for ; Thu, 6 Feb 2025 12:22:26 +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=1738844548; cv=none; b=KQ9849hPP0xrg23q2duZH8PNR0fJdou8A1jGB/VAqEzrN3LoCWQIMUBAQxGlfIH3tF8QhzR3NZw5XRvmt/UCDT4PgoYv7DCs7XL7EbsTtRyzRcYkK80+9jOs3PvMR3ef/3kCYvlz0ZulOfV1oVTlsLUiF2wJvkSWLX2qPdv2HRI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844548; c=relaxed/simple; bh=vsC0ALtmeFLUJid3v92trM8BakrNODQ+xcARW6L4VGM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=m8A91/gTLxckoYGHp3PQQE8+btxC7pMyyUVZiWNbqtlxesGUiCR3I9KoKa9eLoxisPA8MIXpflTe57eI798ObBK8dAES6sRbS8g5dma+oRYmMsONKsssCskBTa19ndDFgbIyhmcFlnkLnTGFq0Hky1B9Oa7WB04V6FuxVTo02XM= 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=t6fprTc3; 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="t6fprTc3" Received: by mail-wm1-f54.google.com with SMTP id 5b1f17b1804b1-436202dd730so5554155e9.2 for ; Thu, 06 Feb 2025 04:22:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844545; x=1739449345; 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=t6fprTc3/Jyw11HRRPLD6AvwQGc+d0bmfm28taEms2pehMbADr3698npley9A8ISAk eDo4Am40IwvKeMDRANSm3ZhsfGsxOfTer7bnEfGUxHZ7UxuXrTHeiN+/caj9SgoHo72J P6FcKeAw8lHC10KL6uU36WYkQbWZ5mieLs9hYGsPzJiml9ultrPwcHgkafGXV7wppbqF ScjP+YTQnTh9NGXsupRAZf4Q5N4kJfnE8MOpeN6sI+duZBP6HPy/sFVrZxCSlAx0eaNb JS/aa6d4dKe/TjJnTeaMUWc+oU9CPl4O2Sn5CNJH49OWV3KpP3KjgncKqnAV9S99hJ4K i7hA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844545; x=1739449345; 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=tNaadanJo/yye84YJZOV5S2MWYx938TnQmeAC0j9kLO6rh8kiFbax+U3yVNW/PI0HN CKGi9stzVBl5N+omIKxTrT35Gfn1KjOJJklCebnQlDWZke3iuMCK3w3M6vIHS4gkdlYe a2na3V2YP5RuglI3BvsuVpi18ErXpzWXOwe4YZf1zgLLGbULyREa/12GqBfnzYBon7R2 5KRsmWoGge371OTcnckf3JlA9AlDnmRkWhVYTmXVCWLAZ8ImY+ILxHkr2+GwyjgAVdo8 pTdEOJqo9yviIvyajj4BLs76Ehh3pOvHdLL2yJDy57eJlEpfYJIOrKlMI/mo2bZOXtnJ rIJA== X-Forwarded-Encrypted: i=1; AJvYcCVHaISIjRc/2ZNY7VGJAR28jZczy1B83PQPDwANuOZgu88RyLSGcZEerkbz8THVNRCgiCsjZaJM4yOY@vger.kernel.org X-Gm-Message-State: AOJu0Yx8PiLPvP8IFNqCzjezTl+3wUAAgXx5wZJAOf0cUkC9jF3CY8+I VSiWGYNPlGT+4b55Tisdpy6r6laTxmTsIR0Rf9aEYv17URToR8lirP8Q3hji1xs= X-Gm-Gg: ASbGncuGeXBoMFgcQX28Wt0ByWKGRLTM4rApo8yX6FWym13vS0SO4Bi5wxa3dP/D8VA ECEHRbMT7wHAU/G1UaWLex7bIrX2PyzlXtVGiR6I+8LBke+1jOf/SZ2mjOx+7iaWMM807yTUnu+ iR5nI2AsT1qq7eS5G9SYWpr54xpDtW7HgbxOm+bJXd9vqB/8icLiWHZ+Cdqyi3lh+2JBNTdEaPr DKFm/zwIzN++LDtSPhjMEAcs2abgYO3oaTCAATylxm0FzeOqu/Qju7iwrO1Z+Wz3CVKcg0uinWi iKPA1A== X-Google-Smtp-Source: AGHT+IGiVQd0qFmQVsVXz6h3k6onPKVCJXuA9UuIiZxpcL7v79TaU5m485BNF53X3sFzBwRCxX3veg== X-Received: by 2002:a05:600c:4444:b0:431:547e:81d0 with SMTP id 5b1f17b1804b1-4390d4340e7mr70085515e9.11.1738844544707; Thu, 06 Feb 2025 04:22:24 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:24 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:07 +0100 Subject: [PATCH libgpiod v3 10/16] 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: <20250206-improve-docs-v3-10-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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/ZANAwAKARGnLqAUcddyAcsmYgBnpKlziqIQ8R27vKLgPxgVm3pswdSbvQARh43lM 1IQvvHUagyJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcwAKCRARpy6gFHHX crRoD/0Vcr6oXl1HyXLlBkuVBbfCcQnTUR+q04rN2GkQQhTtKLK/ttjsPlKr2hMgxNmbF4W4UDd WNYpraK864rccIzyP6dz5T7gNYFeNIfTRV0yuQCmz4US0v5+1oIefXy/eWyLZ/TqiSC8aG8eMeq y3BTSeAfrkok5l9zd2A/+4SeMyYseLnf5A1kSRX+agoBX6c4pYgxTyWlONPjM4TX/I4OhR/BU4g QkU/v23LYv4vJvBF5ntBO2CYM/adQnLeXqFaKwZH4kAHAevvGNSwxSbXCWTveguQrnDMNqun1Ji aieqKvJEkjyGTAT6sisT2SSquU0H5cqkwtFMoqZHH9xhlFg2p1aRNG3/Qw5Vrouw0CxUpZrPA0W B7X61PB20t7IDww6nncjDBqzb4UzvQeL9wvmVPj8ngzvPvh4mBLRWl7jueJVXEQGAlMWtl5QhOk YGQXWWIRLm2akduHXTfJdM00jGPToYomFPQBeN8JCByeiezwukaqlf31jwRZqREvAH3k/oSY0aX ToGgKWdYJnW1yTQo+frQD5uR/+BGyb3Lx/tRc4FSVAPr3b9DGag65m82zTFD9gcoikdnYlbrPib aTvzlSHSEuAs/Y6g9LAJmJ56PLyVa/WF0+l0qe2QtWVZLCWewcHeZUv5tkrNN0v/OqFgw6nRG5R YrQ9AL55HlditOg== 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 Thu Feb 6 12:22:08 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863419 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 4F43422DF86 for ; Thu, 6 Feb 2025 12:22:28 +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=1738844551; cv=none; b=mGFUOoLiONkW8l23EuUGw7vTrA2ZcLePlPX9hDe+Zq4AKJ8LYywVcoKZUMuoCoeX0/wKb1PDPKBplxkfVjpgOLeUNZ/rX5xhRYY1ricnfOtyW/zkNVAVYRtjMDRq36efLN/D/7Mgu5igXFLa9RMrHy0fy1Uc0QLEVwbH8BPjB4c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844551; c=relaxed/simple; bh=cYDNqwYD8iOSt27AkSqjbGzDL60HxWMB3A61faNnDGQ=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=HccP2zZb96IuPX4X9+O5W4WIRoIiF1PL+zLOuz5780cfWuPURwpnvPli1GX+FN+tKfBfc5xAQAJ3SMqFJn43tv4nJdrdih2dqZSvCE66VAB+UL4aXRkqSS3S3V8bhr7AN2P8DbSxgDrVO7Z51JPEj8xlewSZhZeIupXkC1fA8Qg= 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=U+MeJEjG; 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="U+MeJEjG" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-4362bae4d7dso5613715e9.1 for ; Thu, 06 Feb 2025 04:22:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844547; x=1739449347; 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=oEv7r4vhq0Wlrq3DyzjuLXehdJ2olQy4C593USt3yxw=; b=U+MeJEjGSWeI9PpOOBcpAFSj7URy5SdYJwvZJce50QBScePeXry1+W3cjRG3/2gOxm XMToikIoJJL9XnC82HupLZ4Yh8N8EPq4frTwPfXM0tA41M08VJZLUzWiv9jewOBiG1c8 zs1VqsteCpKclSrkNRVkPmZITZdZC9b/EeoyK0a6SVFx3f6qGz39I+XFNQpHFBhqDeFi MhGtb6F42c96vfDCJ6Sw49PKlc1tqhc75CE0onEyWrzH42LEtHjeYPswvnyrw3yStFdc JwOWpOA/3xznWRDtDZsiCrJLUJRNELQkt7e/f5Y7myZLk9zh0I23VEWievJFbUIuE+Ho oopA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844547; x=1739449347; 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=oEv7r4vhq0Wlrq3DyzjuLXehdJ2olQy4C593USt3yxw=; b=khAkR//uIXr43aURT2M1dapDeR3PATh04Z6uG7iJMYp3qU3XYM4JkAOl6c7BU8Srk1 9ts+HI4EQ14U3FGWnAiRWMMSIYb8r91u37VyrP9s1lBEU+rjUqDyiyAAKsUQG6PzDtFf Jd2IoNZh3ZGByD/zvOIu39+eqwG+dL9VNrWQwoanRWGlc22wm/+5WO8RoeTNCjgWgsij a9PArzG4lzU7vAf1+vkITY9OgpO21dpZowVmeWFHQrExwsyTKmbyDZFsSp0vSBoXtbmQ bGJAkafliwY7Qt03TdcLnxVUJTpGse30506uaqBsF2sdcx3JKgXfu2pGA96ZuNGJfycp 54hA== X-Forwarded-Encrypted: i=1; AJvYcCWQftIW/dXB/SGFi+zzjz7RdEoNF1UA6Vqhf7ZWLkuNIau9MdBCaFXWUlcsmfULJGkFCc0WjhmUWvsF@vger.kernel.org X-Gm-Message-State: AOJu0Yxrqy7mrq0G8VcrMrSE3W1ebfGldDvhFDuycZgigPxJXuc+ymXt DXCGCyQ9eI7ZAww9d8YnoK0bbglTx1YFmX2VO48t1QPqekaB72ymq8+KcmHfb54= X-Gm-Gg: ASbGnct2umrwmOoVQxa6uKIbvkjVPVCBhM3bRI3kwEX5RCj6tFJkttgdOn4mbBe8gCM yGHAnUwC2RXrNPEnkQHVL2UzAvHK4Bvv1EBIhXKv7zX6em116wkmgjt0RqNF0JOHdFhRON+IXL/ ssLDntWqRhqPLcvMxB96uSCRvrWlPDJHZ456l1fcEjKV55hivsY3yJuFzTATnWi4eQW9MFk40e2 KF9BuRy93Qlhq6zlpLbYd/poLLQsUeABWtcyrbU5SavL7QtfXV98lo7pVYYVeMGeSKdaFy3Gvwq 4QB3MQ== X-Google-Smtp-Source: AGHT+IFnAefZkhHz3/teFF/Za8esFGdqS02Nl2jvm/5g+SgLrlqTC07GpWA5mFhdBSMGjIPv2GaWLg== X-Received: by 2002:a05:600c:138f:b0:433:c76d:d57e with SMTP id 5b1f17b1804b1-4390d42d884mr59890545e9.5.1738844546230; Thu, 06 Feb 2025 04:22:26 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:25 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:08 +0100 Subject: [PATCH libgpiod v3 11/16] 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: <20250206-improve-docs-v3-11-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=35841; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=sTUv7bCGss1cTMwYQDwdTYdaUpzRfh/X/h+PiLaYlEo=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKlzCFlqqdcGPLpu4TOigYPjk+eoGmLLPHVbp z6LNSvtb++JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcwAKCRARpy6gFHHX cqFNEADgIpQKwn+JWuX7g9Mz15Q02gCL69DrynSb8ohSuvOvqyIeLqMxsa+v/crYefcmC91SBn6 CUa2XUGc8pBSu/0z1qbSALYPWB2PfYAuaZ7clQc7SeIRld1PcnkNQwXzZRk/kdMBqSIUHAwGMhI gs792pfOu/QG2rRTE8bXvLAv2SiQsXl9CFsnYmbT09aR0yuVVB2DjK3anVHEWZ8aDQYHIaQDkzb 7rcMruvUpOG+6qwO0/diHSxarLgtN3al7jnQ2msc1OAppvbqVD7cCKtcf8feOc4nX8DKoJIy2TV o5zs01KAAP8xOcVy5x655HaNP+A2+TBOsoQTbsTlEocWidHPEs23WITiezg51dFa/YR3sNiSBm6 OAokOSV+ysIVjvtPl/NbXDLsubHz4EYm2MD1Ul6kGAt5+oJ9/ImqHAWjmNRVLxd+ENbH53RayEB sZYbWSAdvOpr2Q7i6QahYYAoyd3/CoWY8ZXXMXGEGaxmrEWeaP8QK0+B2L7QuhlesAGqCbJ+pXG xKc+AhPKfcIphTrgrt+qd3gsHq/fflhgjPPwEhf33SISIowpmtAPnFysQrbkADyynXXjHPB7ivW eaxOX/SDH2hIGZghInX9AidJ4CwVTQoFK75PDuzUHRMhv4XSdfl0MQgu0oN1fC2zPd4hF3dsnok gyQ37wcNSChsM9A== 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 ./doc/ doc/sphinx-output`). Move the introduction text from the main header into the relevant .rst file. Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where all the documentation now lives. Update .gitignore where needed. Signed-off-by: Bartosz Golaszewski --- .gitignore | 2 - .readthedocs.yaml | 16 +++---- Doxyfile.in | 105 ----------------------------------------- Makefile.am | 12 ++--- README | 12 ++--- configure.ac | 9 +++- docs/.gitignore | 5 ++ docs/Doxyfile | 12 +++++ docs/Makefile.am | 45 ++++++++++++++++++ docs/bindings.rst | 20 ++++++++ docs/conf.py | 53 +++++++++++++++++++++ docs/core_api.rst | 62 ++++++++++++++++++++++++ docs/core_chip_info.rst | 11 +++++ docs/core_chips.rst | 11 +++++ docs/core_edge_event.rst | 11 +++++ docs/core_line_config.rst | 11 +++++ docs/core_line_defs.rst | 11 +++++ docs/core_line_info.rst | 11 +++++ docs/core_line_request.rst | 11 +++++ docs/core_line_settings.rst | 11 +++++ docs/core_line_watch.rst | 11 +++++ docs/core_misc.rst | 11 +++++ docs/core_request_config.rst | 11 +++++ docs/cpp_api.rst | 34 +++++++++++++ docs/cpp_chip.rst | 12 +++++ docs/cpp_chip_info.rst | 12 +++++ docs/cpp_edge_event.rst | 12 +++++ docs/cpp_edge_event_buffer.rst | 12 +++++ docs/cpp_exceptions.rst | 18 +++++++ docs/cpp_info_event.rst | 12 +++++ docs/cpp_line.rst | 24 ++++++++++ docs/cpp_line_config.rst | 12 +++++ docs/cpp_line_info.rst | 12 +++++ docs/cpp_line_request.rst | 15 ++++++ docs/cpp_line_settings.rst | 12 +++++ docs/cpp_misc.rst | 16 +++++++ docs/cpp_request_config.rst | 12 +++++ docs/index.rst | 28 +++++++++++ docs/requirements.txt | 5 ++ include/gpiod.h | 36 -------------- sphinx/conf.py | 68 -------------------------- sphinx/contents.rst | 24 ---------- 42 files changed, 590 insertions(+), 260 deletions(-) diff --git a/.gitignore b/.gitignore index c3a29d8..7b5fa15 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,6 @@ *.la generated-*.c generated-*.h -doc *.pc *.tar.gz *.patch @@ -16,7 +15,6 @@ tags # autotools stuff .deps/ .libs/ -Doxyfile Makefile Makefile.in aclocal.m4 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f40e95f..510b5c1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,5 +1,6 @@ # SPDX-License-Identifier: LGPL-2.1-or-later # SPDX-FileCopyrightText: 2022 Kent Gibson +# 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..ae58605 100644 --- a/Makefile.am +++ b/Makefile.am @@ -50,15 +50,11 @@ SUBDIRS += man endif -if HAS_DOXYGEN +if WITH_DOCS -doc: Doxyfile - $(AM_V_GEN)doxygen Doxyfile -.PHONY: doc +docs: + $(MAKE) -C docs docs -clean-local: - rm -rf doc - -EXTRA_DIST += Doxyfile +.PHONY: docs endif diff --git a/README b/README index 80ad939..28a3dfd 100644 --- a/README +++ b/README @@ -333,14 +333,12 @@ bindings use the standard tests module layout and the #[test] attribute. DOCUMENTATION ------------- -All API symbols exposed by the core C API and C++ bindings are documented with -doxygen markup blocks. Doxygen documentation can be generated by executing -'make doc' given that the doxygen executable is available in the system. +The project uses sphinx to automatically generate the documentation. The system +needs to provide doxygen and sphinx-build programs. With those in place, the +build can be invoked with 'make docs'. This generates documentation for the +core C API as well as C++ and python bindings. -Python bindings contain help strings that can be accessed with the help -builtin. - -Rust bindings use rustdoc. +Rust bindings use rustdoc, GLib bindings use gi-docgen. Man pages for command-line programs are generated automatically if gpio-tools were selected and help2man is available in the system. diff --git a/configure.ac b/configure.ac index 5a7e01c..8eec855 100644 --- a/configure.ac +++ b/configure.ac @@ -328,12 +328,16 @@ then fi AC_CHECK_PROG([has_doxygen], [doxygen], [true], [false]) -AM_CONDITIONAL([HAS_DOXYGEN], [test "x$has_doxygen" = xtrue]) +AC_CHECK_PROG([has_sphinx], [sphinx-build], [true], [false]) +AM_CONDITIONAL([WITH_DOCS], [test "x$has_doxygen" = xtrue && test "x$has_sphinx" = xtrue]) if test "x$has_doxygen" = xfalse then AC_MSG_NOTICE([doxygen not found - documentation cannot be generated]) fi -AM_COND_IF([HAS_DOXYGEN], [AC_CONFIG_FILES([Doxyfile])]) +if test "x$has_sphinx" = xfalse +then + AC_MSG_NOTICE([sphinx-build not found - documentation cannot be generated]) +fi if test "x$cross_compiling" = xno then @@ -350,6 +354,7 @@ AC_CONFIG_FILES([Makefile lib/Makefile lib/libgpiod.pc contrib/Makefile + docs/Makefile examples/Makefile tools/Makefile tests/Makefile diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..86f8cfd --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +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..b8cf010 --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +DOCS_DEPS = \ + bindings.rst \ + conf.py \ + core_api.rst \ + core_chip_info.rst \ + core_chips.rst \ + core_edge_event.rst \ + core_line_config.rst \ + core_line_defs.rst \ + core_line_info.rst \ + core_line_request.rst \ + core_line_settings.rst \ + core_line_watch.rst \ + core_misc.rst \ + core_request_config.rst \ + cpp_api.rst \ + cpp_chip_info.rst \ + cpp_chip.rst \ + cpp_edge_event_buffer.rst \ + cpp_edge_event.rst \ + cpp_exceptions.rst \ + cpp_info_event.rst \ + cpp_line_config.rst \ + cpp_line_info.rst \ + cpp_line_request.rst \ + cpp_line.rst \ + cpp_line_settings.rst \ + cpp_misc.rst \ + cpp_request_config.rst \ + Doxyfile \ + index.rst + +docs: $(DOCS_DEPS) + sphinx-build ./ ./sphinx-output + +.PHONY: docs + +clean-local: + rm -rf docs/sphinx-output + rm -rf docs/doxygen-output + +EXTRA_DIST = $(DOCS_DEPS) requirements.txt diff --git a/docs/bindings.rst b/docs/bindings.rst new file mode 100644 index 0000000..069fc8f --- /dev/null +++ b/docs/bindings.rst @@ -0,0 +1,20 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + 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 Thu Feb 6 12:22:09 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862732 Received: from mail-wm1-f48.google.com (mail-wm1-f48.google.com [209.85.128.48]) (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 D59BF22D4E5 for ; Thu, 6 Feb 2025 12:22:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.48 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844552; cv=none; b=ZkRgZGIDVxvFxxp0dNX9KpX6xjeYhjSfl33gVRMR7VnRci4ttNN4DQLbHXtDfz/vzwoDU6aPkVAtJzTgAp+oBkPCoRPB6V/Fp8mPsYw+N+uCGwI/Rf+C2a3X3LBkiPNYWHxWM7pALdkXLhWQZLulyuw4z/6i8EHHvn4GnEwnZ4M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844552; c=relaxed/simple; bh=mSqsFmZPOabDVEeMLifE1dEy1siDeQry56Wdgi36et8=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=H/c0gcWFQ9/e3jMAtddwmy8daQktE7pgkSjBWvVcc034wLt0cVaOvddQOuy8xbIJeogbBNIR1HOQi6266NqprcUvfzoE+GYUR8rMH8KsmwE0GNvKg+h56KjtFrLuHVn/V2KXJgJvlDNlMLUa7GDSCxkZUCNuh1jjCItbO849yYE= 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=Gcb9eiTF; arc=none smtp.client-ip=209.85.128.48 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="Gcb9eiTF" Received: by mail-wm1-f48.google.com with SMTP id 5b1f17b1804b1-4361b6f9faeso4660955e9.1 for ; Thu, 06 Feb 2025 04:22:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844547; x=1739449347; 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=U5LzZPmqY+CtWBYlpbMj2y2+1NLwvLGPcUy1p0/8H5c=; b=Gcb9eiTFs1vvpvGH60mrmAnsRsWJiak3rJHV573t0Be75Fy6lGdPdJb8EZKpikFea2 bJltNRM6afR7cACrj9fo6/MoQ3odr57Wc6Y2lJb5y8ivAgxj5dL1e8HQuNo+N+tZtBq7 tGOy9jATBw+ZAPn6IjE5SQbvj/hIwiFxCqmCmzqLe47nIiOVijuDKLJaAdPsmoiN02sr KlFjenBZEaLR6LETE5s92xHxT/ubCkDRVPNwEl+WOpaBBz7jqUl+/ezA4Zi8vgwtJcaq w9ewR0PwVwh1kUCdpsXahXpgDN8D3yTeDu75WMkeMtwe7pdS1p0+xtocO5dJe0E5nHFj QARA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844547; x=1739449347; 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=U5LzZPmqY+CtWBYlpbMj2y2+1NLwvLGPcUy1p0/8H5c=; b=qoLC/1j9Fj9y/KW79tUWy1JEU3fhdlHvGGMVH0lIfyNEzs0xmA3XKBLxY0ezNXX6HC cmh0VUNruvRJaI2NaWDPYqnpLPVfLteBWelQu2kjhulyKYsjdaJtookcIUFr5PPxc1Zp EhgxQMVNVG3sw4UWs1HS6cPACliSegs/Eidk7Pyw/ojdHzV/SNNVugnvvZr8PBM6hYq9 fkTejibZXM335igiTcTPTGvPISjLWrhIGtfPzlosg4BOj0IJOifwo6OFJHDIzcXnJiyK WJ77ok15fK5gIHPLeXsuiQ/0VjFQDCcwQ0oCX3JOzxytAdTzsy0Jfui5RDDz23smoxpS nIhA== X-Forwarded-Encrypted: i=1; AJvYcCW9+7j2ap4Mk6LYSW9pMMMlNcMVehtZ6a7WUsxpRkqg9ISCVMRut3j7nf3QMZcqt1teSWDVAVGOTgx2@vger.kernel.org X-Gm-Message-State: AOJu0Yyy1MGCX9EuUwDLJZU1f+8pfivWsX1GnezEtCWuNFMv+Cyzw/88 x5RhO5xGsG5a2lV9ybnzmYADG9DH/tmehfGkDfKSvbxjqheDJA7HB6Hh+Gj9zWo= X-Gm-Gg: ASbGncs46DSRhPDHQZyLbZPN+cmBsX6FbRbD7YE2EJN9Mr16nV66DqvsR3B38GpLed9 1bjFOTKDBkGTjer+nr6z9VzmKUXgZQNkYo846AJnfJySEnjrdCl+1H70/VhRq7PVEs9jUWYBU2q 2svs0gGr7NCSfLb8Y/w3FyXnuBloPCC7HLwYUmfbd93M1i8aNFqIL++LbAecgsDCoGcv6CSLTk1 8W8mPIrTH9FVF2tpdyzUMQ6m1TvcJbssYCXDsRf4CzzjKcYF7B9XLxPZMxQzeKVwBxIaURc305F Rz5lPA== X-Google-Smtp-Source: AGHT+IGczCRDgmz/gojEulOUC6+kPpO+Th8xWbvenayMcOUQp/Fn8FhWBiDqNvUkg1mNpSd7e4O94w== X-Received: by 2002:a05:600c:4e15:b0:434:92f8:54a8 with SMTP id 5b1f17b1804b1-43912c5a51dmr21653775e9.0.1738844547096; Thu, 06 Feb 2025 04:22:27 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:26 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:09 +0100 Subject: [PATCH libgpiod v3 12/16] 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: <20250206-improve-docs-v3-12-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=9094; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=kVu6GynGUZT2n+IJIKq4QC/SP+KrLWb/1hOrgiRErQY=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKlzADHuvZ9mw2jas6aTIQnxTWKJppvfdbc6g 6XkGFe53UOJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpcwAKCRARpy6gFHHX clXzD/9wAR476H1pcmKk16/u7V2ER10xhZPK5KB8POQSXPbn99cvUO/AJ5PIhzGgtoiUZWLRW+H 1rq3uSYTPVA/WhaL1mnxJK2ruMuEBWJbAsc34vbY+DUmOVIh3dgCVFx554BD/JYHdn8SuonWEZX raqh+jKW3t3CpZlHODFFdk4mZiaJdFtvqMNBWRax9DkM58/iItl4jqxd1/n18a+0BykfACpFCgn /AhhWLwOWE+ZuNxERbdsmp64CJ5LR1F0Ma8gkw2shCzP+lWwy6Q1eYosLA8WZruEOiBi7oZPXbZ dHKZ/ryzjWdbkX4qR0KQzt8U1Fc6i7dSnpRjhNnOHTjhpPfB9UgGXwfo357+LRBxE4HO6EOpB3G XObpSEUzYPHjV0U4YDJVGQCtTSCHuVbrm4KQ8krNoPC+0dC2IV2UbrcHS+gn2EeXLGs81DEEmoM ShPWMzNwCoYL3XOs8qkY4cnbb6fQDtP4uO/UslIX+xBNeL6afspCRIBXGQX4JiD0Povrz2Ao6h/ QGJ/5PZELf+yyIUo3u1bBLJ8Apxw5ex48mb8oC4pQ93gV7XShdo/djJC+DjFRX7QtQu2zwx720c /2UltIbSd9aMXiH13WCI2pflCis5HcT+e/JTITYZoG5pIdsTHloaiuQJOitAWfQhR9TRBxEkmnM SrVXuUaVZEHFTyQ== 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 | 18 +++++++++++++++++- docs/python_api.rst | 33 +++++++++++++++++++++++++++++++++ docs/python_chip.rst | 12 ++++++++++++ docs/python_chip_info.rst | 12 ++++++++++++ docs/python_edge_event.rst | 12 ++++++++++++ docs/python_exceptions.rst | 17 +++++++++++++++++ docs/python_info_event.rst | 12 ++++++++++++ docs/python_line.rst | 27 +++++++++++++++++++++++++++ docs/python_line_info.rst | 12 ++++++++++++ docs/python_line_request.rst | 12 ++++++++++++ docs/python_line_settings.rst | 12 ++++++++++++ docs/python_misc.rst | 13 +++++++++++++ 14 files changed, 204 insertions(+), 2 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index b8cf010..dd3e6ac 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -31,7 +31,18 @@ DOCS_DEPS = \ cpp_misc.rst \ cpp_request_config.rst \ Doxyfile \ - index.rst + index.rst \ + python_api.rst \ + python_chip_info.rst \ + python_chip.rst \ + python_edge_event.rst \ + python_exceptions.rst \ + python_info_event.rst \ + python_line_info.rst \ + python_line_request.rst \ + python_line.rst \ + python_line_settings.rst \ + python_misc.rst docs: $(DOCS_DEPS) sphinx-build ./ ./sphinx-output diff --git a/docs/bindings.rst b/docs/bindings.rst index 069fc8f..ed7ec69 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -18,3 +18,4 @@ C library. :caption: Contents cpp_api + python_api diff --git a/docs/conf.py b/docs/conf.py index 04c8c3b..3d0209a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,7 @@ import os import re import subprocess import sys +from pathlib import Path project = "libgpiod" copyright = "2017-2025, Bartosz Golaszewski" @@ -34,11 +35,14 @@ with open("../configure.ac", "r") as fd: release = f"{version}{extra}" -extensions = ["breathe"] +extensions = ["breathe", "sphinx.ext.autodoc"] breathe_projects = {"libgpiod": "./doxygen-output/xml"} breathe_default_project = "libgpiod" +sys.path.insert(0, str(Path("../bindings/python").resolve())) +autodoc_mock_imports = ["gpiod._ext"] + # Use the RTD theme if available sphinx_rtd_theme = None try: @@ -50,4 +54,16 @@ except ImportError: html_theme = "sphinx_rtd_theme" if sphinx_rtd_theme else "default" + +def autodoc_skip_init(app, what, name, obj, would_skip, options): + if name == "__init__": + return False + + return would_skip + + +def setup(app): + app.connect("autodoc-skip-member", autodoc_skip_init) + + subprocess.run(["doxygen", "Doxyfile"]) diff --git a/docs/python_api.rst b/docs/python_api.rst new file mode 100644 index 0000000..00b30cb --- /dev/null +++ b/docs/python_api.rst @@ -0,0 +1,33 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + 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..2d78b4c --- /dev/null +++ b/docs/python_line_request.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + This file is part of libgpiod. + +GPIO line request +================= + +.. autoclass:: gpiod.LineRequest + :members: diff --git a/docs/python_line_settings.rst b/docs/python_line_settings.rst new file mode 100644 index 0000000..b1d594e --- /dev/null +++ b/docs/python_line_settings.rst @@ -0,0 +1,12 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + 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 Thu Feb 6 12:22:10 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863418 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 BC29622D4D5 for ; Thu, 6 Feb 2025 12:22:30 +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=1738844552; cv=none; b=e+or0vIjsg0xEoRafN0HfseAsp+FOSkf2VO+XDwT/YwfmL3oQ5z1UiWe/CGvhlDkM2SXOhF224Z7roDoHVomYob1L/0cMXMjfA880vQjkhfVzaIDoRe5WnVh/kwBdBs/ArQCg4TJXdfV12yVGv4BVL4tEWRjPwtfITlc6R/6pKM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844552; c=relaxed/simple; bh=C83/n0dzhy10SzcX9pFT1a0HqaZLjXcgxsTq8ErvNNc=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=T1QMmsG0Wf3SIby6tipE7yKkl18I0eA97j+/RiVRRxHfegQau6IYP8TnGtzd3cUwViUc35tYD6QFhJObpqZyPWKttyE2zYuqIiEBCnk2HdckNq2HpgYbq5FCWgGymVq65xbzcosChrtbkG8DckVBxUtLK+yei/VkvxlzsA7ZSwY= 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=lEC4aTqW; 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="lEC4aTqW" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-436ce2ab251so5260325e9.1 for ; Thu, 06 Feb 2025 04:22:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844549; x=1739449349; 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=Xx4xbYPphWqOiZSyil4D9RJUGzOHeo3JsF0Q9TNJ/k4=; b=lEC4aTqW84vxEFDkEc/e3aJKVN+xyuh1+UEClXpEnoQXuM2WFSQ6sPXCNLLvsvimFm B3fq/LHiKODEJ3G7rQ/6iS9SBHXNu5D5UW91oETK2zvU3rMu7KGtfzvZMFsBrLZBsml8 emeLn/oFH7ktI4nf5ZxUzl7DpKvSzldv1PDy1GqSqQ3+6jgRcBTx0J6W7H5oWJ5RhVeq 6mU/GqAH9FKniMGL7pr7Mtg157Gcnf69KBdpsswANuvzvvEmz1Z+k82sAft/e1y+lwBZ 2lkqJNFvg5b6YFBbE1aFvik9yAE/1AzVbY3FqD+F0bV210KsdnVTsrdkunFSN8DESfLV TsGg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844549; x=1739449349; 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=Xx4xbYPphWqOiZSyil4D9RJUGzOHeo3JsF0Q9TNJ/k4=; b=CqEPAK7zBXcno2UR9IUpz85+oiFnvV6TIzbKHEPGDQwLQqzNsYgTmp73dY3SBWOneO SDCch816bLTkML2+1OtxPNlTcFnKguzrVKzHdFUKNs2kykMvpbp7DpVTvky5qOSyxVLZ yLYWr/om0mVTJNbyoa+EmSDAY5WNAfO9+I8qHKkTwMC0OggUsmOjt6bStyWTPQlxTSLz 4fPbdqHRl/W5YrqEZASMWON1/jmVC8cw2olGA6tk9ifLzSCGu1YjJ6LIK/ow9KEMHcLO VsU+POJd0+uF5KA5PRUeL3OqKnQjBHh45Q2MGxy8iDyka60+eXJ9q5oTNCtdr+Zzc4zM 89+w== X-Forwarded-Encrypted: i=1; AJvYcCWvYh9tMs0Cg4gX6hqvwHrcoCfE8GXXi7jYLx3BGSHkZnBb8CY4wmoy14h3w5oRlHugRtE6cr4swTqm@vger.kernel.org X-Gm-Message-State: AOJu0Yy7YtxPTeGdk59PhRViiAp1I+wqNT/3mwRF2VMzb1vRR3JjKdIa t27RRQ/+BeuetrYg1NE/AqWngIjVBM2BKopCAQ8npEzvD9CQODcUaXCWwKwI608= X-Gm-Gg: ASbGncsPD4e6QEhl4lYR4dXtRbDh59zsmUGLAx6jdBVpDbC7QUJrdpwkMq7WDLY2edh ORZZ8SLYIfMbCXDPxd0YOhAn1fnoifGL286fLkdIewZmweMJPBLKwClzjIws1G4apSxHDQsu1HC ut4GtyPnernB1HIOPxb+JO2vN14WCd5IKbd2K4zOQWtejyxIazI1m5tP4LiwzdtzIC0mXxNgjQA edrwYRpfZtCGVbOjd6i0/1UX4ykxZcSsdK1IlKTyuqGXo6omFC/LCBf0o4XZEAYg8v44EwQQPs/ LSXCJw== X-Google-Smtp-Source: AGHT+IH/5r7BQwdc+Av7FdsUZUrw4aaA5DCbbDH7chItUBtUuVfb7qkxdeLmxx8flU5vO7L3qRrX5g== X-Received: by 2002:a05:600c:4fcf:b0:434:f623:9fe3 with SMTP id 5b1f17b1804b1-4390d43f12cmr65818915e9.16.1738844548945; Thu, 06 Feb 2025 04:22:28 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:27 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:10 +0100 Subject: [PATCH libgpiod v3 13/16] 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: <20250206-improve-docs-v3-13-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=4247; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=WiXLRks1OFxSdHV21Ymo3Cnsw8xD/7Ijy0sn6TXuRJY=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKl0Nu7eGIKxQ9F98nI5xAev4pLG/4CmsLsuG pG7fS94mRSJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpdAAKCRARpy6gFHHX cmiKD/49K3XipoNINerkgl09uCc6d0kAdC6lCHKyY2yUELjK/i9ShD2gGg3rhMe5JhkKh6ZRv/f gJVYw6uxO3b0oyi7nDIFq0METaSnEZ/Jl/9gxxVL6wPqWn0k0JtCYeQHJ8HRJuOwQglpy+llMho rt/loDHqlBmXTaN4uDUVcCUuTYVo0dwqqbbYG/pJQiMocjxDgEdWgG3A8xzaUL62DDPIHj1SWOg jiEzJqgOVt7YuEMwrpBeqZ2KbZN9DLhX+7qfpmU/BRGk9yg2RRkEi0dZ5yItToTbxljq51zUSiS jaXYenn19YAik1rb0w2KWo36l/QjtVMXpUZJ+ExR3GqJvcX0wTBFMIyZdHq4cS9ImNfUxzg90Yi EttSuHVeMCJ6OLtLM639li0LXZYrJRvsulEsy6+Y1JptEUXWXBaQm8YLOC3Y4VqCiKFqO35mPQ8 HoQPBJK/G8RLlXcXWr1Z8CjLD8B+rAPbiWLjszdlwAjvkzesDh6XRDMUPKbxngtiEE9JR6WSLe/ qpyhC/JYXnck7VW5w+L1Q7nSsWmkmGNox6uLRs+iHBUnaM1414MwxengKaXk8B18SgmuHCUahA+ HUWGD18WX+z6TEHhBHVgWJkBtHAQru7PNXC3x/fqPXioiQFp6G564bDsIgy/RjaOU8qXxYPzQ9+ s+C0fZeXUCH5zRw== 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 | 38 ++++++++++++++++++++++++++++++++++++++ docs/glib_api.rst | 23 +++++++++++++++++++++++ 5 files changed, 71 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 510b5c1..97086fa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,13 +11,20 @@ version: 2 build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: python: "3.12" apt_packages: + - autoconf + - autoconf-archive # doxygen is available by default, but just in case. - doxygen + - gi-docgen + - gir1.2-glib-2.0-dev + - gobject-introspection - graphviz + - libtool + - pkg-config sphinx: configuration: docs/conf.py diff --git a/docs/Makefile.am b/docs/Makefile.am index dd3e6ac..ef9ebf2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -32,6 +32,7 @@ DOCS_DEPS = \ cpp_request_config.rst \ Doxyfile \ index.rst \ + glib_api.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/bindings.rst b/docs/bindings.rst index ed7ec69..73f1262 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -19,3 +19,4 @@ C library. cpp_api python_api + glib_api diff --git a/docs/conf.py b/docs/conf.py index 3d0209a..33fc89f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,8 +62,46 @@ def autodoc_skip_init(app, what, name, obj, would_skip, options): return would_skip +# We need to know where to put docs generated by gi-docgen but app.outdir is +# only set once the builder is initialized. Let's delay running gi-docgen +# until we're notified. +def make_glib_docs(app): + # For some reason on RTD we're in the docs/ directory while during a local + # build, we're still in the top source directory. + prefix = "../" if os.getenv("READTHEDOCS") == "True" else "" + + subprocess.run( + [ + "gi-docgen", + "generate", + "--config", + f"{prefix}bindings/glib/gi-docgen.toml", + f"{prefix}bindings/glib/Gpiodglib-1.0.gir", + "--output-dir", + f"{app.outdir}", + ], + check=True, + ) + + def setup(app): app.connect("autodoc-skip-member", autodoc_skip_init) + app.connect("builder-inited", make_glib_docs) subprocess.run(["doxygen", "Doxyfile"]) + +cwd = os.getcwd() +os.chdir("..") +subprocess.run(["autoreconf", "-ifv"], check=True) +subprocess.run( + [ + "./configure", + "--enable-tools", + "--enable-bindings-glib", + "--enable-introspection", + ], + check=True, +) +subprocess.run(["make", "-j"], check=True) +os.chdir(cwd) diff --git a/docs/glib_api.rst b/docs/glib_api.rst new file mode 100644 index 0000000..307f5f7 --- /dev/null +++ b/docs/glib_api.rst @@ -0,0 +1,23 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2024-2025 Bartosz Golaszewski + +.. + 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 Thu Feb 6 12:22:11 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862731 Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) (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 BF20822D4F0 for ; Thu, 6 Feb 2025 12:22:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.47 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844553; cv=none; b=U0xpfpydy0iWaX2xLSV0csGGNH86s9v7r658H6+hx/kXMPXMaBF4LKcoSsV6SdKD+hsLrEe1x+NeZqxwA9pbfO4CNydwKMyT8JvAd6KBSbF8Moo5modrsAui9i2f4GGRu/Aq/nAH3Dc6c4Kgkq03gaYH2NogM/a6y4CNCI1+NBE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844553; c=relaxed/simple; bh=JayJQKl8QyM1y03imMMb3+krWrXZlOrW9T8eiTIiFpE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=rC6QLR2Oo/2QdcDRw2feRzcUDhcaoSmbTipSkpRcU7ds2mJyRnUimiER1J6of3NmwpwbC9ujHVy2m1JvqDuljIXBM/hoyBBmz4NV9RnApgjq/o3Mg372T00Iq5ir23iWgUIpAMs/5D7T2YRKNB/nBRXXvNP64gTQuiiAwIu/qCQ= 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=M11cr4E5; arc=none smtp.client-ip=209.85.128.47 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="M11cr4E5" Received: by mail-wm1-f47.google.com with SMTP id 5b1f17b1804b1-4368a293339so9128145e9.3 for ; Thu, 06 Feb 2025 04:22:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844550; x=1739449350; 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=MCdNJEl2czQbOdGVTb4tBPEJedPychSdvsrDKPt3tZI=; b=M11cr4E5d/EyIGqFNUb+4i2ppJVZkvcB5JQl56BQnGXZmNU2MAaUTmJBccxWJul1fG 78bJpuVq8wvutX4wLkrtN/Z38W4MeUGw8tJ6TDWvXxOLoVuzuOEQ5/bW/KZWvPVCR73B 1Ukfwq+s4+WZb1NGh+7hvLuiZ4BlXBFT00b94fgYd3/phD5iZtT0/VRrpoYmOPwWh/4F 3xqPzqekVgkNwfWB5o0jDjEuVJYfClUkFA9TOEFcQC5IJ7YQ9SC7V9xUjhVIHnXN+Ws7 E50FOoCWMgDomluN7JEsNSUQo4w6zkWbprW81BxK653gi/KburyoGCTgTj/P0p53MD+m 9F3g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844550; x=1739449350; 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=MCdNJEl2czQbOdGVTb4tBPEJedPychSdvsrDKPt3tZI=; b=LiIKiJ+OFm2Tyir+6ts300U2ljdS+xmq0/03uNnzmn1WxIlmht+kYPw/TrHYaxDJhj DzPYBkRclztrYcv2GoFJWqSR6ziK6jvcFnD5RlmRcOiaL1JOyLXPxFxeIp1ThAr51wjh sKTqWfhCLlilVNJkX/o89pAteVGetS1KI0mX8WJSt2paFg0Psxk/vIGOzpWag6KzlXsd m9So1QtVulZ8W097PK6STirA9t8sQ3D9MHMyx+Dr+DEscEFRea5HZPfqLRA0JDePeSV8 6A6T/V59fTXL1wS5WGa34RFAzI7idE/khlgKdyH/kJ1rXeihzlpxWXEMB5g+RuN+lEyQ mPmw== X-Forwarded-Encrypted: i=1; AJvYcCUso+sB67Olp1c3WtXxjoyh0SWPJgsSK3KlqRciVEHO7C80gofFf4TPblAQylolUQ9GDO4SIsLTGPb4@vger.kernel.org X-Gm-Message-State: AOJu0Yyf3pAYH7NtHb8qo+C6BEaV4/sL/vFejgwId3ZMtMWP36IrJ5Vr lqDn5AkAvOjReGnTvg9XJ4DK5+oksjJZ5dyFnLWv8U8kTv4A05SqYv4wSokyQQI= X-Gm-Gg: ASbGncvh7BjfevQ7B6XAdJBbfElOPKlkIbKwZkxwIbqc582o0BstoQ+xqa6yqacVH4V U2qesJ2rA53E787XvClQUI9mJtbX72KcSQXdpILLMzsacI1F7ROYG1VzGSZ3s530hVMsr8MwXwD vbhThsejvJqkL0FykU+DqVLXR6zw3it43a3TVDxY6QRzW7lSkYy3QK8kfkRP/Ju2gvX8j+16oEr ZOTFoCiggIbi6vqNtJiLd181fUSIJtKzKidOpiCEnmNk5MM1sbD7idLhLaa8o0pp7R95/I47uZX VROBhw== X-Google-Smtp-Source: AGHT+IEPGUrA4z8KiPHY+gmH2GT3EO3P/+hS9jOUPUEwJfeGhIMgpO2YYGej7V+DrbEcTvJOUzLB4A== X-Received: by 2002:a05:600c:4f87:b0:434:a815:2b5d with SMTP id 5b1f17b1804b1-4390d569847mr49804185e9.24.1738844550094; Thu, 06 Feb 2025 04:22:30 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:29 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:11 +0100 Subject: [PATCH libgpiod v3 14/16] 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: <20250206-improve-docs-v3-14-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=5208; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=FFQGQE+U+3PHlEYdijSCavIj74kLd24iZQFFrmUiQ6Y=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKl0u0DpFvo0e11exfgZFINR7gazG6k/2l6kx AS0OKDS2O2JAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpdAAKCRARpy6gFHHX cix4D/4nK3Td/iSDzwvANuxFA66Jmn201K6PLYiZujEA96oxbRm0UE+NgNPw3eu0UAshEpxXUEw rB+adS1n3zzNAxWkenRsHWQsJFCnWfeHfibxtiGlV9C+kzeaCnZvwajSKPE5B4AG+8yzB6kFll8 TaslcVZJcaTVC3o3oQtVl6ksSueb/Qe9jRwRTOkBDRW/LeOTwlXGxPTAGb9X+xv2dqmHKOwJf5J L3knqK5smBjnlD2LU198z0jqzQcM/oGNWkre5/c016xSbvuXc9Y47cXsewSwOlhzHIUDcb768Fo O/C/ZGSbOgP43ZQ5VLdLzn3LLg3CIhtEVpdhiqvFXDDgZZ3kL/6KXefdMsRU+gX50lg7lj2F/dM DGgRG9rAMnZmoFiqfHNnt6JAR93ufhZ8rFfO+2oP5ys+ob8aA4Qio+EHwatTpmLL4cqeQmDiKv4 HyZ0rvVBFaIoIeeZtA74tMWWAOJ79ZvVNuxT6AhfmQbn5TpG6rXDPQsLquDYglGH61yio8/Kjcl y263DOrsQPpfovFljOQkHsIrzSjdM2h0oz4tLd3q6LVX09U0Y0O+sxQSMbSMXJo0XZdpv+SkZ2w zHI+RHg/WsZ+x4hN/xvz7+enH5J0dFrdlnCJQaoO2SuxTw3WVJpIATR1Lxy73yu8UC8z4Wxhw9Z QSKsi90Fq4HYV+A== 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 ef9ebf2..269dd7e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -33,6 +33,7 @@ DOCS_DEPS = \ Doxyfile \ index.rst \ glib_api.rst \ + gpio_tools.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/conf.py b/docs/conf.py index 33fc89f..5e20c17 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,8 +100,30 @@ subprocess.run( "--enable-tools", "--enable-bindings-glib", "--enable-introspection", + "--enable-tools", ], check=True, ) subprocess.run(["make", "-j"], check=True) os.chdir(cwd) + +for page in [ + "gpiodetect", + "gpioinfo", + "gpioget", + "gpioset", + "gpiomon", + "gpionotify", +]: + subprocess.run( + [ + "pandoc", + "--from=man", + "--to=rst", + "--standalone", + "--wrap=none", + f"--output={page}.rst", + f"../man/{page}.man", + ], + check=True, + ) diff --git a/docs/gpio_tools.rst b/docs/gpio_tools.rst new file mode 100644 index 0000000..7372de4 --- /dev/null +++ b/docs/gpio_tools.rst @@ -0,0 +1,25 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + 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 Thu Feb 6 12:22:12 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 863417 Received: from mail-wr1-f44.google.com (mail-wr1-f44.google.com [209.85.221.44]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D0F5822D4D5 for ; Thu, 6 Feb 2025 12:22:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.44 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844554; cv=none; b=dB3F/YeY0sEY76ZfFdU+CE6sh3SD3vy7vhPZE3+Yftw4Q8IaM0w8RHack+Yag/RmE47Epz878KRq2j4FO6WYQHGkGM/5jV63mJXexHMDosbJTFy6aKwPRdrIzIOcJc1aRnCTWfCzo4isvcpIloVFXXHYBUw+FW8CnEPWyKkx5jM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844554; c=relaxed/simple; bh=yu9EyuGUFX68C0r1xD2DDUmoSUYLDCYgGt2P11sKENM=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=OgrHQoNEuOViMq5kpXE/UAmoIqf2Szpymizzn/hbImlHpa2ek9bGuWSg2wCBDDKUZ4FWemgZJl+ZTu6alYz+2uRP3guWhVqYXRd4AcJ9qt4Y2GNW04v85xj2GhF1aQYcAgR5qezCq7334erjWI8scTjk7Vvn+0dK3KKx1aKQFl0= 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=i2jOTORx; arc=none smtp.client-ip=209.85.221.44 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=bgdev.pl Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=bgdev-pl.20230601.gappssmtp.com header.i=@bgdev-pl.20230601.gappssmtp.com header.b="i2jOTORx" Received: by mail-wr1-f44.google.com with SMTP id ffacd0b85a97d-388cae9eb9fso414401f8f.3 for ; Thu, 06 Feb 2025 04:22:32 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844551; x=1739449351; 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=DJi6mVJW5bYLmVVwvwCPxn8lprON+2nI2ecuhLfiO44=; b=i2jOTORx2kBhneXklKgyLVXzX7qsiwNNh8mVVV+knEGuq+MjPZigaD4aNaaU9ymOyB PhxcVmyWNMB7/Z1P5YhesNI8amTHvdxXpDX4z6BRatV89aoV2JnF3FR1hy45Ya1W1wy6 4PffgEyHeIM2+pakTrqbw41KdR+LArNUJQUc94YwamffeYDDmSigvM7QCbYo+/TCFWuy tKfpi9PSe9fQCxXLQorqjsEVPUhNmdq0pRHoEHN5R63d1PL1uwK0+PoayrnA8LJX62Gf fQCZtbWiUo9WhHmnuOOoY0R5qCgCFfzl9svKSzj8Y1VHpekKsWsGvlagSyO3V2ymi6IK LmYw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844551; x=1739449351; 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=DJi6mVJW5bYLmVVwvwCPxn8lprON+2nI2ecuhLfiO44=; b=l0FWBSNpFel6Yw9aGYJ6iCqK+uFQ2W78o8JbYW9nm+v9fO7dS+f20f9VcvqhkBSNG3 W6nvjcM4kCNZBEMaDNHtg6R/yt1hlxRPtr49cfQqTgiUyC8DYcilRBIhmZSqT/qu87wF vT4TS2C33BIhLsueOmCaFUgDou3Q0KG3yLsj/9Exv3GeQUYqA7w6rNkUhE2EErDX//vm VmYJdYQ5wkHIt2KDYhfjoJstr8XaOSgoKBvX1i+X24Dp/pBh5CrpdwmiaVMh8qwCex0M w7bovpex7nj3vNiM6p/EhF0OZYWN4WhL790hSaN0A++HE8llwdL++nm2iT/W8J7Ae/rL LUdw== X-Forwarded-Encrypted: i=1; AJvYcCWJQ2iiIKb+NzPQTGlO3DAZ/gPOQehN3RCTB6Fa45AZPpaWtfYx8dfrV1csOIMzXi9SCslKT8yMds/P@vger.kernel.org X-Gm-Message-State: AOJu0YwATQH0AhKDO738pvRxOLJJxRpoM3VJbQY+m4i4bjSfgEFpjrjk e9rYczgVGzuEosCNSIcMo88hzUNTHWfFXN5VJEIPPXs1Gd/ItgZIbjMA763J+dLH+BGTGXFzivO DaiQ= X-Gm-Gg: ASbGnctAeyrp4oM7+JR+HSV9/X40PQp8TNGA0K/M3wpQBRdc4wNtXN8BcABK+6wJ19+ XFAsujotFxKKguRwMPdqa8zAwmcgdUSP1E10qs2dlp2ISw8VMa127G8dqFkkdA85npwLiEc3MiC zAudcmGemE3jeDNXDvqCqLoWaZsYUPHeiffkJFqQSy8Q4W7tMY3wKJsySOFseYvBsc8YJ2GAxGA HkDlTtQcrXOowVjG4B6396Rn/k42NP9+S3tPIj9q8NclLCxBUmZLVY/IrpQie2wBd1g02zfl433 bGgG4Q== X-Google-Smtp-Source: AGHT+IHWnAvJLq1tQ+NTGtKHT2UdTVSBLJPly0DGu4reY8z1cO7qE3uvdGDUM9SeF46kOmouCkfB4Q== X-Received: by 2002:a05:6000:1a8a:b0:38a:8d32:274e with SMTP id ffacd0b85a97d-38db48a4351mr4629100f8f.5.1738844551184; Thu, 06 Feb 2025 04:22:31 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:30 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:12 +0100 Subject: [PATCH libgpiod v3 15/16] 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: <20250206-improve-docs-v3-15-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=5331; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=pCQXmeN8sbMalEHkT3s1mWAni7Uk/wWpD2P7KmYnXd0=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKl0C2wF2YkBNpPIIniDXaZm4DUWpj2XdKMbT b2RTdx0D5iJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpdAAKCRARpy6gFHHX cuRGEACRZZD75WhK7l6IMy3pq4A38jTLWOvUhSO4XQvofnocAt8pi4QSIaZX8gYgNB0HYRLFEVs A5W1vYlxivE0JCwbQOemooyxN3t/xKAIrXaVRcJv7VLYsV53nFKNE2GuMfIX4/0VWO40/56e+m8 ywXHkMY0pAKiTZpPpJLNg/xMNdDeHvlwxlWvHZt8kgfrU6FrtmM+Fmhl/cZcj09tyo2lfZ2RSKD T9gU6rhgpIraMvXuoxGFgIYlh76uAk2qhB0zgMvX6GZ+KwpkxVMaz7vVB9JGLJgsk/jOsWv7SKj +mxD/IICNsipIC+jo6Y5zWZ+lft6vbyImTZe3r+zjRHzTxY80afA1CoZxQNUHe+XLnzWY3a+frw Qjliw3arw6YL+22xI6C/wKcdb7LCkMeoxWvCgNt/iTuojkqLWR5Psq95b4MuLGcDspcuOp0m/o/ ZrFnOWc0dEyj1T3yHo+CKcPoDjqvAs+ajpIiVyLmTkCZOkEku73qvkOvYOSi9u+WN+TCEya6a1j BVAibzS9t9l3DOLPafdujxXD4xyWC0J9q3agor6uvYyl+ghUCE8OPWJ65EqawtyeanckILWePnp U2MV4RAfosX7PyJ0ibzoSgGWPRrazHDRY9oH1VB3vuykJimj6a/suTmMqhY9fuP8dkgTPd6/ZNE mwpcqm5xTCWbf2Q== 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 269dd7e..096095d 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -30,10 +30,13 @@ DOCS_DEPS = \ cpp_line_settings.rst \ cpp_misc.rst \ cpp_request_config.rst \ + dbus.rst \ + dbus_api.rst \ Doxyfile \ index.rst \ glib_api.rst \ gpio_tools.rst \ + gpiocli_top.rst \ python_api.rst \ python_chip_info.rst \ python_chip.rst \ diff --git a/docs/conf.py b/docs/conf.py index 5e20c17..bf4028d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -101,6 +101,7 @@ subprocess.run( "--enable-bindings-glib", "--enable-introspection", "--enable-tools", + "--enable-dbus", ], check=True, ) @@ -114,6 +115,20 @@ for page in [ "gpioset", "gpiomon", "gpionotify", + "gpio-manager", + "gpiocli", + "gpiocli-detect", + "gpiocli-find", + "gpiocli-info", + "gpiocli-get", + "gpiocli-monitor", + "gpiocli-notify", + "gpiocli-reconfigure", + "gpiocli-release", + "gpiocli-request", + "gpiocli-requests", + "gpiocli-set", + "gpiocli-wait", ]: subprocess.run( [ @@ -127,3 +142,5 @@ for page in [ ], check=True, ) + +subprocess.run(["gdbus-codegen", "--generate-rst", "dbus", "../dbus/lib/io.gpiod1.xml"]) diff --git a/docs/dbus.rst b/docs/dbus.rst new file mode 100644 index 0000000..0dcbb81 --- /dev/null +++ b/docs/dbus.rst @@ -0,0 +1,24 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + 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 Thu Feb 6 12:22:13 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bartosz Golaszewski X-Patchwork-Id: 862730 Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) (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 5DCC222D4E9 for ; Thu, 6 Feb 2025 12:22:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.47 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844559; cv=none; b=afNZuIXvFsRWJ53YbvY+gxsueblveS61aQp9IDUicPSEtVAGrmJpzFIYQ2ogkC5rbpfD5/gfYisvcFr8llxo3rew1uBplXiWvJYUGiNMbeAVjuS1GviQkjoZ+phgQ0/feJ3K+jVvfQHgxwR9pr3qtCLHhhzdTwOefCVB8pdF6/s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738844559; c=relaxed/simple; bh=kHt4JppA9KoDQM6JoGGFF2Sta1pIN9pvL/Bp61estpA=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=WoYIWqTD5qBE2580QgggfkLDoLkUIlRwy09wlDydiN9vSzjABSPe/COp8Y7x3dDl2Y/6yL2xQgp2RhwxFkEzENZCG53GUf+9rBFTqGDP5u2PSMPuUA9ONovZIEqmYn1TsEKhwMDS1EV2E4oxEI7A0U5lmGOcl7WflQSoPXz2dkY= 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=S8mbeMG3; arc=none smtp.client-ip=209.85.128.47 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="S8mbeMG3" Received: by mail-wm1-f47.google.com with SMTP id 5b1f17b1804b1-436281c8a38so5541535e9.3 for ; Thu, 06 Feb 2025 04:22:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bgdev-pl.20230601.gappssmtp.com; s=20230601; t=1738844553; x=1739449353; 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=M2cP955ovmWP6uEcUtIsq/Fyd6FDbSlJTttPAOGYs7Y=; b=S8mbeMG3S2kOjYdEZSmYTkbXWKCk4SHwrVAqR25o3MzZmi1n3jkIDErEoxdFfBk9iy Ck6o8EbJlFVCJwI8KFhUvj0D9Lx8u85B25fO/hzF2t6RR4X8YQEqfUxwtWZf0XKn+8NY DgxMvtLvT/3ypmLU8zTXWH2oZlLW7l6U2StHuMu6qcHsDx1SCRFZ4jX6rWuvrZbrG+iH eixyWNZqsg7+Dw1zc18+lh/KRtZrclvfbhWdnEKNvj2Wm7dGVRyIhrO7oJP6rhFqAOvD oab6Pz8ot9UwGUCBWINJ8rJTVwHQJqrVJr9lUzdriRcixxLzBk+EuO6YnpLLmj7iqLH3 2nrw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738844553; x=1739449353; 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=M2cP955ovmWP6uEcUtIsq/Fyd6FDbSlJTttPAOGYs7Y=; b=KGhql10cCjFkOv52xexjFFudANYC3vSYJUnufQlEadfDMjev+k2dxBtWfacTVB41EM GA+nQKCPUWKAkfdgCX/BmpWVHazB2FLY/IRSWIv2dns9quFTxhTfnFqZh11yaE/VfIz5 MNSrT8WKCZrupQvwS0LXIGn+PgI2gl3qUAScHH+iech5r5TnlXdEt/Q3+XvzXnMZH8gw d5vru09RiGxjLe/cl3w0NY/av4PPBCMsnFjBxTnY/NNRMhmSOMfFDPqflkBfNv6rjk0H dOlV2kHXeRuGb6uhppATTBfOCHxnjuTf2WG7SGkagrhyNJlI3olC/EOneaVshkvahefv esIA== X-Forwarded-Encrypted: i=1; AJvYcCWKPl24dUSHxFu1pKDKkf92/ScpCOIna0YC59Mt3pHTkDbYugAB736CseRgyQavxIN+SxNLZCqkLEHB@vger.kernel.org X-Gm-Message-State: AOJu0Yy691aiQck4BLnvTOfQGSxKTyl7TLj8EJxAhsSOqR+g4FjEWE14 0bPFyGevBGHICSdwkRby3W38DOFN/Md1pFBfiLQ1qj8rF6bRN80rF82gRt0o3u4= X-Gm-Gg: ASbGnctQaPtDzS6/tJ9LQUGIpa+ArKeCsgRQXKl9YOqUoy4BHj0SSsfsZuTALn0Rgt/ hL5a1y+tv4Bf3nUDN/2BneGG0Ob7Rr/NKJvjjhhGsaQYLvz/oGMYNg9Fvi+1CsgeDCvl7EFDr9h YHj1M1Fi2JGxKBX+NIx1gDr9X5TLPPGzkDhepZU3vdaWNCnzM9QRrORAzCrPKrdkwdMjbu5/7+V r+/dUNacdTQzPOlDZPWEJ8DxzNiAMsTJuws0U5OdvQsPLuZh//C9XiDQhpg+J3RKFOGeNSc7sPK 0BbKhw== X-Google-Smtp-Source: AGHT+IGBxizUYkqg2qi2zJkJA2cp+18wC2qVVgGBjBk4svcRjsKPBvwzQC2cWwf9OyqhNavqb4QV/g== X-Received: by 2002:a05:6000:188f:b0:38a:86fe:52b5 with SMTP id ffacd0b85a97d-38db4872051mr5288450f8f.14.1738844552211; Thu, 06 Feb 2025 04:22:32 -0800 (PST) Received: from [127.0.1.1] ([2a01:cb1d:dc:7e00:c726:a8e:825:b823]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4391dfd7d7asm17366775e9.36.2025.02.06.04.22.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2025 04:22:31 -0800 (PST) From: Bartosz Golaszewski Date: Thu, 06 Feb 2025 13:22:13 +0100 Subject: [PATCH libgpiod v3 16/16] 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: <20250206-improve-docs-v3-16-2065191fff6f@linaro.org> References: <20250206-improve-docs-v3-0-2065191fff6f@linaro.org> In-Reply-To: <20250206-improve-docs-v3-0-2065191fff6f@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=40011; i=bartosz.golaszewski@linaro.org; h=from:subject:message-id; bh=4BvnDKZ0sjfkpW65p9guwpCJbbn+svsamT4NAV1Y4tQ=; b=owEBbQKS/ZANAwAKARGnLqAUcddyAcsmYgBnpKl0YzY3hbY4He9b0b/EKAMUPtxP2eDDc2Lvy jOXJnqP4xOJAjMEAAEKAB0WIQQWnetsC8PEYBPSx58Rpy6gFHHXcgUCZ6SpdAAKCRARpy6gFHHX cpyxD/407w2B4jUXieEWsOdTwpqQW4jx6DofErdYype0/8d1+fI/BmlLNRBNr4DdFlO+9XW7B90 UrtD8LC2i5kVC608yvzvKFcb14cnTfK2ZBWMbe9KwvS5kBL6mxTLZHf/ThUaTn0rpDdEn/kDPur 3W5h1pqwtjAF7r15eowySCxtgkY3pKt2jSbKhcVX21YdOY3M/XwbMMKj14IOgA0nEU1GvGpdq/M 9cNz4SfdpLUrYLFVs9OsttbCX/MzIzXnGrn4nvG9R0oLIu2XwisPi14m6ZtxzvWhiKUnzgvZNe0 QGPYUVa4ea6qdETarPqXNNdHxH/0Q2G0UFmVksp4/EW1Nu4s7t4EZ/kQkglEw9o4kcXbos+vjN+ bUc8d2xU9bQKuN6VM7DsUwhG++0YVBTndpVS7TsZcJ8EV3Gd6t7a31vrLn0TvEE69SnrQmk+GwD +M9otK4PAAzDs/XrrzIv9fiktX/K5037vceza4L81EeqsegKYBCW/8myGCGaoFpldkXKSh3lKET DtqCI5e/YwqZqeGmaGVk1aSUHAc06b1yLDo/5RPanH3fXuxA7mo/oH+4No35Ds2GZthNUj1cKQr BWfrnq6N0JcD/4DDGF4XlvtIARWQW+zupbpCAg0jIT/UmVWN8sdow18JyTae/LDAJPm5aljl2wG LwzW1lHxyQ9RBSA== 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 | 25 +++- docs/building.rst | 74 ++++++++++ docs/contributing.rst | 45 ++++++ docs/cpp_api.rst | 3 + docs/dbus.rst | 19 ++- docs/glib_api.rst | 3 + docs/gpio_tools.rst | 216 ++++++++++++++++++++++++++++ docs/gpiocli_top.rst | 81 +++++++++++ docs/index.rst | 23 ++- docs/python_api.rst | 8 ++ docs/testing.rst | 46 ++++++ 13 files changed, 544 insertions(+), 394 deletions(-) diff --git a/README b/README deleted file mode 100644 index 28a3dfd..0000000 --- a/README +++ /dev/null @@ -1,384 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 -# SPDX-FileCopyrightText: 2017-2023 Bartosz Golaszewski - -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..7f0f6b7 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -10,8 +10,12 @@ High-level language bindings to libgpiod ======================================== -The bindings provide a more straightforward interface to the base, low-level -C library. +Bindings provide a more straightforward interface to the core, low-level +C library. Object-oriented bindings for C++, GLib, python3 and Rust are +provided as part of the project. They can be enabled by passing +``--enable-bindings-cxx``, ``--enable-bindings-glib``, +``--enable-bindings-python`` and ``--enable-bindings-rust`` arguments to +configure respectively. .. toctree:: :maxdepth: 1 @@ -20,3 +24,20 @@ C library. cpp_api python_api glib_api + +.. warning:: + There's currently no good way of integrating rust documentation with sphinx. + Rust bindings should be documented on https://docs.rs/ but due to a yet + unsolved build problem, this is currently not the case. Please refer to the + in-source comments for now. + +.. note:: + Rust bindings are available on https://crates.io/ as the ``libgpiod`` + package. + +.. note:: + When building the Rust bindings along the C library using make, they will + be automatically configured to build against the build results of the + C library. Building rust bindings requires cargo to be available on the + system. + diff --git a/docs/building.rst b/docs/building.rst new file mode 100644 index 0000000..958c6fb --- /dev/null +++ b/docs/building.rst @@ -0,0 +1,74 @@ +.. + SPDX-License-Identifier: CC-BY-SA-4.0 + SPDX-FileCopyrightText: 2025 Bartosz Golaszewski + +.. + 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/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.