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

Commitc5164b1

Browse files
committed
reorged doc docs to have common prefix and seperate doc build page
1 parent9b8a8c7 commitc5164b1

7 files changed

+155
-131
lines changed

‎doc/devel/contribute.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,9 +150,10 @@ Other documentation is generated from the following external sources:
150150

151151
Instructions and guidelines for contributing documentation are found in:
152152

153-
*:doc:`document`
154-
*:doc:`style_guide`
155-
*:doc:`tag_guidelines`
153+
*:doc:`document_build`
154+
*:doc:`document_format`
155+
*:doc:`document_style`
156+
*:doc:`document_tag`
156157

157158
Documentation is contributed through pull requests, so we recommend that you start
158159
at:ref:`how-to-pull-request`. If that feels intimidating, we encourage you to

‎doc/devel/document_build.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
..redirect-from::/devel/document
2+
3+
.. _documenting-matplotlib:
4+
.. _document-build:
5+
6+
*******************
7+
Build Documentation
8+
*******************
9+
10+
All documentation is built from the:file:`doc/`. The:file:`doc/`
11+
directory contains configuration files for Sphinx and reStructuredText
12+
(ReST_; ``.rst``) files that are rendered to documentation pages.
13+
14+
General file structure
15+
======================
16+
Documentation is created in three ways. First, API documentation
17+
(:file:`doc/api`) is created bySphinx_ from
18+
the docstrings of the classes in the Matplotlib library. Except for
19+
:file:`doc/api/api_changes/`, ``.rst`` files in:file:`doc/api` are created
20+
when the documentation is built. See:ref:`writing-docstrings` below.
21+
22+
Second, our example pages, tutorials, and some of the narrative documentation
23+
are created by `Sphinx Gallery`_. Sphinx Gallery converts example Python files
24+
to ``*.rst`` files with the result of Matplotlib plot calls as embedded images.
25+
See:ref:`writing-examples-and-tutorials` below.
26+
27+
Third, Matplotlib has narrative docs written inReST_ in subdirectories of
28+
:file:`doc/users/`. If you would like to add new documentation that is suited
29+
to an ``.rst`` file rather than a gallery or tutorial example, choose an
30+
appropriate subdirectory to put it in, and add the file to the table of
31+
contents of:file:`index.rst` of the subdirectory. See
32+
:ref:`writing-rest-pages` below.
33+
34+
..note::
35+
36+
Don't directly edit the ``.rst`` files in:file:`doc/plot_types`,
37+
:file:`doc/gallery`,:file:`doc/tutorials`, and:file:`doc/api`
38+
(excepting:file:`doc/api/api_changes/`).Sphinx_ regenerates
39+
files in these directories when building documentation.
40+
41+
Set up the build
42+
================
43+
44+
The documentation for Matplotlib is generated from reStructuredText (ReST_)
45+
using theSphinx_ documentation generation tool.
46+
47+
To build the documentation you will need to
48+
:ref:`set up Matplotlib for development<installing_for_devs>`. Note in
49+
particular the:ref:`additional dependencies<doc-dependencies>` required to
50+
build the documentation.
51+
52+
Build the docs
53+
==============
54+
55+
The documentation sources are found in the:file:`doc/` directory.
56+
The configuration file for Sphinx is:file:`doc/conf.py`. It controls which
57+
directories Sphinx parses, how the docs are built, and how the extensions are
58+
used. To build the documentation in html format, cd into:file:`doc/` and run:
59+
60+
..code-block::sh
61+
62+
make html
63+
64+
..note::
65+
66+
Since the documentation is very large, the first build may take 10-20 minutes,
67+
depending on your machine. Subsequent builds will be faster.
68+
69+
Other useful invocations include
70+
71+
..code-block::sh
72+
73+
# Build the html documentation, but skip generation of the gallery images to
74+
# save time.
75+
make html-noplot
76+
77+
# Build the html documentation, but skip specific subdirectories. If a gallery
78+
# directory is skipped, the gallery images are not generated. The first
79+
# time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
80+
# to add or remove subdirectories
81+
make html-skip-subdirs
82+
83+
# Delete built files. May help if you get errors about missing paths or
84+
# broken links.
85+
make clean
86+
87+
# Build pdf docs.
88+
make latexpdf
89+
90+
The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
91+
the complete docs but exit with exit status 1 if there are warnings. To unset
92+
it, use
93+
94+
..code-block::sh
95+
96+
make SPHINXOPTS= html
97+
98+
You can use the ``O`` variable to set additional options:
99+
100+
* ``make O=-j4 html`` runs a parallel build with 4 processes.
101+
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
102+
103+
Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100'
104+
html``.
105+
106+
On Windows, set the options as environment variables, e.g.:
107+
108+
..code-block::bat
109+
110+
setSPHINXOPTS=&setO=-j4 -Dplot_formats=png:100& make html
111+
112+
Show locally built docs
113+
=======================
114+
115+
The built docs are available in the folder:file:`build/html`. A shortcut
116+
for opening them in your default browser is:
117+
118+
..code-block::sh
119+
120+
make show
121+
122+
.. _ReST:https://docutils.sourceforge.io/rst.html
123+
.. _Sphinx:http://www.sphinx-doc.org
124+
.. _`Sphinx Gallery`:https://sphinx-gallery.readthedocs.io/en/latest/

