Create manpages

As discussed in the 2022-02-02 meeting minutes, manpages are a desirable usability improvement for these tools. While Python's argparse package automatically provides useful --help output, it does not provide man pages.

In addition to executables, configurations should also contain section 5 manpages. This may require coordination with #27 (closed).

Find a method of creating/maintaining manpages that gives maximum maintainability/least effort.

changed the description

I took a quick look around to see if the Python ecosystem has anything less kitchen-sink than Sphinx but I didn't really find anything. I'm partial to the simplicity of scdoc where manpages can be created extremely simply. For instance:

json2db(1)

# NAME

json2db - Read a repository database and write all contained pkgbases to one JSON file each.

# SYNOPSIS

*json2db* [options...] db_file output_dir

# EXAMPLES

*-f, --files*
	Create a _.files_ database instead of a _.db_ database

*-h, --help*
	Show help message and quit.

*-v, --verbose*
	Verbose output.

# SEE ALSO

db2json(1)

# AUTHORS

Maintained by Arch Linux contributors.

Written in minutes with the extremely simple scdoc(5) manpage and generated with a simple scdoc < json2db.sc.

But the comprehensiveness of Sphinx can also be attractive. Are there any preferences?

We could just start out with scdoc and implement the full-blown Sphinx experience if it becomes tiresome to maintain.

I'm not saying it's the best option, but we use sphinx in archinstall: https://github.com/archlinux/archinstall/blob/f6d133804b7fdfab5a00d95a1985c3e220935ac1/PKGBUILD#L20

The benefit to it would be that we could generate manpages and API/tool documentation in HTML from the same source. It's a nice way to both get manpages and https://archinstall.readthedocs.io/ for instance from the same blob.

Hm, I would probably also tend towards a make target for the man pages that uses sphinx then (the reasoning here being, that we would not have disconnected python argparse help and man pages - no sync effort required).

@torxed can you elaborate a bit on what is needed in addition for sphinx to create man pages for the entrypoints in our case?

(also opening another ticket for auto-deploying documentation somewhere)

Sure, I'm not an expert which is clear from the latest generated manpage for archinstall (https://man.archlinux.org/man/archinstall.1). However, what you want to do is:

Add a requirement to the sphinx configuration: extensions += ['sphinxarg.ext'] And then add a .rst entry called arguments.rst or something similar in docs/arguments.rst.

.. argparse::
   :module: arch-repo-management
   :func: process_arguments

Have the docs/conf.py point towards it as the manual page:

man_pages = [("arguments", "arch-repo-management", u"arch-repo-management Documentation", [u"David Runge"], 1)]

And create a function for the initial setup of the arguments:

def process_arguments() -> parser:
    parser = argparse.ArgumentParser()
    parser.add_argument("verbose", action="store_true", default=False, help="Enables verbosity")

    return parser

That should make sphinx auto-generate the list of arguments in a nice "manpage" friendly way. I currently have it configured to read index.rst.

Note: I wrote most of this without actually testing it, it's something like this I've done in the past.

mentioned in issue #36 (closed)

added scopedocumentation label

changed milestone to %0.1.0

marked this issue as related to #65 (closed)

assigned to @ainola

For a dedicated man page setup, I believe khal is a good reference: https://github.com/pimutils/khal/blob/dc6d5a105b613a22283f46a41920b98346d8b0d6/doc/source/conf.py#L278-L281 for conf.py and https://github.com/pimutils/khal/blob/dc6d5a105b613a22283f46a41920b98346d8b0d6/doc/source/man.rst for the dedicated index page (we should put this in a subdirectory below docs/).

I was looking at sphinx itself, which has a man subdir: https://github.com/sphinx-doc/sphinx/blob/5.x/doc/man/sphinx-apidoc.rst

So far, my idea would be to create RST files for db2json/json2db under there but also have a section 5 manpage that could re-use the contents of documentation for the configuration of repod.

Just a heads up: json2db and db2json are superseded by repod-file with !66 (merged)

mentioned in merge request !70 (merged)

closed with merge request !70 (merged)