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

Skip to content

Commit c5164b1

Browse files
story645story645
committed
reorged doc docs to have common prefix and seperate doc build page
1 parent 9b8a8c7 commit c5164b1

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 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 & 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 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 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-
set SPHINXOPTS= & set O=-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.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
@@ -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)