diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 0f5909d697b9..73d5124c60b9 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -174,6 +174,8 @@ environment is set up properly:: Contributing code ================= +.. _how-to-contribute: + How to contribute ----------------- @@ -222,7 +224,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 @@ -316,21 +318,35 @@ 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. +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. + +.. 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 the +:doc:`/citing` guidelines. .. _coding_guidelines: diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 2c467b3753b2..57bc871d1d49 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 configuration files for Sphinx +and reStructuredText (ReST_; ``.rst``) files that are rendered to documentation pages. -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,28 +35,50 @@ 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`, + :file:`doc/tutorials`, and :file:`doc/api` (excepting + :file:`doc/api/api_changes/`). Sphinx_ regenerates files in these + directories when building documentation. 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'll need a minimal working LaTeX distribution for many examples to run. - * `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 -----------------