Build manual pages with argparse-manpage

build.py

@@ -0,0 +1,22 @@
+"""
+Hook argparse-manpage into setup.py generated by poetry
+"""
+
+from build_manpages import (
+    build_manpages,
+    get_build_py_cmd,
+    get_install_cmd,
+)
+
+
+def build(setup_kwargs):
+    """
+    This function is mandatory in order to build the extensions.
+    """
+    setup_kwargs.update({
+        "cmdclass": {
+            'build_manpages': build_manpages,
+            'build_py': get_build_py_cmd(),
+            'install': get_install_cmd(),
+        },
+    })

pyproject.toml

@@ -23,5 +23,18 @@ ibm-cloud-vm = "resalloc_ibm_cloud.ibm_cloud_vm:main"
 
 
 [build-system]
-requires = ["poetry-core"]
+requires = ["poetry-core", "argparse-manpage[setuptools]"]
 build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry.build]
+generate-setup-file = true
+script = "build.py"
+
+
+[tool.build_manpages]
+manpages = [
+    "man/resalloc-ibm-cloud-vm.1:function=vm_arg_parser:pyfile=resalloc_ibm_cloud/argparsers.py",
+    "man/resalloc-ibm-cloud-list-vms.1:function=vm_list_arg_parser:pyfile=resalloc_ibm_cloud/argparsers.py",
+    "man/resalloc-ibm-cloud-list-deleting-vms.1:function=default_arg_parser:pyfile=resalloc_ibm_cloud/argparsers.py",
+]

resalloc-ibm-cloud.spec

@@ -41,10 +41,14 @@ BuildRequires:  pyproject-rpm-macros
 %pyproject_install
 %pyproject_save_files resalloc_ibm_cloud
 
