docs: make man pages more standard

While our man pages included all relevant documentation parts, they were pretty non-standard (e.g. non standard section names, no synopsis). This patch switches the sphinx-argparser directive into manpage mode (for manpages only) and adds the module description into the DESCRIPTION field. By that, the manpages now follow the recommended scheme. Signed-off-by: Felix Moessbauer <[email protected]> Signed-off-by: Jan Kiszka <[email protected]>
siemens · Apr 25, 2024 · 3f46848 · 3f46848
1 parent 11c7af3
commit 3f46848
Show file tree

Hide file tree

Showing 13 changed files with 104 additions and 67 deletions.
diff --git a/docs/_man/kas-plugin-build.rst b/docs/_man/kas-plugin-build.rst
@@ -3,6 +3,14 @@
 kas build plugin
 ================
 
-.. include:: ../userguide/plugins/build.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: build
+    :manpage:
+
+    .. automodule:: kas.plugins.build
+        :noindex:
 
 .. include:: _kas-man-footer.inc
diff --git a/docs/_man/kas-plugin-checkout.rst b/docs/_man/kas-plugin-checkout.rst
@@ -3,6 +3,14 @@
 kas checkout plugin
 ===================
 
-.. include:: ../userguide/plugins/checkout.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: checkout
+    :manpage:
+
+    .. automodule:: kas.plugins.checkout
+        :noindex:
 
 .. include:: _kas-man-footer.inc
diff --git a/docs/_man/kas-plugin-dump.rst b/docs/_man/kas-plugin-dump.rst
@@ -3,10 +3,18 @@
 kas dump plugin
 ===============
 
-.. include:: ../userguide/plugins/dump.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: dump
+    :manpage:
+
+    .. automodule:: kas.plugins.dump
+        :noindex:
 
 SEE ALSO
-~~~~~~~~
+--------
 
 :manpage:`kas-project-config(1)`,
 :manpage:`kas-checkout(1)`,

diff --git a/docs/_man/kas-plugin-for-all-repos.rst b/docs/_man/kas-plugin-for-all-repos.rst
@@ -3,6 +3,14 @@
 kas for-all-repos plugin
 ========================
 
-.. include:: ../userguide/plugins/for-all-repos.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: for-all-repos
+    :manpage:
+
+    .. automodule:: kas.plugins.for_all_repos
+        :noindex:
 
 .. include:: _kas-man-footer.inc
diff --git a/docs/_man/kas-plugin-menu.rst b/docs/_man/kas-plugin-menu.rst
@@ -3,6 +3,14 @@
 kas menu plugin
 ===============
 
-.. include:: ../userguide/plugins/menu.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: menu
+    :manpage:
+
+    .. automodule:: kas.plugins.menu
+        :noindex:
 
 .. include:: _kas-man-footer.inc
diff --git a/docs/_man/kas-plugin-shell.rst b/docs/_man/kas-plugin-shell.rst
@@ -3,6 +3,14 @@
 kas shell plugin
 ================
 
-.. include:: ../userguide/plugins/shell.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: shell
+    :manpage:
+
+    .. automodule:: kas.plugins.shell
+        :noindex:
 
 .. include:: _kas-man-footer.inc
diff --git a/docs/userguide/plugins.rst b/docs/userguide/plugins.rst
@@ -5,31 +5,68 @@ kas sub-commands are implemented by a series of plugins. Each plugin
 typically provides a single command.
 
 ``build`` plugin
-~~~~~~~~~~~~~~~~
+----------------
 
-.. include:: plugins/build.inc
+.. automodule:: kas.plugins.build
+
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: build
 
 ``checkout`` plugin
-~~~~~~~~~~~~~~~~~~~
+-------------------
+
+.. automodule:: kas.plugins.checkout
+
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: checkout
 
-.. include:: plugins/checkout.inc
 
 ``dump`` plugin
-~~~~~~~~~~~~~~~
+---------------
+
+.. automodule:: kas.plugins.dump
 
-.. include:: plugins/dump.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: dump
 
 ``for-all-repos`` plugin
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
-.. include:: plugins/for-all-repos.inc
+.. automodule:: kas.plugins.for_all_repos
+
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: for-all-repos
 
 ``menu`` plugin
-~~~~~~~~~~~~~~~
+---------------
+
+.. automodule:: kas.plugins.menu
 
-.. include:: plugins/menu.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: menu
 
 ``shell`` plugin
-~~~~~~~~~~~~~~~~
+----------------
+
+.. automodule:: kas.plugins.shell
 
-.. include:: plugins/shell.inc
+.. argparse::
+    :module: kas.kas
+    :func: kas_get_argparser
+    :prog: kas
+    :path: shell
diff --git a/docs/userguide/plugins/build.inc b/docs/userguide/plugins/build.inc
diff --git a/docs/userguide/plugins/checkout.inc b/docs/userguide/plugins/checkout.inc
diff --git a/docs/userguide/plugins/dump.inc b/docs/userguide/plugins/dump.inc
diff --git a/docs/userguide/plugins/for-all-repos.inc b/docs/userguide/plugins/for-all-repos.inc
diff --git a/docs/userguide/plugins/menu.inc b/docs/userguide/plugins/menu.inc
diff --git a/docs/userguide/plugins/shell.inc b/docs/userguide/plugins/shell.inc