Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commita40622f

Browse files
authored
Merge pull request#16809 from meeseeksmachine/auto-backport-of-pr-16779-on-v3.2.0-doc
Backport PR#16779 on branch v3.2.0-doc (Documentation: make instructions for documentation contributions easier to find, add to requirements for building docs)
2 parents984f5d6 +5ef8a12 commita40622f

File tree

2 files changed

+65
-27
lines changed

2 files changed

+65
-27
lines changed

‎doc/devel/contributing.rst‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,8 @@ environment is set up properly::
174174
Contributing code
175175
=================
176176

177+
.. _how-to-contribute:
178+
177179
How to contribute
178180
-----------------
179181

@@ -222,7 +224,7 @@ want to consider sending an email to the mailing list for more visibility.
222224
* `Git documentation<https://git-scm.com/documentation>`_
223225
* `Git-Contributing to a Project<https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
224226
* `Introduction to GitHub<https://lab.github.com/githubtraining/introduction-to-github>`_
225-
*:ref:`development-workflow`.
227+
*:ref:`development-workflow`
226228
*:ref:`using-git`
227229

228230
Contributing pull requests
@@ -316,21 +318,35 @@ This helps the contributor become familiar with the contribution
316318
workflow, and for the core devs to become acquainted with the contributor;
317319
besides which, we frequently underestimate how easy an issue is to solve!
318320

319-
.. _other_ways_to_contribute:
320321

321-
Other ways to contribute
322-
=========================
322+
.. _contributing_documentation:
323323

324+
Contributing documentation
325+
==========================
324326

325327
Code is not the only way to contribute to Matplotlib. For instance,
326328
documentation is also a very important part of the project and often doesn't
327329
get as much attention as it deserves. If you find a typo in the documentation,
328330
or have made improvements, do not hesitate to send an email to the mailing
329-
list or submit a GitHub pull request. Full documentation can be found under
330-
the doc/ directory.
331+
list or submit a GitHub pull request. To make a pull request, refer to the
332+
guidelines outlined in:ref:`how-to-contribute`.
333+
334+
Full documentation can be found under the:file:`doc/`,:file:`tutorials/`,
335+
and:file:`examples/` directories.
336+
337+
..seealso::
338+
*:ref:`documenting-matplotlib`
339+
340+
341+
.. _other_ways_to_contribute:
342+
343+
Other ways to contribute
344+
=========================
331345

332346
It also helps us if you spread the word: reference the project from your blog
333-
and articles or link to it from your website!
347+
and articles or link to it from your website! If Matplotlib contributes to a
348+
project that leads to a scientific publication, please follow the
349+
:doc:`/citing` guidelines.
334350

335351
.. _coding_guidelines:
336352

‎doc/devel/documenting_mpl.rst‎

Lines changed: 42 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,45 +18,67 @@ Getting started
1818
General file structure
1919
----------------------
2020

21-
All documentation is built from the:file:`doc/` directory. This directory
22-
contains both reStructuredText (ReST_; ``.rst``) files that contain pages in
23-
the documentation and configurationfilesforSphinx_.
21+
All documentation is built from the:file:`doc/`,:file:`tutorials/`, and
22+
:file:`examples/` directories. The:file:`doc/` directory contains configuration files for Sphinx
23+
and reStructuredText (ReST_; ``.rst``)filesthat are rendered to documentation pages.
2424

25-
The ``.rst`` files are kept in:file:`doc/users`,
26-
:file:`doc/devel`,:file:`doc/api` and:file:`doc/faq`. The main entry point is
27-
:file:`doc/index.rst`, which pulls inthe:file:`index.rst` file for the users
28-
guide, developers guide, api reference, and FAQs. The documentation suite is
29-
built as a single document in order to make the most effective use of cross
30-
referencing.
25+
26+
The main entry point is:file:`doc/index.rst`, which pulls in the
27+
:file:`index.rst` file fortheusers guide (:file:`doc/users`), developers
28+
guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
29+
(:file:`doc/faq`). The documentation suite isbuilt as a single document in
30+
order to make the most effective use of crossreferencing.
3131

3232
Sphinx_ also creates ``.rst`` files that are staged in:file:`doc/api` from
3333
the docstrings of the classes in the Matplotlib library. Except for
3434
:file:`doc/api/api_changes/`, these ``.rst`` files are created when the
3535
documentation is built.
3636

3737
Similarly, the contents of:file:`doc/gallery` and:file:`doc/tutorials` are
38-
generated by the `Sphinx Gallery`_ from the sources in:file:`examples` and
39-
:file:`tutorials`. These sources consist of python scripts that haveReST_
40-
documentation built into their comments. Don't directly edit the
41-
``.rst`` files in:file:`doc/gallery` and:file:`doc/tutorials` as they are
42-
regenerated when the documentation are built.
38+
generated by the `Sphinx Gallery`_ from the sources in:file:`examples/` and
39+
:file:`tutorials/`. These sources consist of python scripts that haveReST_
40+
documentation built into their comments.
41+
42+
..note::
43+
44+
Don't directly edit the ``.rst`` files in:file:`doc/gallery`,
45+
:file:`doc/tutorials`, and:file:`doc/api` (excepting
46+
:file:`doc/api/api_changes/`).Sphinx_ regenerates files in these
47+
directories when building documentation.
4348

4449
Installing dependencies
4550
-----------------------
4651

4752
The documentation for Matplotlib is generated from reStructuredText (ReST_)
48-
using theSphinx_ documentation generation tool. There are several extra
49-
requirements that are needed to build the documentation. They are listed in
50-
:file:`doc-requirements.txt`, which is shown below:
53+
using theSphinx_ documentation generation tool. To build the documentation
54+
you will need to (1) set up an appropriate Python environment and (2)
55+
separately install LaTeX and Graphviz.
56+
57+
To (1) set up an appropriate Python environment for building the
58+
documentation, you should:
59+
60+
* create a clean virtual environment with no existing Matplotlib
61+
installation
62+
* install the Python packages required for Matplotlib
63+
* install the additional Python packages required to build the documentation
64+
65+
There are several extra python packages that are needed to build the
66+
documentation. They are listed in:file:`doc-requirements.txt`, which is
67+
shown below:
5168

5269
..include::../../requirements/doc/doc-requirements.txt
5370
:literal:
5471

72+
To (2) set up LaTeX and Graphviz dependencies you should:
73+
74+
* install a minimal working LaTeX distribution
75+
* install the LaTeX packages cm-super and dvipng
76+
* install `Graphviz<http://www.graphviz.org/download>`_
77+
5578
..note::
5679

57-
* You'll need a minimal working LaTeX distribution for many examples to run.
58-
* `Graphviz<http://www.graphviz.org/Download.php>`_ is not a Python package,
59-
and needs to be installed separately.
80+
The documentation will not build without LaTeX and Graphviz. These are not
81+
Python packages and must be installed separately.
6082

6183
Building the docs
6284
-----------------

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp