Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Additions to the documentation guide #9875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 29, 2017
Merged

Additions to the documentation guide #9875

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,54 @@ An example docstring looks like:
The Sphinx website also contains plenty of documentation_ concerning ReST
markup and working with Sphinx in general.

.. note::

Some parts of the documentation do not yet conform to the current
documentation style. If in doubt, follow the rules given here and not what
you may see in the source code. Pull requests updating docstrings to
the current style are very welcome.

Additional formatting conventions
---------------------------------

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This all looks good to me. Note I knocked all this down a level in the outline, so we'll have to remember to reconcile. Actually my new outlining is somewhat incomplete the way I've done it, but I thought I'd leave it like that to at least remind myself that it needed fixing.

There are some additional conventions, not handled by numpydoc and the Sphinx
guide:

* We do not have a convention whether to use single-quotes or double-quotes.
There is a mixture of both in the current code. Please leave them as they are.

* Long parameter lists should be wrapped using a ``\`` for continuation and
starting on the new line without any indent:

.. code-block:: python

def add_axes(self, *args, **kwargs):
"""
...

Parameters
----------
projection :
['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
'polar' | 'rectilinear'], optional
The projection type of the axes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

close the triple quotes here (possibly after an ellipsis)


Alternatively, you can describe the valid parameter values in a dedicated
section of the docstring.

* Generally, do not add markup to types for ``Parameters`` and ``Returns``.
This is usually not needed because Sphinx will link them automatically and
would unnecessarily clutter the docstring. However, it does seem to fail in
some situations. If you encounter such a case, you are allowed to add markup:

.. code-block:: rst

Returns
-------
lines : `~matplotlib.collections.LineCollection`



Linking to other code
---------------------
To link to other methods, classes, or modules in Matplotlib you can encase
Expand Down