Generate manual page versions of documentation for help command

Manual pages are included in distributions so that they can be
accessed reliably, but should be built separately if installing
as a system package.

Author: coloursofnoise

.github/workflows/publish.yml

@@ -21,6 +21,10 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: '3.10'
+          sphinx: '5.3.0'
+
+      - name: Generate packaged manual pages
+        run: sphinx-build -b man -W docs mons/man -d docs/_build
 
       - name: Install pypa/build
         run: python -m pip install build --user

.gitignore

@@ -1,3 +1,6 @@
+# Project-specific files
+mons/man/*
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include mons/man/man[0-9] *

docs/conf.py

@@ -39,6 +39,16 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# -- Options for manual page output ------------------------------------------
+
+man_pages = [
+    ("everest", "mons", "", "", "1"),
+    ("mods", "mons-mods", "", "", "1"),
+]
+
+man_make_section_directory = True
+manpages_url = "https://www.man7.org/linux/man-pages/man{section}/{page}.{section}.html"
+
 
 # -- Options for HTML output -------------------------------------------------
 

mons/mons.py

@@ -1,9 +1,18 @@
 #!/usr/bin/env python
 import logging
 import os
+import shutil
+import subprocess
+import sys
 import typing as t
 from importlib import import_module
 
+# namespace package support added in 3.10
+if sys.version_info >= (3, 10):  # novermin
+    from importlib.resources import files
+else:
+    from importlib_resources import files
+
 import click
 
 import mons.clickExt as clickExt
@@ -38,24 +47,45 @@ def cli(ctx: click.Context):
     ctx.parent = env_ctx
 
 
+_MAN_PAGES = {
+    "": ("1", "mons"),
+    "mons": ("1", "mons"),
+    "mods": ("1", "mons-mods"),
+}
+
+
 @cli.command(context_settings={"ignore_unknown_options": True})
 @click.argument("command", nargs=-1)
 @click.pass_context
 def help(ctx: click.Context, command: t.List[str]):
     """Display help text for a command."""
+    try:
+        man_pages = files("mons.man")
+    except FileNotFoundError:
+        man_pages = None
 
-    # No args means print program help
-    if len(command) < 1 and ctx.parent:
-        click.echo(cli.get_help(ctx.parent))
-        exit(0)
+    man_path = shutil.which("man")
+    if man_pages and man_path and " ".join(command).lower() in _MAN_PAGES:
+        cmd_str = " ".join(command).lower()
+        section, page = _MAN_PAGES[cmd_str]
+        subprocess.run(
+            [
+                man_path,
+                "--local-file",
+                "-",
+            ],
+            env=env,
+            input=man_pages.joinpath(f"man{section}", f"{page}.{section}").read_bytes(),
+        )
+        return
 
     group = cli
     cmd_path = []
     for cmd_name in command:
         cmd_path.append(cmd_name)
         cmd = group.get_command(ctx, cmd_name)
         if not cmd:
-            err_msg = "No such command '{}.'".format(" ".join(cmd_path))
+            err_msg = "No help entry for '{}'.".format(" ".join(cmd_path))
             click.echo(str(click.BadArgumentUsage(err_msg, ctx)))
             exit(click.BadArgumentUsage.exit_code)
 

setup.cfg

@@ -24,8 +24,13 @@ install_requires =
     pyyaml
     urllib3
     platformdirs
-package_dir =
-packages = find:
+    typing_extensions
+    importlib_resources;python_version<'3.10'
+packages = find_namespace:
+include_package_data = True
+
+[options.packages.find]
+include = mons*
 
 [options.entry_points]
 console_scripts =

tox.ini

@@ -24,4 +24,8 @@ commands =
     pyright --pythonplatform Windows --stats
 
 [testenv:docs]
-commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html
+deps = -r requirements-dev.txt
+skip_install = true
+commands =
+    sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html
+    sphinx-build -W -b man -d {envtmpdir}/doctrees docs {envtmpdir}/man