Documentation Standards

Oliver Beckstein edited this page Nov 18, 2015 · 1 revision

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.

Project Information

About
GNU GPL v2 code license
Labels: python, molecular dynamics, analysis, DCD, CHARMM, LAMMPS, NAMD, Gromacs, computer simulation, atoms, coordinates, trajectory, XTC, Library, object-oriented
Core Developers

Essentials

Applications
Downloads
Install
Release Notes
Guide for Developers
Google Summer of Code

Code of Conduct

Links

@mdanalysis on Twitter
Documentation
Tutorials
Downloads (PyPi)
Mailing Lists:
User discussion group
Developer mailing list

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.