Missing documentation (formats): man pages / lxd.readthedocs.io PDFs

Given that the “lxd” snap package (still) does not come with man pages, is it possible to either put some in a separate package (lxd_<version>-man.deb) or, as a workaround, include them in some non-standard, but documented directory with said snap package? I’d rather manually modify the MANPATH than face the dreaded “No manual entry for …” every time.
I for one do not consider the brief “lxc <command> --help” outputs much of an alternative (those, e.g., come w/o “See also:” references and do not cover what you’d expect from the different man page sections). Of course, writing detailed man pages requires a lot of effort, but this shouldn’t be a reason to not at least start with some stubs…

Also, lxd.readthedocs.io does not allow you to download a single PDF file (zipped HTML only). Is it possible to add this option? It’s much easier to handle/annotate the former format using, e.g., an Android tablet.

1 Like

ReadTheDocs is supposed to autogenerate PDF files as well.

Here is the URL for the PDF version, http://media.readthedocs.org/pdf/lxd/latest/lxd.pdf
However, that PDF only has 5 pages and is from 2016. Something is wrong there.
Looking further, http://readthedocs.org/projects/lxd/downloads/ shows that there are ZIPed HTML packages that are also from 2016. As if those offline packages are not auto-updated at all.

Something is wrong here. The online HTML pages are generated correctly upon each commit.
However, the ZIP of the HTML files and the PDF are not generated since 2016.
But since the online HTML pages are generated successfully, there there should be some other issue at play here.

Yeah, we disabled PDF exports on readthedocs because the output is broken for some reason and there’s not much that us, as users of their service can do about it.

As for manpages, the .deb manpages were auto-generated from those --help output so it doesn’t really seem worth trying to re-introduce that in the snap package.

You can manually run lxc manpage if you want those auto-generated manpages dumped into a path of your choice though.

The HTML ZIP files do not appear to be generated either.

See http://readthedocs.org/projects/lxd/downloads/

The ZIP files

  1. have individual files with timestamp in 2016, that is they have not been updated since then.
  2. there is no content in those ZIP files. They are 1.8MB ZIP files, which is mainly the fonts.

FYI, as a temporary workaround for the second issue, I’ve written a quick and dirty script which downloads the individual HTML files and generates PDF files locally; see https://gist.github.com/m-ueberall/b1e6e3a4dfe8b615fd137768a0aeb19c

(A cleaner solution would be to actually use the .md files from https://github.com/lxc/lxd/tree/master/doc, but this requires more effort. Who is going to come up with the first script for this? :grin:)