From 7005e23c1d5d227c6a1fa84178938ec49e84134f Mon Sep 17 00:00:00 2001 From: Alison Spencer Date: Sun, 21 Oct 2018 16:13:51 -0400 Subject: [PATCH 1/4] added specific instructions for setting up a dev environment and installing mpl and dependencies for documentation editing --- doc/devel/documenting_mpl.rst | 80 ++++++++++++++++++++++++++++++++--- 1 file changed, 75 insertions(+), 5 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index ecb86d53651e..4f46c71d0320 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -41,7 +41,8 @@ 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. -Installing dependencies + +Dependencies ----------------------- The documentation for Matplotlib is generated from reStructuredText (ReST_) @@ -51,17 +52,86 @@ requirements that are needed to build the documentation. They are listed in * Sphinx>=1.3, !=1.5.0, !=1.6.4, !=1.7.3 * colorspacious -* IPython +* IPython<7.0.0 * numpydoc>=0.4 * Pillow * sphinx-gallery>=0.1.13 +* LaTeX * graphviz .. note:: - * You'll need a minimal working LaTeX distribution for many examples to run. - * `Graphviz `_ is not a Python package, - and needs to be installed separately. + * You'll need a minimal working `LaTeX `_ distribution for many examples in the documentation to run. + * `Graphviz `_ is not a Python package, + and needs to be installed separately. + + +Creating a development environment +---------------------------------- + +It's suggested that you create a separate python environment for working on matplotlib. You can do this using `conda `_ or `virtualenv `_. You'll need to use python3 to work on the most current version of Matplotlib. + +Create your environment: + +.. code-block:: sh + + conda create --name matplotlib_dev python=3 + +or + +.. code-block:: sh + + virtualenv -p matplotlib_dev + +Install python dependencies + +.. code-block:: sh + + pip install -r doc-requirements.txt + +or + +.. code-block:: sh + + conda install -c conda-forge --file doc-requirements.txt + +.. note:: + + * colorspacious must be installed using conda-forge, not conda + +Install non-python dependencies: + +* Install the `LaTeX `_ version for your OS +* Install `Graphviz `_ for your OS + + +Install the most recent version of matplotlib: + +.. code-block:: sh + + pip install matplotlib=="3.0.0" + +or + +.. code-block:: sh + + conda install -c conda-forge matplotlib mpl_sample_data + +Create a fork of the matplotlib repo to your personal github account, and clone the forked repo to your machine: + +* On the `matplotlib github page `_, fork the repo +* Once you've created your fork, clone the repo to your machine: + +.. code-block:: sh + + git clone
+ +Create a new branch in your forked repo to make changes: + +.. code-block:: sh + + git checkout -b my-branch-name + Building the docs ----------------- From 1f3637ff18e773b60e3867c949046429b1db2f0a Mon Sep 17 00:00:00 2001 From: Alison Spencer Date: Sun, 2 Dec 2018 17:11:54 -0500 Subject: [PATCH 2/4] removed duplication of instructions between contributing and documenting --- doc/devel/contributing.rst | 5 ++- doc/devel/documenting_mpl.rst | 70 +++++++---------------------------- 2 files changed, 16 insertions(+), 59 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 5140260b3f63..c73469e11f3d 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -64,7 +64,7 @@ environment to build Matplotlib from source. To work on Matplotlib sources, it is strongly recommended to set up an alternative development environment, using the something like `virtual environments in python `_, or a -`conda environment `_. +`conda environment `_. If you choose to use an already existing environment, and not a clean virtual or conda environment, uninstall the current version of Matplotlib in that environment @@ -158,6 +158,7 @@ environment is set up properly:: * :ref:`testing` +.. _how_to_contribute: Contributing code ================= @@ -315,7 +316,7 @@ 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 doc/ directory. Details for contributing to the documentation can be found :ref:`here `. It also helps us if you spread the word: reference the project from your blog and articles or link to it from your website! diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index af673867a2ab..243864a1f4b5 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -47,15 +47,22 @@ 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` and listed below: +requirements, in addition to those in :ref:`Contributing `, that are needed to build the documentation. They are listed in +:file:`doc-requirements.txt` and below: -* Sphinx>=1.3, !=1.5.0, !=1.6.4, !=1.7.3 +* Sphinx * colorspacious * IPython +<<<<<<< Updated upstream * numpydoc>=0.8 * Pillow>=3.4 * sphinx-gallery>=0.2 +======= +* numpydoc +* Pillow +* sphinx-gallery +* LaTeX +>>>>>>> Stashed changes * graphviz .. note:: @@ -65,72 +72,21 @@ requirements that are needed to build the documentation. They are listed in and needs to be installed separately. -Creating a development environment +Install dependencies and create a documentation development environment ---------------------------------- -It's suggested that you create a separate python environment for working on matplotlib. You can do this using `conda `_ or `virtualenv `_. You'll need to use python3 to work on the most current version of Matplotlib. +* See :ref:`installing_for_devs` and :ref:`how_to_contribute` to get the latest version of the code, set up a development environment, and create pull requests. -Create your environment: - -.. code-block:: sh - - conda create --name matplotlib_dev python=3 - -or - -.. code-block:: sh - - virtualenv -p matplotlib_dev - -Install python dependencies - -.. code-block:: sh - - pip install -r doc-requirements.txt - -or - -.. code-block:: sh - - conda install -c conda-forge --file doc-requirements.txt +* Install the python dependencies in `doc-requirements.txt`: .. note:: * colorspacious must be installed using conda-forge, not conda -Install non-python dependencies: - * Install the `LaTeX `_ version for your OS * Install `Graphviz `_ for your OS -Install the most recent version of matplotlib: - -.. code-block:: sh - - pip install matplotlib=="3.0.0" - -or - -.. code-block:: sh - - conda install -c conda-forge matplotlib mpl_sample_data - -Create a fork of the matplotlib repo to your personal github account, and clone the forked repo to your machine: - -* On the `matplotlib github page `_, fork the repo -* Once you've created your fork, clone the repo to your machine: - -.. code-block:: sh - - git clone
- -Create a new branch in your forked repo to make changes: - -.. code-block:: sh - - git checkout -b my-branch-name - Building the docs ----------------- From fabaac91405d699e6f0ed7560ad37bc2a0a98a34 Mon Sep 17 00:00:00 2001 From: Alison Spencer Date: Sun, 2 Dec 2018 17:12:08 -0500 Subject: [PATCH 3/4] removed duplication of instructions between contributing and documenting --- doc/devel/documenting_mpl.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 243864a1f4b5..0c64d926653d 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -53,16 +53,10 @@ requirements, in addition to those in :ref:`Contributing `, that a * Sphinx * colorspacious * IPython -<<<<<<< Updated upstream -* numpydoc>=0.8 -* Pillow>=3.4 -* sphinx-gallery>=0.2 -======= * numpydoc * Pillow * sphinx-gallery * LaTeX ->>>>>>> Stashed changes * graphviz .. note:: From 2f0528374b62525aafe0451250a5d283b3baeb61 Mon Sep 17 00:00:00 2001 From: Alison Spencer Date: Sun, 2 Dec 2018 22:02:22 -0500 Subject: [PATCH 4/4] fixed rst title underlining --- doc/devel/documenting_mpl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 0c64d926653d..d6155b051a8b 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -67,7 +67,7 @@ requirements, in addition to those in :ref:`Contributing `, that a Install dependencies and create a documentation development environment ----------------------------------- +----------------------------------------------------------------------- * See :ref:`installing_for_devs` and :ref:`how_to_contribute` to get the latest version of the code, set up a development environment, and create pull requests. 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