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.