Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 119a7df

Browse files
story645story645
committed
reorged doc docs to have common prefix and seperate doc build page
1 parent 2d5e503 commit 119a7df

7 files changed

Lines changed: 155 additions & 133 deletions

File tree

‎doc/devel/contribute.rst‎

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

138138
Instructions and guidelines for contributing documentation are found in:
139139

140-
* :doc:`document`
141-
* :doc:`style_guide`
142-
* :doc:`tag_guidelines`
140+
* :doc:`document_build`
141+
* :doc:`document_format`
142+
* :doc:`document_style`
143+
* :doc:`document_tag`
143144

144145
Documentation is contributed through pull requests, so we recommend that you start
145146
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 by Sphinx_ 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 in ReST_ 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 the Sphinx_ 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+
set SPHINXOPTS= & set O=-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.rst renamed to doc/devel/document_format.rst

Lines changed: 6 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +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 by Sphinx_ 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 in ReST_ 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 the Sphinx_ 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_docs:
56-
57-
Build the docs
58-
--------------
59-
60-
The documentation sources are found in the :file:`doc/` directory.
61-
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
62-
directories Sphinx parses, how the docs are built, and how the extensions are
63-
used. To build the documentation in html format, cd into :file:`doc/` and run:
64-
65-
.. code-block:: sh
66-
67-
make html
68-
69-
.. note::
4+
.. _document-format:
705

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

12710
.. _writing-rest-pages:
12811

@@ -1183,11 +1066,12 @@ style or topbar should be made there to propagate across all subprojects.
11831066

11841067
.. TODO: Add section about uploading docs
11851068
1069+
11861070
.. _ReST: https://docutils.sourceforge.io/rst.html
11871071
.. _Sphinx: http://www.sphinx-doc.org
1072+
.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
11881073
.. _documentation: https://www.sphinx-doc.org/en/master/contents.html
11891074
.. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
1190-
.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
11911075
.. _references: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html
11921076
.. _`numpydoc docstring guide`: https://numpydoc.readthedocs.io/en/latest/format.html
11931077
.. _`Manually passing files`: https://sphinx-gallery.github.io/stable/configuration.html#manually-passing-files

doc/devel/style_guide.rst renamed 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.rst renamed 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.rst renamed 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
@@ -220,9 +220,10 @@ manage, or release manage, these guidelines describe how our current process wor
220220
.. toctree::
221221
:maxdepth: 1
222222

223-
document
224-
style_guide
225-
tag_guidelines
223+
document_build
224+
document_format
225+
document_style
226+
document_tag
226227

227228
.. grid-item-card::
228229
:shadow: none

0 commit comments

Comments
 (0)