‎doc/devel/document.rstrenamed to‎doc/devel/document_format.rst

Lines changed: 6 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,11 @@
11
..redirect-from::/devel/documenting_mpl
22

3-
.. _documenting-matplotlib:
43

5-
===================
6-
Write documentation
7-
===================
8-
9-
Getting started
10-
===============
11-
12-
General file structure
13-
----------------------
14-
15-
All documentation is built from the:file:`doc/`. The:file:`doc/`
16-
directory contains configuration files for Sphinx and reStructuredText
17-
(ReST_; ``.rst``) files that are rendered to documentation pages.
18-
19-
Documentation is created in three ways. First, API documentation
20-
(:file:`doc/api`) is created bySphinx_ from
21-
the docstrings of the classes in the Matplotlib library. Except for
22-
:file:`doc/api/api_changes/`, ``.rst`` files in:file:`doc/api` are created
23-
when the documentation is built. See:ref:`writing-docstrings` below.
24-
25-
Second, our example pages, tutorials, and some of the narrative documentation
26-
are created by `Sphinx Gallery`_. Sphinx Gallery converts example Python files
27-
to ``*.rst`` files with the result of Matplotlib plot calls as embedded images.
28-
See:ref:`writing-examples-and-tutorials` below.
29-
30-
Third, Matplotlib has narrative docs written inReST_ in subdirectories of
31-
:file:`doc/users/`. If you would like to add new documentation that is suited
32-
to an ``.rst`` file rather than a gallery or tutorial example, choose an
33-
appropriate subdirectory to put it in, and add the file to the table of
34-
contents of:file:`index.rst` of the subdirectory. See
35-
:ref:`writing-rest-pages` below.
36-
37-
..note::
38-
39-
Don't directly edit the ``.rst`` files in:file:`doc/plot_types`,
40-
:file:`doc/gallery`,:file:`doc/tutorials`, and:file:`doc/api`
41-
(excepting:file:`doc/api/api_changes/`).Sphinx_ regenerates
42-
files in these directories when building documentation.
43-
44-
Set up the build
45-
----------------
46-
47-
The documentation for Matplotlib is generated from reStructuredText (ReST_)
48-
using theSphinx_ documentation generation tool.
49-
50-
To build the documentation you will need to
51-
:ref:`set up Matplotlib for development<installing_for_devs>`. Note in
52-
particular the:ref:`additional dependencies<doc-dependencies>` required to
53-
build the documentation.
54-
55-
Build the docs
56-
--------------
57-
58-
The documentation sources are found in the:file:`doc/` directory.
59-
The configuration file for Sphinx is:file:`doc/conf.py`. It controls which
60-
directories Sphinx parses, how the docs are built, and how the extensions are
61-
used. To build the documentation in html format, cd into:file:`doc/` and run:
62-
63-
..code-block::sh
64-
65-
make html
66-
67-
..note::
68-
69-
Since the documentation is very large, the first build may take 10-20 minutes,
70-
depending on your machine. Subsequent builds will be faster.
4+
.. _document-format:
715

72-
Other useful invocations include
73-
74-
..code-block::sh
75-
76-
# Build the html documentation, but skip generation of the gallery images to
77-
# save time.
78-
make html-noplot
79-
80-
# Build the html documentation, but skip specific subdirectories. If a gallery
81-
# directory is skipped, the gallery images are not generated. The first
82-
# time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
83-
# to add or remove subdirectories
84-
make html-skip-subdirs
85-
86-
# Delete built files. May help if you get errors about missing paths or
87-
# broken links.
88-
make clean
89-
90-
# Build pdf docs.
91-
make latexpdf
92-
93-
The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
94-
the complete docs but exit with exit status 1 if there are warnings. To unset
95-
it, use
96-
97-
..code-block::sh
98-
99-
make SPHINXOPTS= html
100-
101-
You can use the ``O`` variable to set additional options:
102-
103-
* ``make O=-j4 html`` runs a parallel build with 4 processes.
104-
* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
105-
106-
Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100'
107-
html``.
108-
109-
On Windows, set the options as environment variables, e.g.:
110-
111-
..code-block::bat
112-
113-
setSPHINXOPTS=&setO=-j4 -Dplot_formats=png:100& make html
114-
115-
Show locally built docs
116-
-----------------------
117-
118-
The built docs are available in the folder:file:`build/html`. A shortcut
119-
for opening them in your default browser is:
120-
121-
..code-block::sh
122-
123-
make show
6+
*******************
7+
Write documentation
8+
*******************
1249

12510
.. _writing-rest-pages:
12611

@@ -1174,11 +1059,12 @@ style or topbar should be made there to propagate across all subprojects.
11741059

11751060
.. TODO: Add section about uploading docs
11761061
1062+
11771063
.. _ReST:https://docutils.sourceforge.io/rst.html
11781064
.. _Sphinx:http://www.sphinx-doc.org
1065+
.. _`Sphinx Gallery`:https://sphinx-gallery.readthedocs.io/en/latest/
11791066
.. _documentation:https://www.sphinx-doc.org/en/master/contents.html
11801067
.. _index:http://www.sphinx-doc.org/markup/para.html#index-generating-markup
1181-
.. _`Sphinx Gallery`:https://sphinx-gallery.readthedocs.io/en/latest/
11821068
.. _references:https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html
11831069
.. _`numpydoc docstring guide`:https://numpydoc.readthedocs.io/en/latest/format.html
11841070
.. _`Manually passing files`:https://sphinx-gallery.github.io/stable/configuration.html#manually-passing-files

‎doc/devel/style_guide.rstrenamed to‎doc/devel/document_style.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1+
..redirect-from::/devel/style_guide
12

2-
=========================
3-
Documentation style guide
4-
=========================
3+
.. _document_style:
4+
5+
***********
6+
Style guide
7+
***********
58

69
This guide contains best practices for the language and formatting of Matplotlib
710
documentation.
@@ -410,6 +413,7 @@ This style guide is not a comprehensive standard. For a more thorough
410413
reference of how to contribute to documentation, see the links below. These
411414
resources contain common best practices for writing documentation.
412415

416+
413417
* `Python Developer's Guide<https://devguide.python.org/documenting/#documenting-python>`_
414418
* `Google Developer Style Guide<https://developers.google.com/style>`_
415419
* `IBM Style Guide<https://www.oreilly.com/library/view/the-ibm-style/9780132118989/>`_

‎doc/devel/tag_guidelines.rstrenamed to‎doc/devel/document_tag.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
..redirect-from::/devel/tag_guidelines
2+
3+
.. _document-tag-guidelines:
4+
15
Tagging guidelines
26
==================
37

@@ -50,10 +54,10 @@ title or the scope of the example.
5054
..toctree::
5155
:maxdepth:2
5256

53-
tag_glossary
57+
document_tag_glossary
5458

5559
+++
56-
See:doc:`Tag Glossary<tag_glossary>` for a complete list
60+
See:ref:`Tag Glossary<document-tag-glossary>` for a complete list
5761

5862
Proposing new tags
5963
------------------

‎doc/devel/tag_glossary.rstrenamed to‎doc/devel/document_tag_glossary.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
..redirect-from::/devel/tag_glossary
2+
3+
.. _document-tag-glossary:
4+
15
Tag Glossary
26
============
37

‎doc/devel/index.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -185,9 +185,10 @@ Policies and guidelines
185185
..toctree::
186186
:maxdepth:1
187187

188-
document
189-
style_guide
190-
tag_guidelines
188+
document_build
189+
document_format
190+
document_style
191+
document_tag
191192

192193
..grid-item-card::
193194
:shadow: none

0 commit comments

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