Skip to content

Documentation Overhaul

Benjamin Winger requested to merge bmwinger/portmod:manpages into master

Fixes #313 (closed).

We'll need multiple manpages, and I'm not entirely sure how to handle this, as sphinx seems to just generate the one. We may be able to structure them in separate directories and then manually rename the man pages after generating each one (it's just generating the portmod.1 page. I'm not sure how to configure this).

manpages:

  • portmod.1 (CLI)
  • inquisitor.1 (CLI)
  • portmod.3 (APIdoc)
  • portmodlib.3 (APIdoc)
  • pybuild.3 (APIdoc)
  • portmod.5 (various files associated with portmod (config files and profile files))
  • pybuild.5 (maybe? pybuild file format spec. Or should this be in pybuild.3?)

I'm thinking of using https://github.com/ashb/sphinx-argparse to generate the documentation for the CLI. There's also https://pypi.org/project/sphinx-argparse-cli, but that doesn't support python3.6.

TODO:

  • Move documentation related to portmod itself from the wiki into rst manpages in the doc directory.
  • Add CLI documentation generator
  • Generate manpages as part of setup.py (should be optional though) and include them in macOS/Linux wheels (if possible. It should be, but I seem to recall that it goes against the spec to install arbitrary files outside of the package directory like this).

Sphinx's generator produces both a Makefile (which I've modified to generate the APIdoc) and a make.bat for Windows. I'm leaving the make.bat file for now since we may also want to eventually generate documentation on Windows for use with the GUI. There may also be other documentation options that sphinx supports which would suit windows users (e.g. we could produce pdf documentation).

Edited by Benjamin Winger

Merge request reports