Documentation Overhaul
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 inpybuild.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 thedoc
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).