Docs/contrib #12584
Docs/contrib #12584
Conversation
…alling mpl and dependencies for documentation editing
|
You had a rebase that seems to have gone bad and included to many commits. Can you try again? |
|
It's not a rebase; the target is |
doc/devel/documenting_mpl.rst
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
Needs to be clarified wrt #12583.
There was a problem hiding this comment.
This will get out of sync again in the future. Can we just refer to doc-requirements.txt instead of listing everything explicitly here again? Or literalinclude if we want that information written out here.
doc/devel/documenting_mpl.rst
Outdated
| Creating a development environment | ||
| ---------------------------------- | ||
|
|
||
| It's suggested that you create a separate python environment for working on matplotlib. You can do this using `conda <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_ or `virtualenv <https://virtualenv.pypa.io/en/stable/>`_. You'll need to use python3 to work on the most current version of Matplotlib. |
There was a problem hiding this comment.
I'd rather consolidate this with what's already in contributing.rst rather than duplicating the same info in two places with two slightly different variants.
There was a problem hiding this comment.
I can merge it with what's in contributing.rst, but I do think that precise instructions are helpful for beginners looking to contribute specifically to the documentation. Would links between documenting_mpl.rst and contributing.rst be a reasonable solution?
doc/devel/documenting_mpl.rst
Outdated
|
|
||
| .. code-block:: sh | ||
|
|
||
| pip install matplotlib=="3.0.0" |
doc/devel/documenting_mpl.rst
Outdated
|
|
||
| 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: |
There was a problem hiding this comment.
Again this info should be consolidated with the testing docs rather than being spread out.
| @@ -41,27 +41,46 @@ 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 | |||
| ----------------------- | |||
There was a problem hiding this comment.
| ----------------------- | |
| ------------ |
| ----------------------- | ||
|
|
||
| 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 <contributing>`, that are needed to build the documentation. They are listed in |
There was a problem hiding this comment.
https://16523-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/devel/contributing.html actially doesn't list the dependencies.
The whole paragraph could be rephrased to:
Building the documentation requires the following extra requirements:
- Sphinx
...See :file:
doc-requirements.txtfor the exact version requirements. You can also use this file to install the dependencies using your package manager:python -m pip install -r doc-requirements.txt # or conda install --file doc-requirements.txt
|
Content is now present in the current documentation. @alisonspencer Sorry that the PR stalled. Anyway, thanks for the contribution! |
PR Summary
Added specific instructions for getting started modifying the mpl documentation - examples for installing matplotlib & dependencies using pip/conda, creating an isolated conda/virtualenv environment, and added links to sites to install LaTeX & Graphviz.
PR Checklist