From 2cc8b11928ac96389d12f807593aa3008531ff14 Mon Sep 17 00:00:00 2001 From: Lucas Hoffmann Date: Thu, 24 Oct 2019 13:55:38 +0200 Subject: [PATCH 1/4] doc: add sphinx argparse extension for man pages The extension can use our argparse parser object to generate a listing of subommands and options automatically. --- doc/source/conf.py | 1 + pyproject.toml | 7 ++++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 3658d89..02f28a7 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -53,6 +53,7 @@ def update_template_file(): 'sphinx.ext.autosectionlabel', 'sphinx.ext.todo', 'sphinx_autodoc_typehints', # https://pypi.org/project/sphinx-autodoc-typehints/ + 'sphinxarg.ext', ] autoapi_type = 'python' diff --git a/pyproject.toml b/pyproject.toml index 21bfbdb..099107f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,7 +31,12 @@ dependencies = [ ] [project.optional-dependencies] -doc = ['sphinx', 'sphinx-autoapi', 'sphinx-autodoc-typehints'] +doc = [ + 'sphinx', + 'sphinx-argparse', + 'sphinx-autoapi', + 'sphinx-autodoc-typehints', +] [project.urls] homepage = "https://github.com/lucc/khard" From bb41fff978bbb9a8c1b6c50db07601d80d1cc9d8 Mon Sep 17 00:00:00 2001 From: Lucas Hoffmann Date: Sat, 20 Feb 2021 08:42:52 +0100 Subject: [PATCH 2/4] doc: use sphinx argparse extension in main man page --- doc/source/man/khard.rst | 8 ++++++++ khard/cli.py | 5 +++++ 2 files changed, 13 insertions(+) diff --git a/doc/source/man/khard.rst b/doc/source/man/khard.rst index 18876bc..b9679b8 100644 --- a/doc/source/man/khard.rst +++ b/doc/source/man/khard.rst @@ -4,6 +4,14 @@ khard Synopsis -------- +.. argparse:: + :module: khard.cli + :func: _sphinxarg_helper + :prog: khard + +Synopsis +-------- + :program:`khard` [:option:`-c` CONFIG] [:option:`--debug`] [:option:`--skip-unparsable`] SUBCOMMAND ... :program:`khard` :option:`-h` | :option:`--help` diff --git a/khard/cli.py b/khard/cli.py index 730c606..592fdea 100644 --- a/khard/cli.py +++ b/khard/cli.py @@ -455,3 +455,8 @@ def init(argv: list[str]) -> tuple[argparse.Namespace, Config]: return args, merge_args_into_config(args, conf) except ConfigError as err: sys.exit(str(err)) + + +def _sphinxarg_helper(): + """Helper function to return the correct argument parser for the docs.""" + return create_parsers()[1] From 71fb6f00628b6742e8c7fd81afdd00c605406a0c Mon Sep 17 00:00:00 2001 From: Lucas Hoffmann Date: Mon, 5 Dec 2022 23:25:03 +0100 Subject: [PATCH 3/4] doc: add new man page with subcommand listing --- doc/source/conf.py | 1 + doc/source/man.rst | 1 + doc/source/man/khard-subcommands.rst | 14 ++++++++++++++ doc/source/man/khard.rst | 6 +++--- 4 files changed, 19 insertions(+), 3 deletions(-) create mode 100644 doc/source/man/khard-subcommands.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 02f28a7..02895a2 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -136,6 +136,7 @@ def update_template_file(): # (source start file, name, description, authors, manual section). man_pages = [ ('man/khard', 'khard', 'Console address book manager', '', 1), + ('man/khard-subcommands', 'khard-subcommands', 'Subcommands of khard', '', 1), ('man/khard.conf', 'khard.conf', 'configuration file for khard', '', 5), ] diff --git a/doc/source/man.rst b/doc/source/man.rst index ac9eabe..c3d5704 100644 --- a/doc/source/man.rst +++ b/doc/source/man.rst @@ -7,4 +7,5 @@ The following man pages are available for khard: :maxdepth: 1 khard(1) + khard-subcommands(1) khard.conf(1) diff --git a/doc/source/man/khard-subcommands.rst b/doc/source/man/khard-subcommands.rst new file mode 100644 index 0000000..4dc88b7 --- /dev/null +++ b/doc/source/man/khard-subcommands.rst @@ -0,0 +1,14 @@ +khard subcommands +================= + +These are all the subcommands and accepted arguments of :manpage:`khard(1)`. + +.. argparse:: + :module: khard.cli + :func: _sphinxarg_helper + :prog: khard + +See also +-------- + +:manpage:`khard(1)`. diff --git a/doc/source/man/khard.rst b/doc/source/man/khard.rst index b9679b8..e26e604 100644 --- a/doc/source/man/khard.rst +++ b/doc/source/man/khard.rst @@ -8,9 +8,7 @@ Synopsis :module: khard.cli :func: _sphinxarg_helper :prog: khard - -Synopsis --------- + :nosubcommands: true :program:`khard` [:option:`-c` CONFIG] [:option:`--debug`] [:option:`--skip-unparsable`] SUBCOMMAND ... @@ -54,6 +52,8 @@ Subcommands The functionality of khard is divided into several subcommands. All of these have their own help text which can be seen with ``khard SUBCOMMAND --help``. +The full list of subcommands and all options can be found in +:manpage:`khard-subcommands(1)`. Many subcommands accept search terms to limit the number of contacts they should work on, display or present for selection. The syntax is described in From 5cde150134d4461568984ea8342eb7a4cff333e2 Mon Sep 17 00:00:00 2001 From: Lucas Hoffmann Date: Fri, 20 Dec 2024 15:18:57 +0100 Subject: [PATCH 4/4] doc: Replace manual option list in khard.1 with generated one --- doc/source/man/khard.rst | 39 +++++++----------------------------- khard/carddav_object.py | 2 +- khard/helpers/interactive.py | 2 +- 3 files changed, 9 insertions(+), 34 deletions(-) diff --git a/doc/source/man/khard.rst b/doc/source/man/khard.rst index e26e604..360d815 100644 --- a/doc/source/man/khard.rst +++ b/doc/source/man/khard.rst @@ -5,16 +5,14 @@ Synopsis -------- .. argparse:: - :module: khard.cli - :func: _sphinxarg_helper - :prog: khard - :nosubcommands: true + :module: khard.cli + :func: _sphinxarg_helper + :prog: khard + :nosubcommands: true -:program:`khard` [:option:`-c` CONFIG] [:option:`--debug`] [:option:`--skip-unparsable`] SUBCOMMAND ... - -:program:`khard` :option:`-h` | :option:`--help` - -:program:`khard` :option:`-v` | :option:`--version` + -c --config + The default value and the syntax of the config file are explained in + :manpage:`khard.conf(5)`. Description ----------- @@ -24,29 +22,6 @@ modify and delete vCard address book entries. :program:`khard` only works with store of vCard files. It is intended to be used in conjunction with other programs like an email client, text editor, vdir synchronizer or VOIP client. -Options -------- - -.. option:: -c CONFIG, --config CONFIG - - configuration file (default: :file:`~/.config/khard/khard.conf`) - -.. option:: --debug - - output debugging information - -.. option:: -h, --help - - show a help message and exit - -.. option:: --skip-unparsable - - skip unparsable vcards when reading the address books - -.. option:: -v, --version - - show program's version number and exit - Subcommands ----------- diff --git a/khard/carddav_object.py b/khard/carddav_object.py index 08c478b..27766b6 100644 --- a/khard/carddav_object.py +++ b/khard/carddav_object.py @@ -115,7 +115,7 @@ def __str__(self) -> str: def get_first(self, property: str, default: str = "") -> str: """Get a property from the underlying vCard. - This method should only be called for properties with cardinality *1 + This method should only be called for properties with cardinality \\*1 (zero or one). Otherwise only the first value will be returned. If the property is not present a default will be returned. diff --git a/khard/helpers/interactive.py b/khard/helpers/interactive.py index a5d78b8..2e9cae1 100644 --- a/khard/helpers/interactive.py +++ b/khard/helpers/interactive.py @@ -35,7 +35,7 @@ def ask(message: str, choices: list[str], default: Optional[str] = None, None this list must not contain the string "?" :param default: the answer that should be selected on empty user input (None means empty input is not accepted) - :parm help: a help text to display to the user if they did not answer + :param help: a help text to display to the user if they did not answer correctly :returns: the choice of the user """