diff --git a/doc/source/conf.py b/doc/source/conf.py index 3658d89..02895a2 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' @@ -135,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 18876bc..360d815 100644 --- a/doc/source/man/khard.rst +++ b/doc/source/man/khard.rst @@ -4,11 +4,15 @@ khard Synopsis -------- -:program:`khard` [:option:`-c` CONFIG] [:option:`--debug`] [:option:`--skip-unparsable`] SUBCOMMAND ... +.. argparse:: + :module: khard.cli + :func: _sphinxarg_helper + :prog: khard + :nosubcommands: true -: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 ----------- @@ -18,34 +22,13 @@ 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 ----------- 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 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/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] 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 """ 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"