add --doc-format option for choosing the output of the documentation verb

diff --git a/NEWS.md b/NEWS.md
index be5bfd9f13bcf301098e2080cc87eb8001e834bc..b4ae8369fddd0b56ead3788a67362a5683daf8c3 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -113,14 +113,13 @@
   removed.
 - A verb `documentation` has been added. Calling mkosi with this verb will show
   the documentation. This is useful when running mkosi during development to
-  always have the documentation in the correct version available. If available,
-  the man page will be shown, but it will fall back to the markdown file from
-  which it can be generated, e.g. via `pandoc -t man -s -o mkosi.1
-  mkosi.md`. The markdown file can be found in `mkosi/resources` in the Python
-  package or by redirecting the output of `python -m mkosi documentation` into a
-  file. Distro packagers are encouraged to add a file `mkosi.1` into the
-  `mkosi/resources` directory of the Python package as well es install it in
-  the appropriate search path for man pages.
+  always have the documentation in the correct version available. By default it
+  will try several ways to output the documentation, but a specific option can
+  be chosen with the `--doc-format` option. Distro packagers are encouraged to
+  add a file `mkosi.1` into the `mkosi/resources` directory of the Python
+  package, if it is missing, as well es install it in the appropriate search
+  path for man pages. The man page can be generated from the markdown file
+  `mkosi/resources/mkosi.md` e.g via `pandoc -t man -s -o mkosi.1 mkosi.md`.
 
 ## v14
 

diff --git a/mkosi/__init__.py b/mkosi/__init__.py
index ea74662869eb7a5e57b3674efbf1abab6b23dfc2..abe7c9ed90a58e7131b4032b0d87af5bd1272f04 100644 (file)
--- a/mkosi/__init__.py
+++ b/mkosi/__init__.py
@@ -4,8 +4,8 @@ import contextlib
 import datetime
 import hashlib
 import http.server
-import itertools
 import importlib.resources
+import itertools
 import json
 import logging
 import os
@@ -24,6 +24,7 @@ from mkosi.archive import extract_tar, make_cpio, make_tar
 from mkosi.config import (
     Compression,
     ConfigFeature,
+    DocFormat,
     ManifestFormat,
     MkosiArgs,
     MkosiConfig,
@@ -1652,13 +1653,39 @@ def bump_image_version(uid: int = -1, gid: int = -1) -> None:
 
 
 def show_docs(args: MkosiArgs) -> None:
-    with importlib.resources.path("mkosi.resources", "mkosi.1") as man:
-        if man.exists():
-            run(["man", man])
-            return
+    if args.doc_format == DocFormat.auto:
+        formats = [DocFormat.man, DocFormat.pandoc, DocFormat.markdown, DocFormat.system]
+    else:
+        formats = [args.doc_format]
 
-    md = importlib.resources.read_text("mkosi.resources", "mkosi.md")
-    page(md, args.pager)
+    while formats:
+        form = formats.pop(0)
+        try:
+            if form == DocFormat.man:
+                with importlib.resources.path("mkosi.resources", "mkosi.1") as man:
+                    if not man.exists():
+                        raise FileNotFoundError()
+                    run(["man", "--local-file", man])
+                    return
+            elif form == DocFormat.pandoc:
+                if not shutil.which("pandoc"):
+                    logging.debug("pandoc is not available")
+                with importlib.resources.path("mkosi.resources", "mkosi.md") as mdr:
+                    pandoc = run(["pandoc", "-t", "man", "-s", mdr], stdout=subprocess.PIPE)
+                    run(["man", "--local-file", "-"], input=pandoc.stdout)
+                    return
+            elif form == DocFormat.markdown:
+                md = importlib.resources.read_text("mkosi.resources", "mkosi.md")
+                page(md, args.pager)
+                return
+            elif form == DocFormat.system:
+                run(["man", "mkosi"])
+                return
+        except (FileNotFoundError, subprocess.CalledProcessError) as e:
+            if not formats:
+                if isinstance(e, FileNotFoundError):
+                    die("The mkosi package does not contain the man page.")
+                raise e
 
 
 def expand_specifier(s: str) -> str:

diff --git a/mkosi/config.py b/mkosi/config.py
index 95e526e1a5148755c5ecc5aef853a5e6f7537217..b5d7ee460eb2e2a9ef0cf935274752eafcaabe65 100644 (file)
--- a/mkosi/config.py
+++ b/mkosi/config.py
@@ -107,6 +107,14 @@ class Compression(StrEnum):
         return self != Compression.none
 
 
+class DocFormat(StrEnum):
+    auto     = enum.auto()
+    markdown = enum.auto()
+    man      = enum.auto()
+    pandoc   = enum.auto()
+    system   = enum.auto()
+
+
 def parse_boolean(s: str) -> bool:
     "Parse 1/true/yes/y/t/on as true and 0/false/no/n/f/off/None as false"
     s_l = s.lower()
@@ -611,6 +619,7 @@ class MkosiArgs:
     genkey_common_name: str
     auto_bump: bool
     presets: list[str]
+    doc_format: DocFormat
 
     @classmethod
     def from_namespace(cls, ns: argparse.Namespace) -> "MkosiArgs":
@@ -1717,6 +1726,12 @@ class MkosiConfigParser:
             default=[],
             help="Build the specified presets and their dependencies",
         )
+        parser.add_argument(
+            "--doc-format",
+            help="The format to show documentation in",
+            default=DocFormat.auto,
+            type=DocFormat,
+        )
         parser.add_argument(
             "--nspawn-keep-unit",
             action="store_true",

diff --git a/mkosi/resources/mkosi.md b/mkosi/resources/mkosi.md
index 2f0b889a72f68e000fc49d8a8c74293f2c3a6a09..1bb74bcb008d3af5017cd6292dd4c5d1b61fcae0 100644 (file)
--- a/mkosi/resources/mkosi.md
+++ b/mkosi/resources/mkosi.md
@@ -124,7 +124,14 @@ The following command line verbs are known:
 
 `documentation`
 
-: Show mkosi's documentation.
+: Show mkosi's documentation. By default this verb will try several ways
+  to output the documentation, but a specific option can be chosen with
+  the `--doc-format` option. Distro packagers are encouraged to add a
+  file `mkosi.1` into the `mkosi/resources` directory of the Python
+  package, if it is missing, as well as to install it in the appropriate
+  search path for man pages. The man page can be generated from the
+  markdown file `mkosi/resources/mkosi.md` e.g via
+  `pandoc -t man -s -o mkosi.1 mkosi.md`.
 
 `help`
 
@@ -201,6 +208,18 @@ Those settings cannot be configured in the configuration files.
   dependencies are built. If not specified, all presets are built. See
   the `Presets` section for more information.
 
+`--doc-format`
+
+: The format to show the documentation in. Supports the values `markdown`,
+  `man`, `pandoc`, `system` and `auto`. In the case of `markdown` the
+  documentation is shown in the original Markdown format. `man` shows the
+  documentation in man page format, if it is available. `pandoc` will generate
+  the man page format on the fly, if `pandoc` is available. `system` will show
+  the system-wide man page for mkosi, which may or may not correspond to the
+  version you are using, depending on how you installed mkosi. `auto`, which is
+  the default, will try all methods in the order `man`, `pandoc`, `markdown`,
+  `system`.
+
 ## Supported output formats
 
 The following output formats are supported: