improve-doc-contrib: improvements to contrib instructions for docs

pibion · pibion · commit bd1e4b2b1d32 · 2020-03-14T22:58:08.000-06:00
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -274,21 +274,32 @@ This helps the contributor become familiar with the contribution
 workflow, and for the core devs to become acquainted with the contributor;
 besides which, we frequently underestimate how easy an issue is to solve!
 
-.. _other_ways_to_contribute:
 
-Other ways to contribute
-=========================
+.. _contributing_documentation:
 
+Contributing documentation
+==========================
 
 Code is not the only way to contribute to Matplotlib. For instance,
 documentation is also a very important part of the project and often doesn't
 get as much attention as it deserves. If you find a typo in the documentation,
 or have made improvements, do not hesitate to send an email to the mailing
 list or submit a GitHub pull request. Full documentation can be found under
-the doc/ directory.
+the :file:`doc/`, :file:`tutorials/`, and :file:`examples/` directories.
+
+.. seealso::
+  * :ref:`documenting-matplotlib`
+
+
+.. _other_ways_to_contribute:
+
+Other ways to contribute
+=========================
 
 It also helps us if you spread the word: reference the project from your blog
-and articles or link to it from your website!
+and articles or link to it from your website!  If Matplotlib contributes to a
+project that leads to a scientific publication, please follow these guidelines
+for citation :doc:`/citing`.
 
 .. _coding_guidelines:
 
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -18,28 +18,32 @@ Getting started
 General file structure
 ----------------------
 
-All documentation is built from the :file:`doc/` directory.  This directory
-contains both reStructuredText (ReST_; ``.rst``) files that contain pages in
-the documentation and configuration files for Sphinx_.
+All documentation is built from the :file:`doc/`, :file:`tutorials/`, and
+:file:`examples/` directories.  The :file:`doc/` directory contains both
+reStructuredText (ReST_; ``.rst``) files that contain pages in the
+documentation and configuration files for Sphinx_.
 
-The ``.rst`` files are kept in :file:`doc/users`,
-:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is
-:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users
-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.
+The main entry point is :file:`doc/index.rst`, which pulls in the
+:file:`index.rst` file for the users guide (:file:`doc/users`), developers
+guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
+(:file:`doc/faq`). The documentation suite is built as a single document in
+order to make the most effective use of cross referencing.
 
 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`` files are created when the
 documentation is built.
 
 Similarly, the contents of :file:`doc/gallery` and :file:`doc/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.  Don't directly edit the
-``.rst`` files in :file:`doc/gallery` and :file:`doc/tutorials` as they are
-regenerated when the documentation are built.
+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.
+
+.. note::
+
+  Don't directly edit the ``.rst`` files in :file:`doc/gallery` and
+  :file:`doc/tutorials` as they are regenerated when the documentation are
+  built.
 
 Installing dependencies
 -----------------------
@@ -54,9 +58,14 @@ requirements that are needed to build the documentation. They are listed in
 
 .. note::
 
-  * You'll need a minimal working LaTeX distribution for many examples to run.
-  * `Graphviz <http://www.graphviz.org/Download.php>`_ is not a Python package,
+  * You'll need a minimal working LaTeX distribution to build the
+    documentation.
+  * The LaTeX pacakges cm-super and dvipng are also required to build the
+    documentation.
+  * `Graphviz <http://www.graphviz.org/download>`_ is not a Python package,
     and needs to be installed separately.
+  * You should set up a clean `virtual environment`_ if you plan to build the
+    documentation.  
 
 Building the docs
 -----------------
