How to contribute to the NumPy documentation#

Documentation framework#

There are formulas for writing useful documents, and four formulas cover nearly everything. There are four formulas because there are four categories of document – tutorial, how-to guide, explanation, and reference. The insight that docs divide up this way belongs to Daniele Procida and his Diátaxis Framework. When you begin a document or propose one, have in mind which of these types it will be.

NumPy tutorials#

In addition to the documentation that is part of the NumPy source tree, you can submit content in Jupyter Notebook format to the NumPy Tutorials page. This set of tutorials and educational materials is meant to provide high-quality resources by the NumPy project, both for self-learning and for teaching classes with. These resources are developed in a separate GitHub repository, numpy-tutorials, where you can check out existing notebooks, open issues to suggest new topics or submit your own tutorials as pull requests.

More on contributing#

Don’t worry if English is not your first language, or if you can only come up with a rough draft. Open source is a community effort. Do your best – we’ll help fix issues.

Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others.

For now, the only data formats accepted by NumPy are those also used by other Python scientific libraries like pandas, SciPy, or Matplotlib. We’re developing a package to accept more formats; contact us for details.

NumPy documentation is kept in the source code tree. To get your document into the docbase you must download the tree, build it, and submit a pull request. If GitHub and pull requests are new to you, check our Contributor Guide.

Our markup language is reStructuredText (rST), which is more elaborate than Markdown. Sphinx, the tool many Python projects use to build and link project documentation, converts the rST into HTML and other formats. For more on rST, see the Quick reStructuredText Guide or the reStructuredText Primer

User documentation#

• In general, we follow the Google developer documentation style guide for the User Guide.

• NumPy style governs cases where:

  • Google has no guidance, or

  • We prefer not to use the Google style

  Our current rules:

  • We pluralize index as indices rather than indexes, following the precedent of numpy.indices.

  • For consistency we also pluralize matrix as matrices.

• Grammatical issues inadequately addressed by the NumPy or Google rules are decided by the section on “Grammar and Usage” in the most recent edition of the Chicago Manual of Style.

• We welcome being alerted to cases we should add to the NumPy style rules.

Docstrings#

When using Sphinx in combination with the NumPy conventions, you should use the numpydoc extension so that your docstrings will be handled correctly. For example, Sphinx will extract the Parameters section from your docstring and convert it into a field list. Using numpydoc will also avoid the reStructuredText errors produced by plain Sphinx when it encounters NumPy docstring conventions like section headers (e.g. -------------) that sphinx does not expect to find in docstrings.

It is available from:

• numpydoc on PyPI

• numpydoc on GitHub

Note that for documentation within NumPy, it is not necessary to do import numpy as np at the beginning of an example.

Please use the numpydoc formatting standard as shown in their example.

Documenting C/C++ code#

NumPy uses Doxygen to parse specially-formatted C/C++ comment blocks. This generates XML files, which are converted by Breathe into RST, which is used by Sphinx.

It takes three steps to complete the documentation process:

/**
 * This a simple brief.
 *
 * And the details goes here.
 * Multi lines are welcome.
 *
 * @param  num  leave a comment for parameter num.
 * @param  str  leave a comment for the second parameter.
 * @return      leave a comment for the returned value.
 */
int doxy_javadoc_example(int num, const char *str);

/**
 *  Template to represent limbo numbers.
 *
 *  Specializations for integer types that are part of nowhere.
 *  It doesn't support with any real types.
 *
 *  @param Tp Type of the integer. Required to be an integer type.
 *  @param N  Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
 public:
    /// Default constructor. Initialize nothing.
    DoxyLimbo();
    /// Set Default behavior for copy the limbo.
    DoxyLimbo(const DoxyLimbo<Tp, N> &l);
    /// Returns the raw data for the limbo.
    const Tp *data();
 protected:
    Tp p_data[N]; ///< Example for inline comment.
};

/**
 * A comment block contains reST markup.
 * @rst
 * .. note::
 *
 *   Thanks to Breathe_, we were able to bring it to Doxygen_
 *
 * Some code example::
 *
 *   int example(int x) {
 *       return x * 2;
 *   }
 * @endrst
 */
void doxy_reST_example(void);

# to specify certain headers
INPUT += @CUR_DIR/header1.h \
         @CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
              NPY_HAVE_FEATURE2

.. doxygenfunction:: <function name>
    :outline:
    :no-link:

.. doxygenclass:: <class name>
   :members: [...]
   :protected-members:
   :private-members:
   :undoc-members:
   :membergroups: ...
   :members-only:
   :outline:
   :no-link:

.. doxygennamespace:: <namespace>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:

.. doxygengroup:: <group name>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:
   :inner:

Legacy directive#

If a function, module or API is in legacy mode, meaning that it is kept around for backwards compatibility reasons, but is not recommended to use in new code, you can use the .. legacy:: directive.

By default, if used with no arguments, the legacy directive will generate the following output:

We strongly recommend that you also add a custom message, such as a new API to replace the old one:

.. legacy::

   For more details, see :ref:`distutils-status-migration`.

This message will be appended to the default message and will create the following output:

Finally, if you want to mention a function, method (or any custom object) instead of a submodule, you can use an optional argument:

.. legacy:: function

This will create the following output: