Reader + Topology doc structure

[richardjgowers]

So currently our documentation tree closely follows the source code layout, so we have a coordinates and topology page off the main page. I think this is pretty useless as most people will never actually have to interact with either of these modules to load their stuff, but it seems like a natural option if you have never used the package before.

Could we merge these two (at a documentation level) so our doc tree would look like:

Mainpage
    + MDAnalysis overview (current introduction)
    + How to read your files (general discussion of the arguments of Universe)
        + Reading Gromacs files (information particular to this particular MD format)
            + topology.GROParser  (if you're reaaallly interested in how this is implemented, go see the details)
            + coordinates.GROReader
            + coordinates.XDRReader
        + Reading Lammps files
        + etc for each format
    + Selection commands

I think this will better match what people expect.

This will require more documentation to live outside of the .py files and instead in .rsts, but apart from that I can't really see a problem. I guess the line being that .py documentation is for developer/people playing with internals, .rst is for people just wanting to use MDA.

Unless anyone sees a big problem with this I'll start working on this in a couple days.

[orbeckst]

Makes sense to me.

Ultimately, splitting the docs into "intro/user" and "developer/API" would be good (#1175) but I think we could take your structure and put the "inner" parts into the API docs when we get to a big doc restructuring.

Regarding topology docs: The thread https://groups.google.com/d/msg/mdnalysis-discussion/DCJzYzBbDJI/xUiqyAdfBQAJ could be a good starting point for an example using Universe.empty().

[orbeckst]

See also #1845 : how to include docs for methods that only come into existence if the appropriate TopologyAttr is present. (Is this magic explained somewhere?)