From 83129fa03c49988ee08070bb7846d42e665f1bed Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 27 Apr 2017 12:27:56 -0700 Subject: [PATCH 1/8] updating developer docs --- doc/devel/documenting_mpl.rst | 48 ++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 050e31dae564..b5705038769d 100644 --- a/doc/devel/documenting_mpl.rst +++ b/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 -Sphinx_ documentation generation tool. -The requirements are as follows (https://github.com/matplotlib/matplotlib/blob/master/doc-requirements.txt) +Sphinx_ documentation generation tool. There are several extra requirements that +are needed to build the documentation. They are listed in the file +`doc-requirements.txt `_ +as well as listed below: 1. Sphinx-1.3 or later(Version 1.5.0 is not supported) 2. numpydoc 0.4 or later @@ -19,6 +24,30 @@ 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. + * Graphviz is not pip-installable so you need to install this on your own. + +General structure +----------------- + +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. + +.. 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``. + When the docs are built, folders of the same name will be generated inside of :file:`docs/`. + These can be safely deleted. + +The configuration file for Sphinx is in :file:`doc/conf.py`. It controls which folders +sphinx parses, how the docs are built, and how the extensions are used. + +Building the docs +----------------- The documentation sources are found in the :file:`doc/` directory in the trunk. To build the users guide in html format, cd into @@ -30,11 +59,18 @@ or:: ./make.py html -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: + +* ``clean`` will delete the built sphinx files. Call 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 + +In addition, these are useful flags: -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 + throws a warning. This is useful for debugging and spot-checking many warnings + at once. Organization of matplotlib's documentation From 0baccc76b3f87f22129c42afa59b5e86df81ff98 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 27 Apr 2017 18:06:40 -0700 Subject: [PATCH 2/8] addressing comments --- doc/devel/documenting_mpl.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index b5705038769d..5211266959cd 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -27,21 +27,23 @@ as well as listed below: .. 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. + * `Graphviz `_ is not pip-installable so you need + to install this on your own. This is straightforward with something like + the `anaconda distribution `_. General structure ----------------- 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. +``.rst`` files, and configuration files for Sphinx. .. 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``. When the docs are built, folders of the same name will be generated inside of :file:`docs/`. - These can be safely deleted. + 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 sphinx parses, how the docs are built, and how the extensions are used. @@ -62,9 +64,9 @@ or:: 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 +* ``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 +* ``latex`` builds a pdf of the documentation. In addition, these are useful flags: From 530c62db76c74380fcc5fca9b3c893fbb9fa0b74 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 27 Apr 2017 19:02:19 -0700 Subject: [PATCH 3/8] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 5211266959cd..4349ad8cceae 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -28,14 +28,13 @@ as well as listed below: * 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. This is straightforward with something like - the `anaconda distribution `_. + to install this on your own. General structure ----------------- 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 that contain pages in the documentation, folders that contain more ``.rst`` files, and configuration files for Sphinx. .. note:: @@ -45,7 +44,7 @@ All documentation is built from the :file:`doc/` directory. This folder contains 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 +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. Building the docs @@ -70,6 +69,7 @@ full list inside that file. Here are two useful ones: In addition, these are useful flags: +* ``--help`` will (among other things) display the allowed commands for ``make.py``. * ``--allowsphinxwarnings`` will allow the docs to continue building even if sphinx throws a warning. This is useful for debugging and spot-checking many warnings at once. From 23f4757b2fcb934d7a35347f861ba349134b36a1 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 27 Apr 2017 19:25:48 -0700 Subject: [PATCH 4/8] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 4349ad8cceae..f2926452bde9 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -10,7 +10,7 @@ Getting started Installing dependencies ----------------------- -The documentation for matplotlib is generated from ReStructured Text using the +The documentation for matplotlib is generated from reStructuredText using the Sphinx_ documentation generation tool. There are several extra requirements that are needed to build the documentation. They are listed in the file `doc-requirements.txt `_ @@ -26,26 +26,26 @@ as well as listed below: .. note:: - * You'll need a minimal working latex distribution for many examples to run. - * `Graphviz `_ is not pip-installable so you need + * 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. General structure ----------------- -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 ``.rst`` files, and configuration files for Sphinx. .. 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``. - 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. + 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/`. + The generated directories :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. +The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directory +Sphinx parses, how the docs are built, and how the extensions are used. Building the docs ----------------- @@ -63,14 +63,14 @@ or:: 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 +* ``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. +* ``latex`` builds a PDF of the documentation. In addition, these are useful flags: * ``--help`` will (among other things) display the allowed commands for ``make.py``. -* ``--allowsphinxwarnings`` will allow the docs to continue building even if sphinx +* ``--allowsphinxwarnings`` will allow the docs to continue building even if Sphinx throws a warning. This is useful for debugging and spot-checking many warnings at once. From 5efe61cd8108ffdd0f2df1056d5eb53d1edd1bea Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 27 Apr 2017 19:32:49 -0700 Subject: [PATCH 5/8] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index f2926452bde9..7ddd97911a76 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -34,17 +34,17 @@ General structure ----------------- 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 +``.rst`` files that contain pages in the documentation, directories that contain more ``.rst`` files, and configuration files for Sphinx. .. 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``. - When the docs are built, directory of the same name will be generated inside of :file:`docs/`. + When the docs are built, directories of the same name will be generated inside of :file:`docs/`. The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted. -The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directory +The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directories Sphinx parses, how the docs are built, and how the extensions are used. Building the docs From ff1b20ed115ca7761f4d1659351ea1d02f875d09 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 28 Apr 2017 09:58:31 -0700 Subject: [PATCH 6/8] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 7ddd97911a76..53581291593d 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -27,8 +27,8 @@ as well as listed below: .. 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. + * `Graphviz `_ is not a python package, and needs + to be installed separately. General structure ----------------- From c6866a0db83d8c1fa116320cb85dffd27c716da6 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 28 Apr 2017 10:23:27 -0700 Subject: [PATCH 7/8] Update documenting_mpl.rst --- doc/devel/documenting_mpl.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 53581291593d..dbd94dd3bb47 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -35,12 +35,12 @@ General structure All documentation is built from the :file:`doc/` directory. This directory contains both ``.rst`` files that contain pages in the documentation, directories that contain more -``.rst`` files, and configuration files for Sphinx. +``.rst`` files, and configuration files for Sphinx_. .. 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``. + exist in the root directory. These contain Python files that are built by `Sphinx Gallery `_. When the docs are built, directories of the same name will be generated inside of :file:`docs/`. The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted. @@ -302,11 +302,6 @@ working with Sphinx in general. Here are a few additional things to keep in mind * The autodoc extension will handle index entries for the API, but additional entries in the index_ need to be explicitly added. -.. _Sphinx: http://www.sphinx-doc.org -.. _documentation: http://www.sphinx-doc.org/contents.html -.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html -.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup - * Please limit the text width of docstrings to 70 characters. * Keyword arguments should be described using a definition list. @@ -542,3 +537,9 @@ Some helpful functions:: Shift region to the right .. TODO: Add section about uploading docs + +.. _Sphinx: http://www.sphinx-doc.org +.. _documentation: http://www.sphinx-doc.org/contents.html +.. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html +.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup +.. _sphinx_gallery: https://sphinx-gallery.readthedocs.io/en/latest/ From d73ff15aa11cb18c70e683bfeae70260b9ddd926 Mon Sep 17 00:00:00 2001 From: Christopher Holdgraf Date: Fri, 28 Apr 2017 12:26:08 -0700 Subject: [PATCH 8/8] fixing link --- doc/devel/documenting_mpl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index dbd94dd3bb47..226971ba11bc 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -40,7 +40,7 @@ All documentation is built from the :file:`doc/` directory. This directory conta .. 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 `_. + exist in the root directory. These contain Python files that are built by `Sphinx Gallery`_. When the docs are built, directories of the same name will be generated inside of :file:`docs/`. The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted. @@ -542,4 +542,4 @@ Some helpful functions:: .. _documentation: http://www.sphinx-doc.org/contents.html .. _`inline markup`: http://www.sphinx-doc.org/markup/inline.html .. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup -.. _sphinx_gallery: https://sphinx-gallery.readthedocs.io/en/latest/ +.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/