Nov 28, 2017 · Nov 28, 2017 · Nov 28, 2017 · Nov 28, 2017 · Nov 28, 2017 · Nov 28, 2017
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
 built as a single document in order to make the most effective use of cross
 referencing.

 .. note::

   An exception to this are the directories :file:`examples` and
   :file:`tutorials`, which exist in the root directory.  These contain Python
   files that are built by `Sphinx Gallery`_.  When the docs are built,
   the directories :file:`docs/gallery` and :file:`docs/tutorials`
   are automatically generated. Do not edit the rst files in :file:docs/gallery
   and :file:docs/tutorials, as they are rebuilt from the original sources in
   the root directory.

 Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
 the docstrings of the classes in the Matplotlib library.  Except for
 :file:`doc/api/api_changes/`, these ``.rst`` are created when the
 documentation is built.

 Similarly, the contents of :file:`docs/gallery` and :file:`docs/tutorials` are
 generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
 :file:`tutorials`.  These sources consist of python scripts that have ReST
 documentation built into their comments.  Again, don't directly edit the
 ``.rst`` files in :file:`docs/gallery` and :file:`docs/tutorials` as they are
 regenerated when the documentation are built.

 Additional files can be added to the various guides by including their base
 file name (the .rst extension is not necessary) in the table of contents.
 Writing new documentation
 =========================

 As noted above, most documentation is either in the docstring of individual
 classes and methods, in explicit ``.rst`` files, or in examples and tutorials.

 Writing self-documenting docstrings
 -----------------------------------

 Most documentation lives in "docstrings". These are comment blocks in source
 code that explain how the code works. All new or edited docstrings should
 conform to the numpydoc guidelines. These split the docstring into a number
 of sections - see
 https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more
 details and a guide to how docstrings should be formatted.
 details and a guide to how docstrings should be formatted.  These docstrings
 eventually populate the :file:`doc/api` directory.

 An example docstring looks like:

        axhline: horizontal line across the axes
        """

 See the `~.Axes.hlines` documentation for how this renders.

 The Sphinx website also contains plenty of documentation_ concerning ReST
 markup and working with Sphinx in general.

   the current style are very welcome.

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

 There are some additional conventions, not handled by numpydoc and the Sphinx
 guide:
             ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
     'polar' | 'rectilinear'], optional
             The projection type of the axes.
         """

  Alternatively, you can describe the valid parameter values in a dedicated
  section of the docstring.
     lines : `~matplotlib.collections.LineCollection`



 Linking to other code
 ---------------------
 ~~~~~~~~~~~~~~~~~~~~~
 To link to other methods, classes, or modules in Matplotlib you can encase
 the name to refer to in back ticks, for example:

 .. code-block:: python

  `~matplotlib.collections.LineCollection`

 It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.
 Sometimes it is tricky to get external Sphinx linking to work; to check that
 a something exists to link to the following shell command outputs a list of all
 objects that can be referenced (in this case for Numpy)::
 returns a link to the documentation of
 `~matplotlib.collections.LineCollection`.  If we want the full path of the
 class to be shown then we omit the tilde:

 .. code-block:: python

  `matplotlib.collections.LineCollection`

 to get `matplotlib.collections.LineCollection`.  Its often not
 necessary to fully specify the class hierarchy unless there is a namespace
 collision between two packages:

 .. code-block:: python

  `~.LineCollection`

 links just as well: `~.LineCollection`.

 Other packages can also be linked via ``intersphinx``:

 .. code-block:: Python

  `numpy.mean`

 will return this link: `numpy.mean`.  This works for Python, Numpy, Scipy,
 and Pandas (full list is in :file:`doc/conf.py`). Sometimes it is tricky
 to get external Sphinx linking to work; to
 check that a something exists to link to the following shell command outputs
 a list of all objects that can be referenced (in this case for Numpy)::

  python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv'


 Function arguments
 ------------------
 ~~~~~~~~~~~~~~~~~~

 Function arguments and keywords within docstrings should be referred to using
 the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent
 with Python's documentation:

  Here is a description of *argument*

 Please do not use the ```default role```:

 Do not use the ```default role```:

 .. code-block:: rst

   Please do not describe `argument` like this.
   Do not describe `argument` like this.  As per the previous section,
   this syntax will (unsuccessfully) attempt to resolve the argument as a
   link to an object in the library.

 nor the ````literal```` role:

 .. code-block:: rst

 Please do not describe ``argument`` like this.
 Do not describe ``argument`` like this.

 Setters and getters
 -------------------
 Matplotlib uses artist introspection of docstrings to support properties.
 All properties that you want to support through `~.pyplot.setp` and
 `~.pyplot.getp` should have a ``set_property`` and ``get_property`` method in
 the `~.matplotlib.artist.Artist` class. The setter methods use the docstring
 with the ACCEPTS token to indicate the type of argument the method accepts.
 e.g., in `.Line2D`:
 ~~~~~~~~~~~~~~~~~~~

 Artist properties are implemented using setter and getter methods (because
 Matplotlib predates the introductions of the `property` decorator in Python).
 By convention, these setters and getters are named ``set_PROPERTYNAME`` and
 ``get_PROPERTYNAME``; the list of properties thusly defined on an artist and
 their values can be listed by the `~.pyplot.setp` and `~.pyplot.getp` functions.

 Property setter methods should indicate the values they accept using a (legacy)
 special block in the docstring, starting with ``ACCEPTS``, as follows:

 .. code-block:: python

       ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
       """

 The ACCEPTS block is used to render a table of all properties and their
 acceptable values in the docs; it can also be displayed using, e.g.,
 ``plt.setp(Line2D)`` (all properties) or ``plt.setp(Line2D, 'linestyle')``
 (just one property).

 Keyword arguments
 -----------------
 ~~~~~~~~~~~~~~~~~

 .. note::

  The information in this section is being actively discussed by the
  development team, so use the docstring interpolation only if necessary.
  This section has been left in place for now because this interpolation
  is part of the existing documentation.

 Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function
 that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`,
 etc...), it can be difficult for the new user to know which ``kwargs`` are
Original file line number	Diff line number	Diff line change
Expand Up		@@ -43,16 +43,17 @@ guide, developers guide, api reference, and FAQs. The documentation suite is
		built as a single document in order to make the most effective use of cross
		referencing.

		.. note::

		An exception to this are the directories :file:`examples` and
		:file:`tutorials`, which exist in the root directory. These contain Python
		files that are built by `Sphinx Gallery`_. When the docs are built,
		the directories :file:`docs/gallery` and :file:`docs/tutorials`
		are automatically generated. Do not edit the rst files in :file:docs/gallery
		and :file:docs/tutorials, as they are rebuilt from the original sources in
		the root directory.

		Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
		the docstrings of the classes in the Matplotlib library. Except for
		:file:`doc/api/api_changes/`, these ``.rst`` are created when the
		documentation is built.

		Similarly, the contents of :file:`docs/gallery` and :file:`docs/tutorials` are
		generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
Copy link Contributor anntzerNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. not directly related but I think the "examples" folder should be renamed "gallery" or the "gallery" folder on the website should be renamed "examples"... Copy link MemberAuthor jklymakNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Yeah I agree. Its very confusing. I prefer "examples".
		:file:`tutorials`. These sources consist of python scripts that have ReST
		documentation built into their comments. Again, don't directly edit the
		``.rst`` files in :file:`docs/gallery` and :file:`docs/tutorials` as they are
		regenerated when the documentation are built.

		Additional files can be added to the various guides by including their base
		file name (the .rst extension is not necessary) in the table of contents.
Expand DownExpand Up		@@ -91,12 +92,19 @@ The list of commands and flags for ``make.py`` can be listed by running
		Writing new documentation
		=========================

		As noted above, most documentation is either in the docstring of individual
		classes and methods, in explicit ``.rst`` files, or in examples and tutorials.

		Writing self-documenting docstrings
		-----------------------------------

		Most documentation lives in "docstrings". These are comment blocks in source
		code that explain how the code works. All new or edited docstrings should
		conform to the numpydoc guidelines. These split the docstring into a number
		of sections - see
		https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more
		details and a guide to how docstrings should be formatted.
		details and a guide to how docstrings should be formatted. These docstrings
		eventually populate the :file:`doc/api` directory.

		An example docstring looks like:

Expand DownExpand Up		@@ -136,6 +144,8 @@ An example docstring looks like:
		axhline: horizontal line across the axes
		"""

		See the `~.Axes.hlines` documentation for how this renders.

		The Sphinx website also contains plenty of documentation_ concerning ReST
		markup and working with Sphinx in general.

