Sphinx docs

This PR might be for Jenny.

This branch is my exploration into what's involved with including some of the Confluence documentation into the Sphinx documentation. I also took the opportunity to eyeball the Sphinx docs we've got, and wrap the longer lines so that they're easier to read in an editor (which is how I usually read docs in the codebase I'm working with -- a browser is nice, but your IDE is right there -- and reStructuredText is really cool for that, because it's such a readable markup).

So, some feedback on importing docs from Confluence. Here's how I did it:

  1. Open Confluence page you want to import.

  2. Click Tools, and choose View Source.

  3. Right-click, choose "Save Page As...", and save the page as an HTML document locally.

  4. In a terminal, convert to reStructuredText with pandoc:

        $ pandoc -f html -t rst my_doc.html > my_doc.rst

That's it. I found that pandoc gets most things right, but it's rubbish at tables. It just puts each cell in a new paragraph. So tables are time consuming.

Also code literals seem to be converted to single-cell tables. So you need to put in the "::", and remove the block, but that's not too bad.

In conclusion, importing the public documentation from Confluence is going to take more than half an hour, but it should be doable in four to eight (depending on those tables).

Personally, I like the idea of having the documentation with the code -- it's a little easier to keep them up-to-date together -- and code changes that affect docs can be tracked the same way with GitHub. But I'm new, and I'll defer to your opinions. :-)


cool, that does sound like a good plan.