Skip to content

Navigation Menu

Sign in

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
Appearance settings

Commit 119a7df

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

7 files changed

+155
-133
lines changed

‎doc/devel/contribute.rst

Copy file name to clipboardExpand all lines: doc/devel/contribute.rst
+4-3Lines 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

Copy file name to clipboard
+124Lines 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

Copy file name to clipboardExpand all lines: doc/devel/document_format.rst
+6-122Lines 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

Copy file name to clipboardExpand all lines: doc/devel/document_style.rst
+7-3Lines 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

Copy file name to clipboardExpand all lines: doc/devel/document_tag.rst
+6-2Lines 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

Copy file name to clipboardExpand all lines: doc/devel/document_tag_glossary.rst
+4Lines 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

Copy file name to clipboardExpand all lines: doc/devel/index.rst
+4-3Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.