Expand All		@@ -147,7 +157,7 @@ markup and working with Sphinx in general.
		the current style are very welcome.

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

		There are some additional conventions, not handled by numpydoc and the Sphinx
		guide:
Expand All		@@ -170,6 +180,7 @@ guide:
		['aitoff' \| 'hammer' \| 'lambert' \| 'mollweide' \| \
		'polar' \| 'rectilinear'], optional
		The projection type of the axes.
		"""

		Alternatively, you can describe the valid parameter values in a dedicated
		section of the docstring.
Expand All		@@ -186,26 +197,51 @@ guide:
		lines : `~matplotlib.collections.LineCollection`



		Linking to other code
		---------------------
		~~~~~~~~~~~~~~~~~~~~~
		To link to other methods, classes, or modules in Matplotlib you can encase
		the name to refer to in back ticks, for example:

		.. code-block:: python

		`~matplotlib.collections.LineCollection`

		It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.
		Sometimes it is tricky to get external Sphinx linking to work; to check that
		a something exists to link to the following shell command outputs a list of all
		objects that can be referenced (in this case for Numpy)::
		returns a link to the documentation of
		`~matplotlib.collections.LineCollection`. If we want the full path of the
		class to be shown then we omit the tilde:
Copy link Member dstansbyNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. 😮 I didn't know this! Copy link MemberAuthor jklymakNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Yeah,@anntzer explained it all to me (somewhere). Its also nicely explained at the very bottom of this very long section in the sphinx docs: http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain Could the discoverability of this be better? Probably!

		.. code-block:: python

		`matplotlib.collections.LineCollection`

		to get `matplotlib.collections.LineCollection`. Its often not
		necessary to fully specify the class hierarchy unless there is a namespace
		collision between two packages:

		.. code-block:: python

		`~.LineCollection`

		links just as well: `~.LineCollection`.

		Other packages can also be linked via ``intersphinx``:

		.. code-block:: Python

		`numpy.mean`

		will return this link: `numpy.mean`. This works for Python, Numpy, Scipy,
		and Pandas (full list is in :file:`doc/conf.py`). Sometimes it is tricky
		to get external Sphinx linking to work; to
		check that a something exists to link to the following shell command outputs
		a list of all objects that can be referenced (in this case for Numpy)::

		python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv'


		Function arguments
		------------------
		~~~~~~~~~~~~~~~~~~

Copy link Contributor anntzerNov 28, 2017• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. may be worth explaining briefly why single backquotes doesn't work (arguments don't have an entry) jklymak reacted with thumbs up emoji Copy link MemberAuthor jklymakNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Changed to: Do not describe `argument` like this. As per the previous section, this syntax will attempt to resolve the argument as a link to an object in the library. Copy link Contributor anntzerNov 28, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. will (unsuccessfully) attempt to etc. jklymak reacted with thumbs up emoji
		Function arguments and keywords within docstrings should be referred to using
		the ``emphasis`` role. This will keep Matplotlib's documentation consistent
		with Python's documentation:
Expand All		@@ -214,27 +250,31 @@ with Python's documentation:

		Here is a description of argument

		Please do not use the ```default role```:

		Do not use the ```default role```:

		.. code-block:: rst

		Please do not describe `argument` like this.
		Do not describe `argument` like this. As per the previous section,
		this syntax will (unsuccessfully) attempt to resolve the argument as a
		link to an object in the library.

		nor the ````literal```` role:

		.. code-block:: rst

		Please do not describe ``argument`` like this.
		Do not describe ``argument`` like this.

		Setters and getters
		-------------------
		Matplotlib uses artist introspection of docstrings to support properties.
		All properties that you want to support through `~.pyplot.setp` and
		`~.pyplot.getp` should have a ``set_property`` and ``get_property`` method in
		the `~.matplotlib.artist.Artist` class. The setter methods use the docstring
		with the ACCEPTS token to indicate the type of argument the method accepts.
		e.g., in `.Line2D`:
		~~~~~~~~~~~~~~~~~~~

		Artist properties are implemented using setter and getter methods (because
		Matplotlib predates the introductions of the `property` decorator in Python).
		By convention, these setters and getters are named ``set_PROPERTYNAME`` and
		``get_PROPERTYNAME``; the list of properties thusly defined on an artist and
		their values can be listed by the `~.pyplot.setp` and `~.pyplot.getp` functions.

		Property setter methods should indicate the values they accept using a (legacy)
		special block in the docstring, starting with ``ACCEPTS``, as follows:

		.. code-block:: python

Expand All		@@ -246,8 +286,21 @@ e.g., in `.Line2D`:
		ACCEPTS: [ '-' \| '--' \| '-.' \| ':' \| 'steps' \| 'None' \| ' ' \| '' ]
		"""

		The ACCEPTS block is used to render a table of all properties and their
		acceptable values in the docs; it can also be displayed using, e.g.,
		``plt.setp(Line2D)`` (all properties) or ``plt.setp(Line2D, 'linestyle')``
		(just one property).

		Keyword arguments
		-----------------
		~~~~~~~~~~~~~~~~~

		.. note::

		The information in this section is being actively discussed by the
		development team, so use the docstring interpolation only if necessary.
		This section has been left in place for now because this interpolation
		is part of the existing documentation.

		Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function
		that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`,
		etc...), it can be difficult for the new user to know which ``kwargs`` are
Expand Down