From bd1e4b2b1d324a62fe55da8cb81f2ee4eaac2ac0 Mon Sep 17 00:00:00 2001 From: Amy Roberts Date: Sat, 14 Mar 2020 22:58:08 -0600 Subject: [PATCH 1/4] improve-doc-contrib: improvements to contrib instructions for docs --- doc/devel/contributing.rst | 21 +++++++++++++----- doc/devel/documenting_mpl.rst | 41 +++++++++++++++++++++-------------- 2 files changed, 41 insertions(+), 21 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index f9a115e47c1c..a79478f6bc97 100644 --- 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 index bf48e6093b46..6232ad0ef085 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -18,16 +18,16 @@ 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 @@ -35,11 +35,15 @@ the docstrings of the classes in the Matplotlib library. Except for 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 `_ 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 `_ 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 ----------------- From d9e75c6b7de1afab2e092abd22c38eb1846d3756 Mon Sep 17 00:00:00 2001 From: Amy Roberts Date: Sat, 14 Mar 2020 23:55:38 -0600 Subject: [PATCH 2/4] improve-doc-contrib: update links and references for doc contrib --- doc/devel/contributing.rst | 14 +++++++++----- doc/devel/documenting_mpl.rst | 11 ++++++----- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index a79478f6bc97..53f346d8d38a 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -127,6 +127,8 @@ You can then run the tests to check your work environment is set up properly:: Contributing code ================= +.. _how-to-contribute: + How to contribute ----------------- @@ -175,7 +177,7 @@ want to consider sending an email to the mailing list for more visibility. * `Git documentation `_ * `Git-Contributing to a Project `_ * `Introduction to GitHub `_ - * :ref:`development-workflow`. + * :ref:`development-workflow` * :ref:`using-git` Contributing pull requests @@ -284,8 +286,10 @@ 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 :file:`doc/`, :file:`tutorials/`, and :file:`examples/` directories. +list or submit a GitHub pull request as 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` @@ -298,8 +302,8 @@ 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! If Matplotlib contributes to a -project that leads to a scientific publication, please follow these guidelines -for citation :doc:`/citing`. +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 index 6232ad0ef085..808ec91b7feb 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -41,9 +41,10 @@ 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. + 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 ----------------------- @@ -58,14 +59,14 @@ requirements that are needed to build the documentation. They are listed in .. note:: + * You should set up a clean virtual environment with no existing Matplotlib + installation if you plan to build the documentation. * 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 `_ 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 ----------------- From 7aa60af117788f8e9ef5a5596cf0214646b29efe Mon Sep 17 00:00:00 2001 From: Amy Roberts Date: Sun, 15 Mar 2020 07:29:30 -0600 Subject: [PATCH 3/4] improve-doc-contrib: edits to dependencies for building docs --- doc/devel/contributing.rst | 3 ++- doc/devel/documenting_mpl.rst | 34 +++++++++++++++++++++++----------- 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 53f346d8d38a..ab2360393a5e 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -286,7 +286,8 @@ 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 as outlined in :ref:`how-to-contribute`. +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. diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 808ec91b7feb..45fa29472083 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -50,23 +50,35 @@ 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 `_ + .. note:: - * You should set up a clean virtual environment with no existing Matplotlib - installation if you plan to build the documentation. - * 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 `_ 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 ----------------- From afb2dbea374a520a9c98546c0bf91aa88103b97d Mon Sep 17 00:00:00 2001 From: hannah Date: Mon, 16 Mar 2020 12:38:29 -0400 Subject: [PATCH 4/4] Update documenting_mpl.rst just tried to reorg the bit under general file structure to be a little clearer --- 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 45fa29472083..9de294517ca2 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -19,9 +19,9 @@ General file structure ---------------------- 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_. +:file:`examples/` directories. The :file:`doc/` directory contains configuration files for Sphinx +and reStructuredText (ReST_; ``.rst``) files that are rendered to documentation pages. + 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