Writing documentation

Note: This document is a draft.

General

Sympy documentation found at docs.sympy.org is generated from docstrings in the source code and dedicated files in /doc/src directory. Both are written in reStructuredText format extended by Sphinx. Sphinx is also used to compile documentation to various formats (e.g. html, latex,...).

Docstrings

Docstrings should follow PEP 257 - Docstring conventions and PEP 287 - reStructuredText docstring format. In order to make section underlining work nicely in docstrings, numpydoc Sphinx extension is used. Here are some of the section titles that the extension supports in docstrings (but are not mandatory to use):

• Parameters
• See Also
• Notes
• References
• Examples

Do not use unsupported section titles! Some parts of docstrings should use alternative formatting mechanisms (i.e. not underlining), for example Deprecation warnings should use the note Sphinx directive,

.. note:: Deprecated in Sympy 0.7.1.

For more information on available options see A guide to NumPy/SciPy documentation.

TOCs and indexes

Tables of content (TOC), e.g. on the documentation front page, and indexes mush have the items listed in alphabetical order.