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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy