diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index f9a115e47c1c..ab2360393a5e 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 @@ -274,21 +276,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 bf48e6093b46..9de294517ca2 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 ----------------- 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