Update documentation guide #9805

dstansby · 2017-11-16T23:47:46Z

Needs a bit more work, but the aim is to fix #9786 eventually and generally clean the writing documentation guide. Comments very welcome and encouraged! (please also add to the TODO list below)

TODO:

Link to numpydoc docs
Add section on intersphinx

dstansby · 2017-11-17T00:00:42Z

doc/devel/documenting_mpl.rst


  .. rubric:: Footnotes

  .. [#] For example.

-* Use the *note* and *warning* directives, sparingly, to draw attention to


This delted block is covered by numpydoc guidelines

jklymak · 2017-11-17T00:39:03Z

doc/devel/documenting_mpl.rst


 The function `matplotlib.artist.kwdoc` and the decorator
-`matplotlib.docstring.dedent_interpd` facilitate this.  They combine python
+`matplotlib.docstring.dedent_interpd` facilitate this.  They combine Python


Given the big squak some raised when I tried to use this facilty, should this be in the doc guide?

I'll still re-iterate that I was told explcitly not to do this for the legend docs a month ago. So if we are not allowed to use this functionality it should be noted here.

dstansby · 2017-11-19T21:20:16Z

doc/devel/documenting_mpl.rst

@@ -91,244 +90,131 @@ statement, such as::

  .. include:: ../../TODO

-docstrings


This whole section has moved down to the bottom

dstansby · 2017-11-19T21:35:11Z

doc/devel/documenting_mpl.rst

-directories.  To exclude the example from having an image rendered,
-insert the following special comment anywhere in the script:
+automatically included in the HTML docs. To exclude the example from having an
+image rendered, insert the following special comment anywhere in the script:


Is this still true @choldgraf ?

ah no, instead they should put sgskip somewhere in the filename. Maybe worth just noting "all files in the examples directory will be automatically run and rendered into documentation with sphinx-gallery (incl. link)" and leave it at that?

dstansby · 2017-11-19T21:44:46Z

doc/devel/documenting_mpl.rst

-
-     Please do not describe ``argument`` like this.
-
-* Mathematical expressions can be rendered as png images in html, and in the


I've removed the maths, ipython, and footnotes bits, as they are covered in Sphinx documentation, and I don't think they're common enough to need a specific section in the Matplotlib docs.

anntzer · 2017-11-19T23:37:58Z

doc/devel/documenting_mpl.rst

-The documentation sources are found in the :file:`doc/` directory in
-the trunk.  To build the users guide in html format, cd into
-:file:`doc/` and do:
+The documentation sources are found in the :file:`doc/` directory in the trunk.


This part will be obsoleted by https://github.com/matplotlib/matplotlib/pull/9513/files...

anntzer · 2017-11-19T23:38:42Z

doc/devel/documenting_mpl.rst

+  def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
+             label='', **kwargs):
+        """
+        Plot horizontal lines at each `y` from `xmin` to `xmax`.


should be asterisks :p

anntzer · 2017-11-19T23:39:04Z

doc/devel/documenting_mpl.rst

-* Use the *seealso* directive, for example:
+        Other Parameters
+        ----------------
+        **kwargs :  `~matplotlib.collections.LineCollection` properties.


one space too many after the colon

anntzer · 2017-11-19T23:41:16Z

doc/devel/documenting_mpl.rst


-* Please keep the :ref:`glossary` in mind when writing documentation. You can
-  create a references to a term in the glossary with the ``:term:`` role.
+   Please do not describe `argument` like this.


I think a (short) explanation similar to the one I gave at #9786 (comment) (about the meaning of single backticks) may be helpful.

anntzer · 2017-11-19T23:42:50Z

doc/devel/documenting_mpl.rst

-it via a relative path from the document where the rst file resides, e.g., in
-:file:`users/navigation_toolbar.rst`, we refer to the image icons with::
+In the documentation, you may want to include to a document in the
+Matplotlib src, e.g., a license file or an image file from `mpl-data`,


anntzer · 2017-11-19T23:43:10Z

doc/devel/documenting_mpl.rst

-mpl-data directory, I use the symlink directory.  For example, from
-:file:`customizing.rst`::
+In the `users` subdirectory, if you want to refer to a file in the mpl-data
+directory, you can use the symlink directory.  For example, from


I don't think there's a symlink anymore?

matplotlib/lib/mpl_examples

Line 1 in 7ddc73a

../examples

In master it looks like there still is

anntzer · 2017-11-19T23:43:49Z

doc/devel/documenting_mpl.rst

@@ -454,7 +287,7 @@ files are duplicated and large)
 Internal section references
 ===========================

-To maximize internal consistency in section labeling and references,
+To maximize internal consistency in section labelling and references,


US english one ell? :)

anntzer · 2017-11-19T23:44:31Z

doc/devel/documenting_mpl.rst

@@ -467,8 +300,8 @@ and refer to it using  the standard reference syntax:

    See :ref:`howto-webapp`

-Keep in mind that we may want to reorganize the contents later, so
-let's avoid top level names in references like ``user`` or ``devel``
+Keep in mind that we may want to re-organize the contents later, so


https://www.merriam-webster.com/dictionary/reorganize

anntzer · 2017-11-19T23:45:34Z

doc/devel/documenting_mpl.rst

+      autoscaled; default True.  See Axes.autoscale_view for more
+      information
+      """
+      pass


the pass is unneeded (syntax is correct without it and it's not the real impl either)

anntzer · 2017-11-19T23:45:50Z

doc/devel/documenting_mpl.rst

+      The kwargs are Line2D properties:
+      %(Line2D)s
+
+      kwargs scalex and scaley, if defined, are passed on


should use correct markup (asterisks, backquotes below)

anntzer · 2017-11-19T23:46:19Z

doc/devel/documenting_mpl.rst

-Developer's tips for documenting Matplotlib
-===========================================
+================================
+Developer's tips for documenting


"Documentation guidelines"?

anntzer · 2017-11-19T23:47:11Z

doc/devel/documenting_mpl.rst

-the Sphinx_ documentation generation tool.  There are several extra
-requirements that are needed to build the documentation.  They are listed in
-:file:`doc-requirements.txt` as well as listed below:
+the Sphinx_ documentation generation tool. There are several extra requirements


also edited in the Makefile PR

choldgraf · 2017-11-20T04:04:37Z

@dstansby thanks for cleaning this up! +1 on merge after @anntzer 's comments addressed. feel free to ping me after you do so

jklymak · 2017-11-21T16:54:29Z

doc/devel/documenting_mpl.rst

-   generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be
-   safely deleted.
+   the directories :file:`docs/gallery` and :file:`docs/tutorials`
+   are generated.


I'd say something like: "...are automatically generated. Do not edit the rst files in :file:docs/gallery and :file:docs/tutorials, as they are rebuilt from the sources in the root directory"

I was mystified for a while when my changes to files in these directories were being overwritten ;-)

jklymak · 2017-11-21T16:59:15Z

doc/devel/documenting_mpl.rst

-     Matplotlib makes extensive use of keyword arguments as pass-through
-     arguments, there are a many cases where a table is used in place of a
-     definition list for autogenerated sections of docstrings.
+   Please do not describe ``argument`` like this.

 Figures
 =======



This could use an intoroductory paragraph, or even a change of heading. I find it very mysterious what figures you are talking about. In docstrings? I think you mean in examples and tutorials. If so, maybe a "Writing an example or tutorial" would be a more useful heading, and figure creation is of course the most important thing that happens in that context.

Added a bit more text and changed the title; is it better now?

I think maybe a specific section on writing an example/tutorial is needed.

Maybe a new document? This one is quite long already, so sticking to just "Documenting code" is better, and a separate "Writing examples and tutorials" guide can be written.

jklymak · 2017-11-21T17:00:26Z

