Restructure documentation for user-friendliness

[dotsdl]

The MDAnalysis documentation is structured in such a way that it contains scant information on the user interface and otherwise gives detail on the internal components of MDAnalysis that users should never really have to touch directly (parsers, readers and writers). We've seen usage on the mailing list from users in which they try e.g. to directly use a Reader object to parse a trajectory, and the docs don't make it clear that this isn't really the way to go about things.

I think the docs should be restructured to have three parts. The first part should read more like the MDAnalysis Tutorial, giving a friendly view as to how one uses MDAnalysis in practice. The second part should be an API reference, with the full sphinx autodoc output for the user interface components showed in part one. The last part should be the developer docs, which would include the reference docs for internal components, such as parsers, readers, and writers so that they are somewhere.

Thoughts?

[richardjgowers]

I liked the idea of a tiered approach, first there should be an explanation of how it works, and only after an explanation of why.

[richardjgowers]

So thinking about this, the only problem is that there is potential for the rst and py docs to diverge.

So one option would be to later implement doc testing on our first part/tutorial so that it always works as intended

http://doc.pytest.org/en/latest/doctest.html

[kain88-de]

Related I just found out that scikit-learn has a Circle-CI setup that uploads the changes for a document build. This allows a reviewer to quickly check the result and give comments without building it himself.

https://8425-843222-gh.circle-artifacts.com/0/home/ubuntu/scikit-learn/doc/_build/html/stable/_changed.html

[orbeckst]

From the scikit-learn example that @kain88-de linked I found out about http://sphinx-gallery.readthedocs.io , which allows one to make nice docs from small scripts. Maybe worthwhile looking into in conjunction with the proposed examples gallery MDAnalysis/MDAnalysis.github.io#4 .