#187: Add manpage

docs/poetry-dynamic-versioning.1

@@ -0,0 +1,25 @@
+.TH POETRY\-DYNAMIC\-VERSIONING "1" "2024\-07\-26" "poetry\-dynamic\-versioning 1.4.0" "poetry\-dynamic\-versioning"
+.SH NAME
+poetry\-dynamic\-versioning
+.SH SYNOPSIS
+.B poetry\-dynamic\-versioning
+[-h] {enable} ...
+.SH DESCRIPTION
+Apply the dynamic version to all relevant files and leave the changes in\-place. This allows you to activate the plugin behavior on demand and inspect the result. Your configuration will be detected from pyproject.toml as normal.
+
+.SH
+SUBCOMMANDS
+.SS \fBpoetry\-dynamic\-versioning enable\fR
+Update pyproject.toml to enable the plugin using a typical configuration. The output may not be suitable for more complex use cases.
+
+usage: poetry\-dynamic\-versioning enable [\-h]
+
+.SH AUTHOR
+.nf
+'Matthew T. Kennerly (mtkennerly)'
+.fi
+
+.SH DISTRIBUTION
+The latest version of poetry\-dynamic\-versioning may be downloaded from
+.UR https://github.com/mtkennerly/poetry\-dynamic\-versioning
+.UE

poetry_dynamic_versioning/cli.py

@@ -45,13 +45,17 @@ class Help:
     )
 
 
-def parse_args(argv=None) -> argparse.Namespace:
+def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=Help.main)
 
     subparsers = parser.add_subparsers(dest="cmd", title="subcommands")
     subparsers.add_parser(Command.enable, help=Help.enable)
 
-    return parser.parse_args(argv)
+    return parser
+
+
+def parse_args(argv=None) -> argparse.Namespace:
+    return get_parser().parse_args(argv)
 
 
 def validate(*, standalone: bool, config: Optional[Mapping] = None) -> None:

pyproject.toml

@@ -41,6 +41,7 @@ pre-commit = "^1.16"
 black = "^22.8"
 mypy = "^0.971"
 ruff = {version = "^0.0.272", python = "^3.7"}
+argparse-manpage = "^4.6"
 
 [tool.poetry.scripts]
 poetry-dynamic-versioning = 'poetry_dynamic_versioning.__main__:main'

tasks.py

@@ -1,4 +1,5 @@
 import os
+import shlex
 import shutil
 from pathlib import Path
 
@@ -11,6 +12,14 @@
 DEPRECATED_PYPROJECT = ROOT / "pyproject.plugin.toml"
 
 
+def get_version() -> str:
+    for line in (ROOT / "pyproject.toml").read_text("utf-8").splitlines():
+        if line.startswith("version ="):
+            return line.replace("version = ", "").strip('"')
+
+    return "0.0.0"
+
+
 @task
 def pdv(ctx):
     if NORMAL_PYPROJECT.exists():
@@ -73,3 +82,36 @@ def uninstall(ctx, pip=False):
             ctx.run("poetry self remove poetry-dynamic-versioning")
     except Exception:
         pass
+
+
+@task
+def docs(ctx):
+    version = get_version()
+    manpage = "docs/poetry-dynamic-versioning.1"
+
+    args = [
+        "poetry",
+        "run",
+        "argparse-manpage",
+        "--pyfile",
+        "poetry_dynamic_versioning/cli.py",
+        "--function",
+        "get_parser",
+        "--project-name",
+        "poetry-dynamic-versioning",
+        "--prog",
+        "poetry-dynamic-versioning",
+        "--version",
+        version,
+        "--author",
+        '"Matthew T. Kennerly (mtkennerly)"',
+        "--url",
+        "https://github.com/mtkennerly/poetry-dynamic-versioning",
+        "--format",
+        "single-commands-section",
+        "--output",
+        manpage,
+        "--manual-title",
+        "poetry-dynamic-versioning",
+    ]
+    ctx.run(shlex.join(args))