Repository: systemd/mkosi

Issue:
Include man page in Python package
When building the man page with
```
pandoc -t man -o mkosi.1 mkosi.md
```
the output looks rather unpleasing:
```
mkosi  ‐  Build  Legacy‐Free  OS  Images mkosi [options...] build
mkosi [options...] clean mkosi [options...]  summary  mkosi  [op‐
tions...]  shell [command line...]  mkosi [options...] boot [com‐
mand line...]  mkosi [options...] qemu mkosi is a tool for easily
building  legacy‐free OS images.  It’s a fancy wrapper around dnf
‐‐installroot, debootstrap, pacstrap and zypper that may generate
disk  images  with a number of bells and whistles.  The following
output formats are supported: Raw GPT disk image,  with  ext4  as
[...]
```

We should fix that and maybe generate the man page automatically via a commit hook, so that the man page can be included (and installed) when doing a pip install.


Discussion:
This was tested with pandoc 2.9.2.1 on Arch.
That was easy. Adding `-s` fixes it, see jgm/pandoc#6521.
Can we not just generate the man page on demand when installing?
Not with pandoc, that's not guaranteed to be installed and it's also a rather heavy dependency just for a man page.
Commit hooks seems a bit heavy for the amount of contributors we have. I think we can get by if we just include the man page in the repo and tell contributors to regenerate it if they update mkosi.md. 

I do eventually want to get back to doing stable releases which should alleviate the dependency problem a bit as distros will generate it for the user.
I do remember when first installing mkosi from the AUR on Arch that I was extremely annoyed that I had to install more than 200 haskell dependencies to get the docs so I get where you're coming from. 

Resolving patch:
diff --git a/mkosi/__main__.py b/mkosi/__main__.py
--- a/mkosi/__main__.py
+++ b/mkosi/__main__.py
@@ -6,18 +6,23 @@
 from . import parse_args, complete_step, run_verb, die, MkosiException
 
 
-try:
-    args = parse_args()
+def main() -> None:
+    try:
+        args = parse_args()
 
-    for job_name, a in args.items():
-        # Change working directory if --directory is passed
-        if a.directory:
-            work_dir = a.directory
-            if os.path.isdir(work_dir):
-                os.chdir(work_dir)
-            else:
-                die(f"Error: {work_dir} is not a directory!")
-        with complete_step(f"Processing {job_name}"):
-            run_verb(a)
-except MkosiException:
-    sys.exit(1)
+        for job_name, a in args.items():
+            # Change working directory if --directory is passed
+            if a.directory:
+                work_dir = a.directory
+                if os.path.isdir(work_dir):
+                    os.chdir(work_dir)
+                else:
+                    die(f"Error: {work_dir} is not a directory!")
+            with complete_step(f"Processing {job_name}"):
+                run_verb(a)
+    except MkosiException:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -13,7 +13,7 @@ def finalize_options(self):
         pass
 
     def run(self):
-        self.spawn(['pandoc', '-t', 'man', '-s', '-o', 'mkosi.1', 'mkosi.md'])
+        self.spawn(['pandoc', '-t', 'man', '-s', '-o', 'man/mkosi.1', 'mkosi.md'])
 
 
 setup(
@@ -27,5 +27,6 @@ def run(self):
     python_requires=">=3.6",
     packages = ["mkosi"],
     cmdclass = { "man": BuildManpage },
-    entry_points = {"console_scripts": ["mkosi=mkosi.__main__"]},
+    data_files = [('share/man/man1', ["man/mkosi.1"])],
+    entry_points = {"console_scripts": ["mkosi=mkosi.__main__:main"]},
 )


Test patch: