updating developer docs #8544

choldgraf · 2017-04-27T19:38:00Z

small change to add some extra useful information for the documentation to help contribute to the docs. We've had a hard time on-boarding new people to help with docs in matplotlib, so hopefully this will help clear up some issues.

story645 · 2017-04-27T22:31:23Z

doc/devel/documenting_mpl.rst

+.. note::
+
+  * You'll need a minimal working latex distribution for many examples to run.
+  * Graphviz is not pip-installable so you need to install this on your own.


externel link to Graphviz? (Graphviz is not a python package, so it needs to be installed separately.)

story645 · 2017-04-27T22:31:59Z

doc/devel/documenting_mpl.rst

+
+All documentation is built from the :file:`doc/` directory. This folder contains both
+``.rst`` files that contains pages in the documentation, folders that contain more
+``.rst`` files, and configuration for Sphinx.


missing some word here. configuration files ?

story645 · 2017-04-27T22:32:34Z

doc/devel/documenting_mpl.rst

+  An exception to this are the folders :file:`gallery` and :file:`tutorials`, which
+  exist in the root folder. These contain python files that are built by ``sphinx-gallery``.
+  When the docs are built, folders of the same name will be generated inside of :file:`docs/`.
+  These can be safely deleted.


which docs, the ones in docs or the ones in gallery?

story645 · 2017-04-27T22:32:59Z

doc/devel/documenting_mpl.rst

+There are many other flags you can pass to ``make.py``, and you can see the
+full list inside that file. Here are two useful ones:
+
+* ``clean`` will delete the built sphinx files. Call if you're getting strange


hehe - I meant "call make.py with this input", will fix

choldgraf · 2017-04-28T01:06:56Z

thx for the comments @story645 , all addressed

phobson · 2017-04-28T01:15:57Z

doc/devel/documenting_mpl.rst


-The output produced by Sphinx can be configured by editing the :file:`conf.py`
-file located in the :file:`doc/`.
+* ``--allowsphinxwarnings`` will allow the docs to continue building even if sphinx


I needed this information! thanks for this

omg my life changed when I found out about this. Instead of re-running for each warning, one at a time, you can just see the output of all the warnings, change them all in one swoop, and then re-build when you want to!

phobson

LGTM. I'll merge pending CI success.

story645 · 2017-04-28T01:35:01Z

doc/devel/documenting_mpl.rst

+-----------------
+
+All documentation is built from the :file:`doc/` directory. This folder contains both
+``.rst`` files that contains pages in the documentation, folders that contain more


contain pages

story645 · 2017-04-28T01:38:08Z

doc/devel/documenting_mpl.rst

+  When the docs are built, folders of the same name will be generated inside of :file:`docs/`.
+  The generated folders :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.
+
+The configuration file for Sphinx is in :file:`doc/conf.py`. It controls which folders


is :file:doc/conf.py

story645 · 2017-04-28T01:40:13Z

doc/devel/documenting_mpl.rst

+
+  * You'll need a minimal working latex distribution for many examples to run.
+  * `Graphviz <http://graphviz.readthedocs.io/en/latest/manual.html>`_ is not pip-installable so you need
+    to install this on your own. This is straightforward with something like


Not sure the conda reference is helpful here 'cause it's not really contextualized.

story645 · 2017-04-28T01:40:47Z

doc/devel/documenting_mpl.rst

-you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
-arguments to build everything.
+There are many other flags you can pass to ``make.py``, and you can see the
+full list inside that file. Here are two useful ones:


or run ./make.py --help? (maybe?)

I put this in the flags section

choldgraf · 2017-04-28T02:02:35Z

another round of changes made - very helpful @story645 , thanks!

QuLogic

Capitalization is minor, but the link is the major thing.

QuLogic · 2017-04-28T02:07:29Z

doc/devel/documenting_mpl.rst

+.. note::
+
+  * You'll need a minimal working latex distribution for many examples to run.
+  * `Graphviz <http://graphviz.readthedocs.io/en/latest/manual.html>`_ is not pip-installable so you need


This link is not to the right graphviz. It is here.

QuLogic · 2017-04-28T02:08:07Z

doc/devel/documenting_mpl.rst

@@ -19,6 +24,31 @@ The requirements are as follows (https://github.com/matplotlib/matplotlib/blob/m
 6. pillow
 7. graphviz

+.. note::
+
+  * You'll need a minimal working latex distribution for many examples to run.


QuLogic · 2017-04-28T02:08:28Z

doc/devel/documenting_mpl.rst

+.. note::
+
+  An exception to this are the folders :file:`gallery` and :file:`tutorials`, which
+  exist in the root folder. These contain python files that are built by ``sphinx-gallery``.


QuLogic · 2017-04-28T02:09:08Z

doc/devel/documenting_mpl.rst

+General structure
+-----------------
+
+All documentation is built from the :file:`doc/` directory. This folder contains both


One case of "directory" and many of "folder"; I think we should be consistent about it (preferring directory, myself.)

QuLogic · 2017-04-28T02:09:58Z

doc/devel/documenting_mpl.rst

+
+* ``clean`` will delete the built sphinx files. Use this command if you're getting strange
+  errors about missing paths or broken links, particularly if you move files around.
+* ``latex`` builds a pdf of the documentation.


QuLogic · 2017-04-28T02:10:45Z

doc/devel/documenting_mpl.rst

+  The generated folders :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.
+
+The configuration file for Sphinx is :file:`doc/conf.py`. It controls which folders
+sphinx parses, how the docs are built, and how the extensions are used.


QuLogic · 2017-04-28T02:10:52Z

doc/devel/documenting_mpl.rst

+There are many other flags you can pass to ``make.py``, and you can see the
+full list inside that file. Here are two useful ones:
+
+* ``clean`` will delete the built sphinx files. Use this command if you're getting strange


QuLogic · 2017-04-28T02:10:59Z

doc/devel/documenting_mpl.rst

-The output produced by Sphinx can be configured by editing the :file:`conf.py`
-file located in the :file:`doc/`.
+* ``--help`` will (among other things) display the allowed commands for ``make.py``.
+* ``--allowsphinxwarnings`` will allow the docs to continue building even if sphinx


QuLogic · 2017-04-28T02:11:47Z

doc/devel/documenting_mpl.rst

@@ -7,9 +7,14 @@ Developer's tips for documenting matplotlib
 Getting started
 ===============

+Installing dependencies
+-----------------------
+
 The documentation for matplotlib is generated from ReStructured Text using the


It's actually (the rather oddly capitalized) reStructuredText.

choldgraf · 2017-04-28T02:26:04Z

ok I think @QuLogic comments addressed

QuLogic

Minor pluralization.

QuLogic · 2017-04-28T02:31:07Z

doc/devel/documenting_mpl.rst

-  The generated folders :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.
+  An exception to this are the directories :file:`gallery` and :file:`tutorials`, which
+  exist in the root directory. These contain Python files that are built by ``sphinx-gallery``.
+  When the docs are built, directory of the same name will be generated inside of :file:`docs/`.


directories

QuLogic · 2017-04-28T02:31:14Z

doc/devel/documenting_mpl.rst

-All documentation is built from the :file:`doc/` directory. This folder contains both
-``.rst`` files that contain pages in the documentation, folders that contain more
+All documentation is built from the :file:`doc/` directory. This directory contains both
+``.rst`` files that contain pages in the documentation, directory that contain more


directories

QuLogic · 2017-04-28T02:31:24Z

doc/devel/documenting_mpl.rst


-The configuration file for Sphinx is :file:`doc/conf.py`. It controls which folders
-sphinx parses, how the docs are built, and how the extensions are used.
+The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directory


directories

choldgraf · 2017-04-28T02:33:05Z

ugh, that's what I get for ctrl+f ing the world "folder". good catch

jenshnielsen · 2017-04-28T10:55:09Z

doc/devel/documenting_mpl.rst

+
+  * You'll need a minimal working LaTeX distribution for many examples to run.
+  * `Graphviz <http://www.graphviz.org/Download.php>`_ is not pip-installable so you need
+    to install this on your own.


To me this sounds like Graphviz is a python package which just happens to be non pip installable. I think it could be made more clear that it is a completely separate binary and not a python package.

jenshnielsen · 2017-04-28T10:55:42Z

Apart from inline comment 👍

anntzer · 2017-04-28T17:10:44Z

doc/devel/documenting_mpl.rst

+.. note::
+
+  An exception to this are the directories :file:`gallery` and :file:`tutorials`, which
+  exist in the root directory. These contain Python files that are built by ``sphinx-gallery``.


s-g should be be a link instead of double-quoted, similarly to Sphinx_ (note the underscore) at the top. The link targets are listed a bit in the middle of nowhere (just before the Figure section), may be worth moving them to the top or the bottom or the file (or just use inline link format like for graphviz above).

choldgraf · 2017-04-28T17:14:38Z

how does that look @jenshnielsen ?

choldgraf · 2017-04-28T17:24:06Z

does that look correct @anntzer ?

anntzer · 2017-04-28T18:51:18Z

Probably, but you should try building :-)

