public inbox for gentoo-commits@lists.gentoo.org
 help / color / mirror / Atom feed
* [gentoo-commits] proj/pkgcore/pkgcore:master commit in: src/pkgcore/scripts/, doc/
@ 2025-01-16 10:44 Arthur Zamarin
  0 siblings, 0 replies; only message in thread
From: Arthur Zamarin @ 2025-01-16 10:44 UTC (permalink / raw
  To: gentoo-commits

commit:     acb85735b20d5e33ccc78390ad9894ee2d3a6113
Author:     Eli Schwartz <eschwartz <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 15 20:48:08 2025 +0000
Commit:     Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
CommitDate: Thu Jan 16 05:10:17 2025 +0000
URL:        https://gitweb.gentoo.org/proj/pkgcore/pkgcore.git/commit/?id=acb85735

docs: make the manpages contain the extended help text

This uses the snake oil from snakeoil.cli.arghparse :) which passes
extra docs in via custom argparse attributes. In order to produce docs,
you need to set a snakeoil global variable, which then causes the extra
docs to replace the help?

This also revealed a bug. You cannot simply use the percent symbol in
argparse help strings, as documented in the standard library:

> As the help string supports %-formatting, if you want a literal % to
> appear in the help string, you must escape it as %%.

Indeed, it crashes if you include one such as ``%`` since the backtick
isn't a valid format specifier. Fix that by percent-escaping the
percent.

Signed-off-by: Eli Schwartz <eschwartz <AT> gentoo.org>

 doc/conf.py                  | 4 ++++
 src/pkgcore/scripts/patom.py | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index f21d3dc5..1cea8812 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -14,6 +14,10 @@
 import sys, os
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../src'))
 
+# make the argument parser emit docs
+import snakeoil.cli.arghparse
+snakeoil.cli.arghparse._generate_docs = True
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

diff --git a/src/pkgcore/scripts/patom.py b/src/pkgcore/scripts/patom.py
index 113bd853..87f9bdf8 100644
--- a/src/pkgcore/scripts/patom.py
+++ b/src/pkgcore/scripts/patom.py
@@ -37,7 +37,7 @@ group.add_argument(
     docs="""
         Specify a custom  output  format.
 
-        Conversion specifiers start with a ``%`` symbol and are followed by
+        Conversion specifiers start with a ``%%`` symbol and are followed by
         either ``{`` or ``[``.  Next is the name of the field to expand,
         followed by a matching ``}`` or ``]``.
 


^ permalink raw reply related	[flat|nested] only message in thread

only message in thread, other threads:[~2025-01-16 10:44 UTC | newest]

Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-01-16 10:44 [gentoo-commits] proj/pkgcore/pkgcore:master commit in: src/pkgcore/scripts/, doc/ Arthur Zamarin

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox