Merge branch 'feature/auto-man'

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),
 ]
 

doc/source/man.rst

@@ -7,4 +7,5 @@ The following man pages are available for khard:
    :maxdepth: 1
 
    khard(1) <man/khard>
+   khard-subcommands(1) <man/khard-subcommands>
    khard.conf(1) <man/khard.conf>

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)`.

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

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.
 

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]

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
     """

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"