From 4040197ac87e2307cfaf0e1ba333756e38c4b821 Mon Sep 17 00:00:00 2001 From: Joerg Behrmann Date: Wed, 9 Aug 2023 15:48:47 +0200 Subject: [PATCH] add --doc-format option for choosing the output of the documentation verb --- NEWS.md | 15 +++++++-------- mkosi/__init__.py | 41 +++++++++++++++++++++++++++++++++------- mkosi/config.py | 15 +++++++++++++++ mkosi/resources/mkosi.md | 21 +++++++++++++++++++- 4 files changed, 76 insertions(+), 16 deletions(-) diff --git a/NEWS.md b/NEWS.md index be5bfd9f1..b4ae8369f 100644 --- 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 ea7466286..abe7c9ed9 100644 --- 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 95e526e1a..b5d7ee460 100644 --- 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 2f0b889a7..1bb74bcb0 100644 --- 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: -- 2.47.2