Documentation feedback

[patmarion]

[ this comment is copy & pasted from here https://github.com/RobotLocomotion/director/pull/120#issuecomment-157953280 ]

I added a new layout for sphinx documentation. Sphinx is a tool that generates static html files from restructured text files (.rst file extension). Most of the rst files I added are stubs, but please have a look and let me know what you think. Everything is in docs/sphinx. Here is what the output looks like:

http://openhumanoids.github.io/director/

Please let me know whether or not you think it's a good idea to use the github.io url. I put it there for now since it was easy.

If you want to generate the html documentation yourself, it's quite easy once you have sphinx installed. On ubuntu I installed sphinx with:

sudo pip install sphinx sphinx-rtd-theme

You can generate sphinx documentation with:

cd director/docs/sphinx
make html

# view the result
firefox _build/html/index.html

To make sphinx documentation that includes the python module auto documentation, you need to run these two commands:

cd director/distro/pods/drc/pod-build

make docs-sphinx-generate
make docs-sphinx-build

The docs-sphinx-generate target will generate module rst files in docs/sphinx/generated. If you run make html then you will get a bunch of import errors because sphinx doesn't know how to import the director modules to generate documentation, that's why you need to run the docs-sphinx-build command as written above.

[patmarion]

Note, I copied the keyboard shortcut documentation from the .md file to .rst. You can see the result here:

https://github.com/RobotLocomotion/director/blob/master/docs/sphinx/user_guide/keyboard_shortcuts.rst

And here is the result rendered in static html (readthedocs theme):

http://openhumanoids.github.io/director/user_guide/keyboard_shortcuts.html

I propose that we delete the .md files and do everything in restructured text.