make mkosi docs from resources available via the documentation verb

This allows, especially when running different versions of mkosi, to always
have the right documentation on hand no matter how that version of mkosi was
installed.

diff --git a/mkosi/__init__.py b/mkosi/__init__.py
index 887434b04713a8ec4ff45245487da4051e1ba1b5..ea74662869eb7a5e57b3674efbf1abab6b23dfc2 100644 (file)
--- a/mkosi/__init__.py
+++ b/mkosi/__init__.py
@@ -5,6 +5,7 @@ import datetime
 import hashlib
 import http.server
 import itertools
+import importlib.resources
 import json
 import logging
 import os
@@ -1650,6 +1651,16 @@ def bump_image_version(uid: int = -1, gid: int = -1) -> None:
     os.chown("mkosi.version", uid, gid)
 
 
+def show_docs(args: MkosiArgs) -> None:
+    with importlib.resources.path("mkosi.resources", "mkosi.1") as man:
+        if man.exists():
+            run(["man", man])
+            return
+
+    md = importlib.resources.read_text("mkosi.resources", "mkosi.md")
+    page(md, args.pager)
+
+
 def expand_specifier(s: str) -> str:
     return s.replace("%u", InvokingUser.name())
 
@@ -1684,6 +1695,9 @@ def run_verb(args: MkosiArgs, presets: Sequence[MkosiConfig]) -> None:
     if args.verb.needs_root() and os.getuid() != 0:
         die(f"Must be root to run the {args.verb} command")
 
+    if args.verb == Verb.documentation:
+        return show_docs(args)
+
     if args.verb == Verb.genkey:
         return generate_key_cert_pair(args)
 

diff --git a/mkosi/config.py b/mkosi/config.py
index 50de80fec0627cecf5fccb2931e53984cfa0d089..95e526e1a5148755c5ecc5aef853a5e6f7537217 100644 (file)
--- a/mkosi/config.py
+++ b/mkosi/config.py
@@ -46,17 +46,18 @@ ConfigDefaultCallback = Callable[[argparse.Namespace], Any]
 
 
 class Verb(StrEnum):
-    build   = enum.auto()
-    clean   = enum.auto()
-    summary = enum.auto()
-    shell   = enum.auto()
-    boot    = enum.auto()
-    qemu    = enum.auto()
-    ssh     = enum.auto()
-    serve   = enum.auto()
-    bump    = enum.auto()
-    help    = enum.auto()
-    genkey  = enum.auto()
+    build         = enum.auto()
+    clean         = enum.auto()
+    summary       = enum.auto()
+    shell         = enum.auto()
+    boot          = enum.auto()
+    qemu          = enum.auto()
+    ssh           = enum.auto()
+    serve         = enum.auto()
+    bump          = enum.auto()
+    help          = enum.auto()
+    genkey        = enum.auto()
+    documentation = enum.auto()
 
     def supports_cmdline(self) -> bool:
         return self in (Verb.shell, Verb.boot, Verb.qemu, Verb.ssh)
@@ -1622,6 +1623,7 @@ class MkosiConfigParser:
                     mkosi [options...] {b}serve{e}
                     mkosi [options...] {b}bump{e}
                     mkosi [options...] {b}genkey{e}
+                    mkosi [options...] {b}documentation{e}
                     mkosi [options...] {b}help{e}
                     mkosi -h | --help
                     mkosi --version

diff --git a/mkosi/resources/mkosi.md b/mkosi/resources/mkosi.md
index 1ebe4ed59581eed7a1b6950f2d2c831b7e4daca1..2f0b889a72f68e000fc49d8a8c74293f2c3a6a09 100644 (file)
--- a/mkosi/resources/mkosi.md
+++ b/mkosi/resources/mkosi.md
@@ -28,6 +28,8 @@ mkosi — Build Bespoke OS Images
 
 `mkosi [options…] genkey`
 
+`mkosi [options…] documentation`
+
 `mkosi [options…] help`
 
 # DESCRIPTION
@@ -120,6 +122,10 @@ The following command line verbs are known:
   `SecureBootKey=`/`--secure-boot-key=` and
   `SecureBootCertificate=`/`--secure-boot-certificate=` options.
 
+`documentation`
+
+: Show mkosi's documentation.
+
 `help`
 
 : This verb is equivalent to the `--help` switch documented below: it