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 .

[orbeckst]

Although this could go into a patch level, I am retargeting to 0.17.0 so that we can focus on fixing bugs for 0.16.1.

[orbeckst]

Should perhaps also include #360

• update formats tables with the appropriate keyword value for format or topology_format
• user docs on "how to read different file formats into MDAnalysis"

Also see discussion there regarding user/developer docs.

[orbeckst]

More for the wish list: system building

• creating new segments (see also segments object isn't properly documented. #1105 and @richardjgowers how-to Hydrogen bond analysis exits with AttributeError: 'list' object has no attribute 'select_atoms' #1268 (comment) )
• adding atoms/residues
• deleting parts of a system
• merging AtomGroups and creating a new Universe (even with trajectory: see MemoryReader docs)
• using Universe.empty() (see e.g. https://groups.google.com/d/msg/mdnalysis-discussion/DCJzYzBbDJI/xUiqyAdfBQAJ) (EDIT)

[orbeckst]

More from other issues with the Component-Docs tag: All along the lines of How to add new properties to an AtomGroup

• adding bfactors = temperaturefactors Set b-factor for PDB file #1359
• adding occupancies attr aren't added correctly to existing AtomGroups. #1092
• adding charges (to build PQR files)

Although this is advanced stuff, we could start putting it into the currently very, very thin section The topology system, at least for a start.

[orbeckst]

A while back @tylerjereddy suggested to do separate pages for classes. Apparently, something like this can be automated with sphinx's autosummary directive.

[orbeckst]

Doc rewrite is not going to happen for 0.17.0 – I am moving it down.

[orbeckst]

More docs todo on loading trajectories:

• describe Universe properly (include the trajectory argument in the docs!!), and all the ways in which trajectories can be loaded (ChainReader can take lists, lists of tuple (name, format))
• clarify memory reader (see change timeseries "format" kw to "order" #1453 (comment) )

[orbeckst]

Update docs on selections

• groupselections: syntax, example, see https://groups.google.com/d/msg/mdnalysis-discussion/ZEuJ5wPPLs4/mDlZyqN9BwAJ
• update examples
• geometric selections (especially with PBC)

[orbeckst]

https://github.com/astropy/sphinx-automodapi looks interesting (see the automodapi docs): it can automatically create the complete API docs for a whole package. Might be useful once we really split the docs in

• introductory
• API
• developer docs

There's also the sphinx.ext.autosummary extension.

[orbeckst]

Docs on extending topologies (thanks to #363)

• adding "known" attributes such as "bfactors", see MDAnalysisTutorial: Coloring by B-factor or Workshop 2018: introduction_MDAnalysis.ipynb: Visualization where we add all attributes that would be present in a PDB file.
• adding custom attributes
• adding custom methods

[orbeckst]

Google launched Season of Docs – this issue looks like a suitable starting point for a tech writer who would want to work with MDAnalysis.

[orbeckst]

@lilyminium with your GSoD project, this is your area :-)

[richardjgowers]

I'm gonna say @lilyminium has done this