Find or write a plugin to generate rST from --help

[ssokolow]

Sphinx can generate man pages and has markup roles for the stuff optparse generates for --help.

So far, I haven't been able to find a --help-to-Sphinx plugin so, when time permits, I need to take the --help-to-manpage script I found a while ago and adapt it into a Sphinx plugin.

[wolph]

What I do in some of my projects is simply include the output of app --help in my readme.rst, works pretty ok :)

Here's an example: https://github.com/WoLpH/zfs-utils-osx/blob/master/README.rst

[ssokolow]

That does look surprisingly nice... but, before I can feel satisfied enough doing the same to consider this resolved, I'll need to:

1. Verify that the approach taken can guaranteed continued niceness. (eg. add escaping as necessary)
2. Learn enough about Sphinx's internals to write a plugin to do that automatically whenever the docs are built.

[wolph]

It's not a 100% solution, just look at the -t parameter, but it certainly beats having nothing at all :)

A little bit of googling revealed sphinx-argparse (https://sphinx-argparse.readthedocs.org/en/latest/index.html) which might do the trick, or perhaps sphinxcontrib.autoprogram (https://pythonhosted.org/sphinxcontrib-autoprogram/)

Can't say I've tested either, but I might do that soon. Better docs are always useful, the big problem is that I generally want to have the basic usage/parameters in the main readme so it's on Github as well. This makes it a bit hard to automate properly...

[ssokolow]

Either of these approaches would work:

1. Have separate master and master-staging branches and give Travis the exclusive responsibility for moving commits from master-staging to master if the tests pass.
2. Use a single master branch and have Travis set some git metadata on the commits it makes so it knows they've already been tested and doesn't get into an infinite commit_hook_triggered->test->push_new_commit loop.

In the process, it could commit an updated README.rst, either generated from a README.rst.in or by using replacement markers that are also valid rST, machine-recognizable as "cut from here to there to remove stale output". Something equivalent to html like this:

<pre myext:capture="fastdupes --version">Find Dupes Fast v0.3.6</pre>

I actually ran across an article long ago which explains how to automate testing and output capture for in-article code snippets using a mix of Sphinx, Paver, and Cog.

[wolph]

Are you sure it's safely possible to let Travis mutate the repo? As far as I know all of the travis configs are public so it would effectively allow everyone to write to the repo.

[ssokolow]

http://docs.travis-ci.com/user/encryption-keys/

...and an example of how to use it to implement ReadTheDocs-like automation for rustdoc: https://github.com/kmcallister/travis-doc-upload/blob/master/README.md

Basically, you create a deploy key (GitHub's term for an SSH key that allows access to only a single repository) and then you use Travis's encryption support to store it in .travis.ymlin a way that only the Travis buildbots can decrypt.

[wolph]

That's pretty awesome, I'll have to look into that. Would be great to have fully automated pypi releases and such. Guess I haven't been keeping track of Travis enough...