Automate generation of documentation/manpages

[masc3d]

could probably be implemented and integrated into setup.py using classes attached to this issue or another solution would be to use sphinx.

[syntonym]

I've played a bit with sphinx and sphinxcontrib.autoprogram which convertes the argparse parser to rst. You can take a look at it here. There is a bit boilerplate for multiple man pages, which means when a new command is added, one would have to modify that. Alternativly one could simple put everything on a single man page, personally I didn't find that as useful/easy to read.

I've also exported to HTML, but I don't know if you want some docs in html format.

[masc3d]

If it can be fully automated, eg. including the conf.py it will be good.
The switches seem to be missing from the rsts, but I do like the idea and basic setup.

if you can provide a fully functional and automated integration with setup.py I will certainly merge this.

[syntonym]

Do you mean that the documentation is automatically build when a user installs the package locally? Or that you don't have to care about the documentation, i.e. it is automatically build whenenver some change happens, and a user only needs to install the documentation (which is done via the setup.py script)? In the first case sphinx would be a hard requirement, which sounds rather bad.

What exactly do you mean with "including the conf.py"?

I will implement what I think makes sense and then you can take a look.

[masc3d]

I meant conf.py could probably also be generated, so that the entire mechanism only depends on argparse and integrates with setup.py.

I'm using python3 setup.py sdist upload for releasing a new version and it would be great if all docs, manpages etc. would be generated and included in the distribution in the process.

[syntonym]

What about sphinx and sphinxcontrib.autoprogram as dependencies (for building the docs, ofcource not for endusers)? I guess the logic isn't too complex and could be extracted into a separate script, but if in the future anything should change sphinx has lots of features and is well documented.

[masc3d]

I don't see an issue with adding deps to the build toolchain

[syntonym]

I can't really find a way to install man pages when installing via pip. I think pip transforms to wheels and wheels no longer can install to arbitrary locations. When packaged for package managers for distributions these could install the manpages. Do you still want to merge?

[masc3d]

never tried it. does this restriction apply even when installing with sudo/root?

[masc3d]

I have seen pip packages which install man pages, so there has to be a way. It has been discussed here eg..

[syntonym]

Hm, you are right. This issue says that wheels can't handle absolute data files and the changelog of pip says "Build Wheels prior to installing from sdist, caching them in the pip cache directory to speed up subsequent installs. (PR #2618)". But installing one of the examples you linked via pip installs the man pages, so I guess something changed. Sorry for that.

[masc3d]

Merged into master, thanks!