+mkdir -p  %buildroot%_mandir/man1
+install  -p -m 644 man/*.1 %buildroot%_mandir/man1
+
 
 %files -n %{name} -f %{pyproject_files}
 %license LICENSE
 %doc README.md
+%_mandir/man1/resalloc-ibm-cloud*1*
 %{_bindir}/ibm-cloud-list-deleting-vms
 %{_bindir}/ibm-cloud-list-vms
 %{_bindir}/ibm-cloud-vm

resalloc_ibm_cloud/argparsers.py

@@ -0,0 +1,68 @@
+"""
+ArgumentParser getters on one place, this simplifies generating manual pages.
+"""
+
+import argparse
+
+def default_arg_parser():
+    """
+    The part that every resalloc-ibm-cloud utility needs
+    """
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--token-file", help="Path to IBM cloud token file", required=True
+    )
+    parser.add_argument(
+        "--service-url",
+        help="SERVICE URL e.g. https://jp-tok.iaas.cloud.ibm.com/v1",
+        required=True,
+    )
+    return parser
+
+
+def vm_arg_parser():
+    """
+    Parser for the resalloc-ibm-cloud-vm utility.
+    """
+    parser = default_arg_parser()
+    parser.add_argument("--log-level", default="info")
+
+    subparsers = parser.add_subparsers(dest="subparser")
+    subparsers.required = True
+    parser_create = subparsers.add_parser(
+        "create", help="Create an instance in IBM Cloud"
+    )
+    parser_create.add_argument("name")
+    parser_create.add_argument("--playbook", help="Path to playbook", required=True)
+    parser_create.add_argument("--image-uuid", required=True)
+    parser_create.add_argument("--vpc-id", required=True)
+    parser_create.add_argument("--security-group-id", required=True)
+    parser_create.add_argument("--ssh-key-id", required=True)
+    parser_create.add_argument("--instance-type", help="e.g. cz2-2x4", required=True)
+    parser_create.add_argument("--floating-ip-name", default=None)
+    parser_create.add_argument(
+        "--zones",
+        help=(
+            "Path to json file with zones as keys and subnet id as value."
+            'content of file will look like: {"jp-tok-1": "secret-subnet-id-123-abcd", ...}'
+        ),
+        required=True,
+    )
+    parser_delete = subparsers.add_parser(
+        "delete", help="Delete instance by it's name from IBM Cloud"
+    )
+    parser_delete.add_argument("name")
+    subparsers.add_parser(
+        "delete-free-floating-ips", help="Clean all IPs without an assigned VM"
+    )
+    return parser
+
+
+def vm_list_arg_parser():
+    """
+    Parser for the resalloc-ibm-cloud-list-vms utility.
+    """
+    parser = default_arg_parser()
+    parser.add_argument("--pool")
+    return parser

resalloc_ibm_cloud/helpers.py

@@ -1,4 +1,3 @@
-import argparse
 import subprocess
 import datetime
 from argparse import Namespace
@@ -7,19 +6,6 @@
 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
 
 
-def default_arg_parser():
-    parser = argparse.ArgumentParser()
-    parser.add_argument(
-        "--token-file", help="Path to IBM cloud token file", required=True
-    )
-    parser.add_argument(
-        "--service-url",
-        help="SERVICE URL e.g. https://jp-tok.iaas.cloud.ibm.com/v1",
-        required=True,
-    )
-    return parser
-
-
 def get_service(cmd: str, opts: Namespace):
     output = subprocess.check_output(cmd, shell=True)
     token = output.decode("utf-8").strip().rsplit("\n", maxsplit=1)[-1]

resalloc_ibm_cloud/ibm_cloud_list_deleting_vms.py

@@ -2,19 +2,15 @@
 List all IBM Cloud instances that are in Deleting state
 """
 
-from resalloc_ibm_cloud.helpers import default_arg_parser, get_service
+from resalloc_ibm_cloud.helpers import get_service
+from resalloc_ibm_cloud.argparsers import default_arg_parser
 from resalloc_ibm_cloud.constants import LIMIT
 
 
-def _get_arg_parser():
-    parser = default_arg_parser()
-    return parser
-
-
 def main():
     """Entrypoint to the script."""
 
-    opts = _get_arg_parser().parse_args()
+    opts = default_arg_parser().parse_args()
     cmd = f"source {opts.token_file} ; echo $IBMCLOUD_API_KEY"
     service = get_service(cmd, opts)
 

resalloc_ibm_cloud/ibm_cloud_list_vms.py

@@ -5,20 +5,15 @@
 import os
 import sys
 
-from resalloc_ibm_cloud.helpers import default_arg_parser, get_service
+from resalloc_ibm_cloud.helpers import get_service
+from resalloc_ibm_cloud.argparsers import default_arg_parser
 from resalloc_ibm_cloud.constants import LIMIT
 
 
-def _get_arg_parser():
-    parser = default_arg_parser()
-    parser.add_argument("--pool")
-    return parser
-
-
 def main():
     """An entrypoint to the script."""
 
-    opts = _get_arg_parser().parse_args()
+    opts = default_arg_parser().parse_args()
 
     pool_id = opts.pool or os.getenv("RESALLOC_POOL_ID")
     if not pool_id:

resalloc_ibm_cloud/ibm_cloud_vm.py

@@ -12,7 +12,8 @@
 import sys
 import requests
 
-from resalloc_ibm_cloud.helpers import default_arg_parser, get_service
+from resalloc_ibm_cloud.helpers import get_service
+from resalloc_ibm_cloud.argparsers import vm_arg_parser
 from resalloc_ibm_cloud.constants import LIMIT
 
 
@@ -253,41 +254,6 @@ def delete_instance_attempt(service, instance_name, opts):
             log.debug("Delete volume request delivered")
 
 
-def _get_arg_parser():
-    parser = default_arg_parser()
-    parser.add_argument("--log-level", default="info")
-
-    subparsers = parser.add_subparsers(dest="subparser")
-    subparsers.required = True
-    parser_create = subparsers.add_parser(
-        "create", help="Create an instance in IBM Cloud"
-    )
-    parser_create.add_argument("name")
-    parser_create.add_argument("--playbook", help="Path to playbook", required=True)
-    parser_create.add_argument("--image-uuid", required=True)
-    parser_create.add_argument("--vpc-id", required=True)
-    parser_create.add_argument("--security-group-id", required=True)
-    parser_create.add_argument("--ssh-key-id", required=True)
-    parser_create.add_argument("--instance-type", help="e.g. cz2-2x4", required=True)
-    parser_create.add_argument("--floating-ip-name", default=None)
-    parser_create.add_argument(
-        "--zones",
-        help=(
-            "Path to json file with zones as keys and subnet id as value."
-            'content of file will look like: {"jp-tok-1": "secret-subnet-id-123-abcd", ...}'
-        ),
-        required=True,
-    )
-    parser_delete = subparsers.add_parser(
-        "delete", help="Delete instance by it's name from IBM Cloud"
-    )
-    parser_delete.add_argument("name")
-    subparsers.add_parser(
-        "delete-free-floating-ips", help="Clean all IPs without an assigned VM"
-    )
-    return parser
-
-
 def _wait_for_ssh(floating_ip):
     cmd = [
         "resalloc-aws-wait-for-ssh",
@@ -337,7 +303,7 @@ def detect_floating_ip_name(opts):
 def main():
     """Entrypoint to the script."""
 
-    opts = _get_arg_parser().parse_args()
+    opts = vm_arg_parser().parse_args()
     log_level = getattr(logging, opts.log_level.upper())
     logging.basicConfig(format="%(levelname)s: %(message)s", level=log_level)
     log = logging.getLogger()