jenshnielsen · 2017-04-28T19:09:07Z

great thanks @choldgraf

choldgraf · 2017-04-28T19:27:21Z

@anntzer good call - it wasn't quite right but the latest push builds correctly :)

choldgraf · 2017-04-29T07:46:13Z

🍻

story645 · 2017-04-30T21:46:44Z

I now want to undo one of my statements 'cause now I get why you made that comment about anaconda. Though I'd then say, "can be installed with conda conda install -c conda-forge graphviz

choldgraf · 2017-04-30T21:58:49Z

yeah - I like things to be as actionable / straightforward as possible for users/devs, though I think most folks will be able to figure it out w/o this language in there. I could go either way

story645 · 2017-04-30T22:42:22Z

I'm tempted to do something like, if you're using conda, you can install the following requirements as follows:

conda install sphinx numpydoc ipython mock pillow -y
conda install -c conda-forge graphviz -y

Ugh, really hate that there's a mix of pip and conda here. :(

updating developer docs

83129fa

choldgraf force-pushed the devel_docs branch from e4a8df8 to 83129fa Compare April 27, 2017 19:40

story645 reviewed Apr 27, 2017

View reviewed changes

addressing comments

0baccc7

phobson reviewed Apr 28, 2017

View reviewed changes

phobson approved these changes Apr 28, 2017

View reviewed changes

story645 reviewed Apr 28, 2017

View reviewed changes

Update documenting_mpl.rst

530c62d

QuLogic requested changes Apr 28, 2017

View reviewed changes

Update documenting_mpl.rst

23f4757

QuLogic approved these changes Apr 28, 2017

View reviewed changes

Update documenting_mpl.rst

5efe61c

story645 approved these changes Apr 28, 2017

View reviewed changes

jenshnielsen reviewed Apr 28, 2017

View reviewed changes

Update documenting_mpl.rst

ff1b20e

anntzer reviewed Apr 28, 2017

View reviewed changes

Update documenting_mpl.rst

c6866a0

fixing link

d73ff15

phobson merged commit e69bdaa into matplotlib:master Apr 28, 2017

QuLogic added this to the 2.1 (next point release) milestone Apr 28, 2017

QuLogic added the Documentation label Apr 28, 2017

story645 mentioned this pull request Apr 30, 2017

Add pillow and graphviz to doc build dependencies #7793

Closed

story645 mentioned this pull request May 2, 2017

Update list of dependencies to build docs #8174

Closed

updating developer docs #8544

updating developer docs #8544

Conversation

choldgraf commented Apr 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Apr 28, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phobson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Apr 28, 2017 • edited Loading

QuLogic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Apr 28, 2017

QuLogic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Apr 28, 2017

Choose a reason for hiding this comment

jenshnielsen commented Apr 28, 2017

Choose a reason for hiding this comment

choldgraf commented Apr 28, 2017

choldgraf commented Apr 28, 2017 • edited Loading

anntzer commented Apr 28, 2017

jenshnielsen commented Apr 28, 2017

choldgraf commented Apr 28, 2017

choldgraf commented Apr 29, 2017

story645 commented Apr 30, 2017

choldgraf commented Apr 30, 2017

story645 commented Apr 30, 2017 • edited Loading

choldgraf commented Apr 28, 2017 •

edited

Loading

choldgraf commented Apr 28, 2017 •

edited

Loading

story645 commented Apr 30, 2017 •

edited

Loading