[WIP] Sphinx

[OndrejMarsalek]

Work in progress, do not merge.

This adds documentation in Sphinx. The idea is to combine both hand-written and automatic documentation to replace the LaTeX manual. If a PDF is needed, Sphinx can render to LaTeX, too.

[OndrejMarsalek]

Before doing this for too many source files, we should decide on a docstring style that will go well with Sphinx. There are now several different options shown in atoms.py. Also, here is an example of "Sphinxy" and "Googley" styles:

https://pythonhosted.org/an_example_pypi_project/sphinx.html

I don't have a strong preference, as long as it is clear and readable.

[OndrejMarsalek]

I made some progress on the new documentation. The current version should showcase some of the features of Sphinx that we want to use. The text is very much placeholder at the moment and subject to change. I just want to get all the infrastructure in place before we start moving text from the LaTeX documentation or adding more.

I rolled back to changes to atoms.py, but also enabled the Napoleon extension, which should add RST formatting to reasonably human plain text. We might still need to tweak the docstrings a bit to conform to one of the two supported conventions (Google or Numpy), but it looks like we are already almost there. In any case, it will be nowhere near as much editing as making them RST by hand.

To illustrate what the autogenerated documentation could look like, I included two modules. Once it is clear that and how exactly we want to proceed, it is easy to add the rest. There are some options to fine-tune what exactly gets generated.

I have tested that both the HTML and LaTeX builds of the documentation work. You can get them simply by doing make html or make latex in the doc-sphinx directory. Dependencies should be easily installed in whatever way you like to install Python packages, pip if nothing else. You can find the output in the _build subdirectory. Open HTML directly, LaTeX still needs to be compiled, for which there is a generated make file. Just run make.

I could upload the generated HTML and PDF files somewhere, but that gets clumsy very quickly with edits and trying out things. In the future, we can use Read the Docs to generate and host the HTML documentation, but that requires a public repository.

I think the last piece that needs to be added is the input file documentation, but I think it should be easy to adapt the current code that write LaTeX source to write RST files.

What do you think?