Add documentation for shed install and run-data-managers

[rhpvorderman]

Hi there.

Run-data-managers.rst and shed-install.rst are very boring on purpose. It took me a while to set it up right, but it might be useful to use them as templates for further documentation.

One of the tricky bits is a nasty dependency thing in sphinx. We need sphinx-argparse for this functionality but this starts a conflicting dependency where recommonmark needs commonmark<0.5.4 and commonmark needs to be at >0.5.6 for sphinx-argparse.

At first I fixed it in the ugly way but I found that sphinx-argparse 0.1.17 works. Which fixes the dependency hell.

In order to be imported by read the docs, the virtualenv option must be selected and the requirements file is doc/requirements.txt.

[bgruening]

@rhpvorderman you introduced a few pep8 linting errors. Can you check this please? Thanks a bunch for these contributions!

[rhpvorderman]

Fixed the errors. These settings need to be enabled on read the docs:

To see how the automated documentation works out, I made a test repo at readthedocs which I will remove when this request is pulled. Check the documentation and specifically the commands section at: http://ephemeris-test.readthedocs.io/en/add_documentation/

Documenting other functions is easy now:

1. Go to the source file and:
   • Add a docstring that gives general information about the module. (Examples in shed-install and run-data-managers)
   • Create a new _parser() method that returns the argument parser.
2. Create a new rst file using shed-install.rst or run-data-managers.rst as a template.
3. Reference the new rst file in commands.rst

To build your documentation to check out how it works before submitting the pull request:

1. Install sphinx in a virtual environment by running pip install -r docs/requirements.txt from ephemeris root
2. go to the docs directory and run make html

[jmchilton]

Is it worth just dropping recommonmark for now - I was using that in Planemo but I don't think we use it here yet?

[rhpvorderman]

There is no need to drop it, seeing as argparse 1.17 works fine for what is done with it in ephemeris. Currently I do not have the time to dive a lot deeper into sphinx and documentation. The requirements file and conf.py can always be changed at a later point in time.

[jmchilton]

@rhpvorderman Fair enough - thanks for the contribution!

[bgruening]

Wonderful. Thanks for your work here. Do you mind to submit your write readme documentation to https://github.com/galaxyproject/ephemeris/blob/master/CONTRIBUTING.rst

[jmchilton]

I redid the requirements file a bit to reduce duplication with https://github.com/galaxyproject/ephemeris/commit/684d2bcac33c3a2c98432752c71115474e3f7d34, updated our settings, and the new docs are live at https://ephemeris.readthedocs.io/en/latest/! 🎆

Thanks so much for new docs @erasche and @rhpvorderman !