From 3f468481332e75db562d2939719f671b76590e2e Mon Sep 17 00:00:00 2001 From: Felix Moessbauer Date: Thu, 25 Apr 2024 13:36:40 +0200 Subject: [PATCH] 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 Signed-off-by: Jan Kiszka --- docs/_man/kas-plugin-build.rst | 10 +++- docs/_man/kas-plugin-checkout.rst | 10 +++- docs/_man/kas-plugin-dump.rst | 12 ++++- docs/_man/kas-plugin-for-all-repos.rst | 10 +++- docs/_man/kas-plugin-menu.rst | 10 +++- docs/_man/kas-plugin-shell.rst | 10 +++- docs/userguide/plugins.rst | 61 +++++++++++++++++++----- docs/userguide/plugins/build.inc | 8 ---- docs/userguide/plugins/checkout.inc | 8 ---- docs/userguide/plugins/dump.inc | 8 ---- docs/userguide/plugins/for-all-repos.inc | 8 ---- docs/userguide/plugins/menu.inc | 8 ---- docs/userguide/plugins/shell.inc | 8 ---- 13 files changed, 104 insertions(+), 67 deletions(-) delete mode 100644 docs/userguide/plugins/build.inc delete mode 100644 docs/userguide/plugins/checkout.inc delete mode 100644 docs/userguide/plugins/dump.inc delete mode 100644 docs/userguide/plugins/for-all-repos.inc delete mode 100644 docs/userguide/plugins/menu.inc delete mode 100644 docs/userguide/plugins/shell.inc diff --git a/docs/_man/kas-plugin-build.rst b/docs/_man/kas-plugin-build.rst index 0239c43b..6cf9e9dd 100644 --- 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 index 65146203..d86fe854 100644 --- 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 index 5ba07096..1a21b844 100644 --- 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 index c07e6134..04792745 100644 --- 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 index 9cc8c92e..d0c3cdc7 100644 --- 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 index 643514ed..34af125f 100644 --- 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 index ffa5fe11..2f4108bb 100644 --- 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 deleted file mode 100644 index 338176c9..00000000 --- a/docs/userguide/plugins/build.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.build - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: build diff --git a/docs/userguide/plugins/checkout.inc b/docs/userguide/plugins/checkout.inc deleted file mode 100644 index fda07afb..00000000 --- a/docs/userguide/plugins/checkout.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.checkout - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: checkout diff --git a/docs/userguide/plugins/dump.inc b/docs/userguide/plugins/dump.inc deleted file mode 100644 index 74b3453d..00000000 --- a/docs/userguide/plugins/dump.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.dump - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: dump diff --git a/docs/userguide/plugins/for-all-repos.inc b/docs/userguide/plugins/for-all-repos.inc deleted file mode 100644 index a4b8f2b4..00000000 --- a/docs/userguide/plugins/for-all-repos.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.for_all_repos - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: for-all-repos diff --git a/docs/userguide/plugins/menu.inc b/docs/userguide/plugins/menu.inc deleted file mode 100644 index ea528edc..00000000 --- a/docs/userguide/plugins/menu.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.menu - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: menu diff --git a/docs/userguide/plugins/shell.inc b/docs/userguide/plugins/shell.inc deleted file mode 100644 index c9adf3f0..00000000 --- a/docs/userguide/plugins/shell.inc +++ /dev/null @@ -1,8 +0,0 @@ -.. automodule:: kas.plugins.shell - :noindex: - -.. argparse:: - :module: kas.kas - :func: kas_get_argparser - :prog: kas - :path: shell