-
Notifications
You must be signed in to change notification settings - Fork 853
WritingDocumentation
In general, we are proposing (still open to some debate) to adjust 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.
MDAnalysis has a lot of documentation in the Python doc strings. In the Python interpreter one can simply say
import MDAnalysis
help(MDAnalysis)
help(MDAnalysis.Universe)
In ipython one can use the question mark operator
MDAnalysis.Universe ?
Interactive use is not always convenient, though, and hence Issue 26 called for proper documentation.
As of Jan 2011, the Online Documentation is available, too.
This page should help developers write good documentation that can be easily processed into online docs.
When writing Python code, you should always add a doc string to each public (user-visible)
- module
- class
- method
- function (We consider something public if the name does not start with an underscore.) The module doc string can be a short sentence describing what the module does or a long document including examples and references. The other doc strings should generally allow a user to use the code element, so they need to say what the code does, what input it requires, and what it returns. Additionally, one should document the exceptions raised and known bugs or quirks.
- Code is documented through Python doc strings (see PEP 257 for good conventions); thus each Python file should contain some documentation.
- The Online Documentation is generated from reStructuredText in doc/sphinx/source/documentation_pages.
- The googlecode pages also hold documentation in the MDAnalysis Wiki (but as far as the user docs go, they are being phased out in favour of the Online Docs).
We are using reStructuredText ("rst" or "reST") in the Python code and in the Online Documentation. The reST is processed with sphinx to generate HTML or PDF. Thus, the docs should use reST with the sphinx autodoc extensions:
- sphinx reST Primer
- sphinx autodoc extension
Note that each page of the Online Documentation has a link to the Source of the page. You can look at it in order to find out how a particular page has been written in reST and copy the approach for your own documentation.
In order to generate the documentation, one has to have sphinx installed. Then one generates the html docs with
cd doc/sphinx
make html
This generates and updates the files in doc/html. Note that you need the current version of MDAnalysis installed and importable. A 'develop' installation (python setup.py develop) is generally useful for quick turn-around.
For testing, you can also use
python setup.py build_sphinx
which creates docs under build/sphinx/html but these files are never committed to the repository so remember to use the procedure with make to generate online docs.
- Generated html and other files are checked into the git repository as a separate commit from any doc changes that you made either in the reST or py files. Please do not mix autogenerated files with manual edits.
- Newly generated files must be added (
git add) or they don't show up in the online docs!
We are using MathJax with sphinx so you can write LaTeX code in math tags, e.g.
#<SPACE if there is text above equation>
.. math::
e^{i\pi} = -1
or inline
We make use of the identity :math:`e^{i\pi} = -1` to show...
Note that you should always make doc strings with math code raw python strings by prefixing them with the letter "r":
def rotate(self, R):
r"""Apply a rotation matrix *R* to the selection's coordinates.
:math:`\mathsf{R}` is a 3x3 orthogonal matrix that transforms a vector
:math:`\mathbf{x} \rightarrow \mathbf{x}'`:
.. math::
\mathbf{x}' = \mathsf{R}\mathbf{x}
"""
or else you will get problems with backslashes in unexpected places (see Stackoverflow: Mathjax expression in sphinx python not rendering correctly).
When a new version is released, the docs on pythonhosted are updated as part of the release procedure. They can be accessed from http://docs.mdanalysis.org
The http://devdocs.mdanalysis.org are generated from the develop branch but because they are served through gh-pages, a manual procedure needs to be carried out to make it work (perhaps run a webhook or something... – and no, readthedocs did not work for us, see #183 and #235):
git checkout gh-pages
git merge develop
git push origin gh-pages