doc/devel/documenting_mpl.rst


 Plot directive documentation
 ''''''''''''''''''''''''''''

 .. automodule:: matplotlib.sphinxext.plot_directive
+   :no-undoc-members:

 Examples


As above. This seems the heading (+ Tutorials) not "Figures" per se. (I guess there are figures in the numpydocs?)

jklymak · 2017-11-21T17:01:25Z

doc/devel/documenting_mpl.rst

@@ -492,11 +308,91 @@ For everything but top level chapters, please use ``Upper lower`` for
 section titles, e.g., ``Possible hangups`` rather than ``Possible
 Hangups``

+Setters, getters, and keyword arguments
+=======================================


Why is this way down here instead of up w/ the numpydoc section?

Moved back up

dstansby · 2017-11-22T18:04:10Z

Okay, I think I'm ready for reviews! (ping @choldgraf)

Add link to numpydoc Add missing dash Fix build Get rid of extra bits Move setter/getter/kwarg section to near bottom More cleanup Remove sections covered in sphinx docs More small fixes Correct sgskip Update title More cleaning Move setters/getters/kwargs back Clarify examples/tutorials directories Fix code indentation Improve figure discussion Improve some headings Add intersphinx section

jklymak · 2017-11-22T19:19:11Z

So save others from a few clicks:
https://circleci.com/gh/dstansby/matplotlib/386/artifacts/0//home/circleci/project/doc/build/html/index.html

jklymak · 2017-11-22T19:21:42Z

doc/devel/documenting_mpl.rst

+
+  `~matplotlib.collections.LineCollection`
+
+It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.


for example:

.. code-block:: python

numpy.mean

jklymak · 2017-11-22T19:23:45Z

doc/devel/documenting_mpl.rst

-argument the method accepts. e.g., in `.Line2D`:
+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`:


OK, I've written some docs, and have used matplotlib for a while. I don't know what the first sentence of this section means. Can we clarify for the somewhat uninitiated?

Something like

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 example follows)

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).

looks good?

Yes that makes sense to me. Thanks!

@dstansby can you apply the patch? or I can do it too

Feel free to push any changes to this section - I don't have the bandwidth to get my head around it at the moment!

jklymak · 2017-11-22T19:26:35Z

doc/devel/documenting_mpl.rst

-     Here is a description of *argument*
-
-  Please do not use the ```default role```:
+Adding figures


I like the text below. I'm still not sure about the heading....

jklymak · 2017-11-22T19:31:33Z

General comment: I still think this could use a bit more basic guidance on the different types of documentation at the top. i.e.:

ReST files in docs/users and docs/faqs and ?? are translated to html and other downstream formats during the build process.
API documentation from docstrings is automatically extracted from the python sources in /lib/matplotlib
docs/examples and docs/tutorials are automatically generated from running the python scripts in /examples and /tutorials. Don't edit the generated files!

choldgraf · 2017-11-28T18:17:23Z

My 2 cents: I think this should be merged. Even if it is not perfect it is a definite improvement in the documentation, and we've already iterated on this quite a lot. People can always open less ambitious PRs to spot-check things but @dstansby has already done a lot on this PR. Obviously it's their call if they want to keep iterating on comments etc, but let's not let perfect become the enemy of good.

efiring · 2017-11-28T18:24:07Z

I'm tempted to follow @choldgraf's advice and merge this, but it looks like @anntzer and/or @jklymak might want to push some quick changes first. Do you?

jklymak · 2017-11-28T18:37:59Z

I think its easier for me to work from master, so I'm happy to put a PR in after this improvement! 👍

anntzer · 2017-11-28T18:47:09Z

actually a bit busy today, can anyone prepare a PR from my patch?

jklymak · 2017-11-28T18:53:33Z

Yes, I'll definitely incude your patch. Its very helpful...

lumberbot-app · 2017-11-28T19:07:34Z

There seem to be a conflict, please backport manually

dstansby · 2017-11-28T19:35:05Z

Thanks for merging! I was happy to add more changes, but didn't/don't have the time to around now anyway.

Update documentation guide

Backport pull request #9805 to v2.1.0-doc

tacaswell · 2017-12-06T03:52:24Z

Back port taken care of my 55830e5 merge of v2.1.0-doc in to 2.1.x

dstansby added the Documentation label Nov 16, 2017

dstansby force-pushed the doc-guide branch from 41d847e to 822cc89 Compare November 17, 2017 00:00

dstansby commented Nov 17, 2017

View reviewed changes

jklymak reviewed Nov 17, 2017

View reviewed changes

dstansby commented Nov 19, 2017

View reviewed changes

anntzer reviewed Nov 19, 2017

View reviewed changes

dstansby force-pushed the doc-guide branch from 265645e to 072ab6c Compare November 20, 2017 10:56

jklymak reviewed Nov 21, 2017

View reviewed changes

dstansby changed the title ~~WIP Update documentating guide~~ Update documentating guide Nov 22, 2017

dstansby force-pushed the doc-guide branch from 8fecdde to 06c8d4a Compare November 22, 2017 18:05

dstansby changed the title ~~Update documentating guide~~ Update documentation guide Nov 22, 2017

jklymak reviewed Nov 22, 2017

View reviewed changes

tacaswell added this to the v2.1.0-doc milestone Nov 23, 2017

jklymak approved these changes Nov 28, 2017

View reviewed changes

efiring merged commit 2f897dc into matplotlib:master Nov 28, 2017

lumberbot-app bot added the status: needs manual backport label Nov 28, 2017

dstansby deleted the doc-guide branch November 28, 2017 19:35

jklymak mentioned this pull request Nov 28, 2017

DOC: Minor enhancements to documenting_mpl #9872

Closed

6 tasks

dstansby pushed a commit to dstansby/matplotlib that referenced this pull request Nov 28, 2017

Merge pull request matplotlib#9805 from dstansby/doc-guide

a7d01a6

Update documentation guide

timhoffm mentioned this pull request Nov 28, 2017

Additions to the documentation guide #9875

Merged

dstansby added a commit that referenced this pull request Nov 29, 2017

Merge pull request #9873 from dstansby/v2.1.0-doc

7bf1a31

Backport pull request #9805 to v2.1.0-doc

tacaswell removed the status: needs manual backport label Dec 6, 2017

timhoffm mentioned this pull request Dec 9, 2017

The documentation on "how to write documentation" need to be updated #7217

Closed

		@@ -91,244 +90,131 @@ statement, such as::

		.. include:: ../../TODO

		docstrings


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

		* Mathematical expressions can be rendered as png images in html, and in the


		`~matplotlib.collections.LineCollection`

		It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.

Uh oh!

Update documentation guide #9805

Update documentation guide #9805

Uh oh!

Conversation

dstansby commented Nov 16, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak Nov 17, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

choldgraf commented Nov 20, 2017

Uh oh!

jklymak Nov 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dstansby commented Nov 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak commented Nov 22, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dstansby commented Nov 16, 2017 •

edited

Loading

jklymak Nov 17, 2017 •

edited

Loading

jklymak Nov 21, 2017 •

edited

Loading

dstansby commented Nov 22, 2017 •

edited

Loading

jklymak commented Nov 28, 2017 •

edited

Loading