Documentation Standards

Proposal for new Documentation Guidelines (2014)

• author: @tylerjreddy
• link to issue: ?

As set out in the Style Guide, we are moving the MDAnalysis documentation to match the formatting standards adopted by numpy / scipy as described in the documentation standard. Much of the scientific Python community adopts this standard (numpy / scipy / scikit) and matplotlib appears to be moving in this direction as well with MEP10. Arguably, new MDAnalysis users from the scientific Python community would appreciate documentation that is consistent with other major scientific libraries, and this format seems to work quite well.

There's a lot to be said for clear and concise documentation--it can save the users and developers time and attract new users (and eventually developers). It's quite nice to be able to google a function or class and obtain a single clear page with its documentation in a familiar format.

The format generally involves a single class / function per documentation page, with example usage strongly encouraged (see, for example: scipy.spatial.ConvexHull). The order and formatting of sections is perhaps best understood by looking at the example provided in the numpy documentation standard. In general, we want to avoid large / bloated documentation pages with several different functions / classes. If appropriate, common classes and functions can be associated in a summary table as shown for scipy.spatial.distance.

There are certainly some points to dicuss: 1) will we adopt a strict doctest format for examples in docstrings (not meant to replace unit tests)? 2) Will we adopt the numpydoc Sphinx extension? This would be needed for a more precise match to the numpy documentation standard. 3) other issues?

While I've tried to be reasonably consistent in my recently-added modules (i.e., 3D streamplot), I'm also guilty of cutting corners in a few of the formatting areas. The idea is to make changes that provide increased consistency with the numpy documentation standard if you stumble across a module that you think could use enhanced documentation.