Merge pull request #16809 from meeseeksmachine/auto-backport-of-pr-16779-on-v3.2.0-doc

QuLogic · web-flow · commit a40622f87c3d · 2020-03-17T17:13:03.000-04:00
Backport PR #16779 on branch v3.2.0-doc (Documentation: make instructions for documentation contributions easier to find, add to requirements for building docs)
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -174,6 +174,8 @@ environment is set up properly::
 Contributing code
 =================
 
+.. _how-to-contribute:
+
 How to contribute
 -----------------
 
@@ -222,7 +224,7 @@ want to consider sending an email to the mailing list for more visibility.
   * `Git documentation <https://git-scm.com/documentation>`_
   * `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
   * `Introduction to GitHub  <https://lab.github.com/githubtraining/introduction-to-github>`_
-  * :ref:`development-workflow`.
+  * :ref:`development-workflow`
   * :ref:`using-git`
 
 Contributing pull requests
@@ -316,21 +318,35 @@ 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.
+list or submit a GitHub pull request.  To make a pull request, refer to the
+guidelines outlined in :ref:`how-to-contribute`.
+
+Full documentation can be found under 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 the
+:doc:`/citing` guidelines.
 
 .. _coding_guidelines:
 
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -18,45 +18,67 @@ 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 configuration files for Sphinx
+and  reStructuredText (ReST_; ``.rst``) files that are rendered to documentation pages. 
 
-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`, 
+  :file:`doc/tutorials`, and :file:`doc/api` (excepting
+  :file:`doc/api/api_changes/`).  Sphinx_ regenerates files in these
+  directories when building documentation.
 
 Installing dependencies
 -----------------------
 
 The documentation for Matplotlib is generated from reStructuredText (ReST_)
-using 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`, which is shown below:
+using the Sphinx_ documentation generation tool. To build the documentation
+you will need to (1) set up an appropriate Python environment and (2)
+separately install LaTeX and Graphviz.
+
+To (1) set up an appropriate Python environment for building the
+documentation, you should:
+
+*  create a clean virtual environment with no existing Matplotlib
+   installation
+*  install the Python packages required for Matplotlib
+*  install the additional Python packages required to build the documentation
+
+There are several extra python packages that are needed to build the
+documentation. They are listed in :file:`doc-requirements.txt`, which is
+shown below:
 
 .. include:: ../../requirements/doc/doc-requirements.txt
    :literal:
 
+To (2) set up LaTeX and Graphviz dependencies you should:
+
+*  install a minimal working LaTeX distribution
+*  install the LaTeX packages cm-super and dvipng
+*  install `Graphviz <http://www.graphviz.org/download>`_
+
 .. 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,
-    and needs to be installed separately.
+  The documentation will not build without LaTeX and Graphviz.  These are not
+  Python packages and must be installed separately.
 
 Building the docs
 -----------------
