Documentation in Sphinx?

[OndrejMarsalek]

Do we at some point want to transition to having the documentation in Sphinx? I think it would be a good idea. It allows the mixing of automatic and hand-written documentation and supports nice math. Multiple output formats are also useful, with HTML and PDF being probably most important for us.

http://sphinx-doc.org/

Some example of projects that use it:

https://wiki.fysik.dtu.dk/ase/
https://wiki.fysik.dtu.dk/gpaw/
http://ipython.org/
http://matplotlib.org/

[joshmore]

I've never used Sphinx before, so I'm not sure exactly how much work that would be. In the early stages of development we did try using doxygen, but the output ended up about 80 pages long and not really particularly helpful, so at the moment I'm a bit wary of automatic documentation generators. Also, for a documentation package I'm finding a quick read of its own documentation to be rather unhelpful.

On the other hand, I really like the idea of having properly formatted math symbols, since some of the help strings look ugly without it. Also, having some documentation of the class structure would probably be very helpful, since there are bits that aren't explained in the current manual.

I think I might be interested in trying this, as long as it doesn't require a huge amount of effort, since it occupies a useful middle ground between the overview of i-PI given in the manual and the function by function docstrings in the source code. I probably need to know a bit more about exactly how Sphinx works though before I try anything.

[OndrejMarsalek]

I think we need to distinguish the automatic documentation generated based on source files and hand-written documents. With Sphinx, they can sit integrated in one website, but don't have to be related too much.

I think the advantage is that you get all the automatic stuff basically for free and better than with Doxygen - Sphinx is designed for Python specifically.

I can prepare a skeleton, say in 'doc-sphinx' and try to set up the automatic stuff. Then we can have a better look together and see what it would take to convert the manual. Would that work?

[joshmore]

Sounds good, I have always liked the look of the online Python documentation, and if we could get something similar I think it would be a huge help to users. It probably won't even be all that much work, most of the words have already been written, and so it should just be a case of creating files to partition what's already there.

I did download Sphinx myself and try to run it, but it would save a large amount of time if you did some of the scaffolding yourself since I'm currently just learning by trial and error.

One thing though, I'll probably be dividing my attention between this and a paper I need to write over the next few weeks, so I might be a little slow in contributing in the meantime.

[OndrejMarsalek]

Sorry about the long silence, too many things that require my attention. I have tried the automatic documentation and I think it works reasonably well, but might need some formatting of the doc strings so that they render nicely when taken as rst. I will make a separate branch for this so that we can have a look at it before deciding whether we want to convert the whole manual. I will try to set up a hook to this service:

https://readthedocs.org/

so that we don't have to recompile locally all the time.

[ceriottm]

I have recently seen the documentation for plumed 2
http://plumed.github.io/doc-v2.0/user-doc/html/index.html
This is done in doxygen. I have to admit it does look very nice, and that documentation in sphinx tends to look even nicer. @joshmore have you decided what to do here?

[jhrmnn]

another free meal from sphinx is that one can host the docs at https://readthedocs.org

[OndrejMarsalek]

I will try and revive my proposal for Sphinx soon.

As far as I know, Doxygen is rather clumsy for Python when it comes to extracting documentation from the code itself, which is one of the main points for Sphinx.

As I said, Read the Docs is indeed useful. It seems, however, that at least for now, it does not work with private repositories, so this might be something to get back to later, after we release a new version.

[OndrejMarsalek]

Some progress in #39.