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

Commit b2422b0

Browse filesBrowse files
tacaswelltacaswell
authored
Merge pull request #21251 from jklymak/doc-more-reorg
DOC: more site re-org
2 parents 033ba05 + 3b58108 commit b2422b0
Copy full SHA for b2422b0
Expand file treeCollapse file tree

40 files changed

+224
-181
lines changed

‎INSTALL.rst

Copy file name to clipboardExpand all lines: INSTALL.rst
-7Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,6 @@
22
Installation
33
############
44

5-
.. toctree::
6-
:hidden:
7-
8-
installing_source.rst
9-
../faq/installing_faq.rst
10-
11-
125
==============================
136
Installing an official release
147
==============================

‎doc/README.txt

Copy file name to clipboardExpand all lines: doc/README.txt
+9-4Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,20 @@ This is the top level build directory for the Matplotlib
1313
documentation. All of the documentation is written using sphinx, a
1414
python documentation system built on top of ReST. This directory contains
1515

16-
* users - the user documentation, e.g., plotting tutorials, configuration
17-
tips, etc.
16+
* users - the user documentation, e.g., installation, plotting tutorials,
17+
configuration tips, faq, explaations, etc.
1818

1919
* devel - documentation for Matplotlib developers
2020

21-
* faq - frequently asked questions
22-
2321
* api - placeholders to automatically generate the api documentation
2422

23+
* tutorials, plot_types, and gallery - automatically
24+
generated by sphinx-gallery from ``../tutorials``, ``../plot_types``, and
25+
``../examples`` respectively (these are only present if docs have been
26+
built locally).
27+
28+
* thirdpartypackages - redirect to <https://matplotlib.org/mpl-third-party/>
29+
2530
* mpl_toolkits - documentation of individual toolkits that ship with
2631
Matplotlib
2732

‎doc/_templates/mpl_nav_bar.html

Copy file name to clipboardExpand all lines: doc/_templates/mpl_nav_bar.html
+3-6Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,12 @@
1010
<a class="reference internal nav-link" href="{{ pathto('tutorials/index') }}">Tutorials</a>
1111
</li>
1212
<li class="nav-item">
13-
<a class="reference internal nav-link" href="{{ pathto('api/index') }}">Reference</a>
13+
<a class="reference internal nav-link" href="{{ pathto('api/index') }}">API Reference</a>
1414
</li>
1515
<li class="nav-item">
16-
<a class="reference internal nav-link" href="{{ pathto('users/index') }}">Usage guide</a>
16+
<a class="reference internal nav-link" href="{{ pathto('users/index') }}">Users guide</a>
1717
</li>
1818
<li class="nav-item">
19-
<a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Develop</a>
20-
</li>
21-
<li class="nav-item">
22-
<a class="reference internal nav-link" href="{{ pathto('users/release_notes') }}">Release notes</a>
19+
<a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Contributing</a>
2320
</li>
2421
</ul>

‎doc/api/index.rst

Copy file name to clipboardExpand all lines: doc/api/index.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Reference
2-
=========
1+
API Reference
2+
=============
33

44
When using the library you will typically create
55
:doc:`Figure <figure_api>` and :doc:`Axes <axes_api>` objects and

‎doc/api/prev_api_changes/api_changes_3.1.0.rst

Copy file name to clipboardExpand all lines: doc/api/prev_api_changes/api_changes_3.1.0.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,7 @@ FreeType or libpng are not in the compiler or linker's default path, set the
308308
standard environment variables ``CFLAGS``/``LDFLAGS`` on Linux or OSX, or
309309
``CL``/``LINK`` on Windows, to indicate the relevant paths.
310310

311-
See details in :doc:`/users/installing`.
311+
See details in :doc:`/users/installing/index`.
312312

313313
Setting artist properties twice or more in the same call
314314
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎doc/conf.py

Copy file name to clipboardExpand all lines: doc/conf.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ def _check_dependencies():
212212
source_encoding = "utf-8"
213213

214214
# The master toctree document.
215-
master_doc = 'contents'
215+
master_doc = 'users/index'
216216

217217
# General substitutions.
218218
try:

‎doc/contents.rst

Copy file name to clipboardExpand all lines: doc/contents.rst
-25Lines changed: 0 additions & 25 deletions
This file was deleted.

‎doc/devel/contributing.rst

Copy file name to clipboardExpand all lines: doc/devel/contributing.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,7 @@ Other ways to contribute
275275
It also helps us if you spread the word: reference the project from your blog
276276
and articles or link to it from your website! If Matplotlib contributes to a
277277
project that leads to a scientific publication, please follow the
278-
:doc:`/citing` guidelines.
278+
:doc:`/users/backmatter/citing` guidelines.
279279

280280
.. _coding_guidelines:
281281

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+27-26Lines changed: 27 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -10,34 +10,35 @@ Getting started
1010
General file structure
1111
----------------------
1212

13-
All documentation is built from the :file:`doc/`, :file:`tutorials/`, and
14-
:file:`examples/` directories. The :file:`doc/` directory contains
15-
configuration files for Sphinx and reStructuredText (ReST_; ``.rst``) files
16-
that are rendered to documentation pages.
13+
All documentation is built from the :file:`doc/`. The :file:`doc/`
14+
directory contains configuration files for Sphinx and reStructuredText
15+
(ReST_; ``.rst``) files that are rendered to documentation pages.
1716

18-
19-
The main entry point is :file:`doc/index.rst`, which pulls in the
20-
:file:`index.rst` file for the users guide (:file:`doc/users`), developers
21-
guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs
22-
(:file:`doc/faq`). The documentation suite is built as a single document in
23-
order to make the most effective use of cross referencing.
24-
25-
Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
17+
Documentation is created in three ways. First, API documentation
18+
(:file:`doc/api`) is created by Sphinx_ from
2619
the docstrings of the classes in the Matplotlib library. Except for
27-
:file:`doc/api/api_changes/`, these ``.rst`` files are created when the
28-
documentation is built.
29-
30-
Similarly, the contents of :file:`doc/gallery` and :file:`doc/tutorials` are
31-
generated by the `Sphinx Gallery`_ from the sources in :file:`examples/` and
32-
:file:`tutorials/`. These sources consist of python scripts that have ReST_
33-
documentation built into their comments.
20+
:file:`doc/api/api_changes/`, ``.rst`` files in :file:`doc/api` are created
21+
when the documentation is built. See :ref:`writing-docstrings` below.
22+
23+
Second, the contents of :file:`doc/plot_types`, :file:`doc/gallery` and
24+
:file:`doc/tutorials` are generated by the `Sphinx Gallery`_ from python
25+
files in :file:`plot_types/`, :file:`examples/` and :file:`tutorials/`.
26+
These sources consist of python scripts that have ReST_ documentation built
27+
into their comments. See :ref:`writing-examples-and-tutorials` below.
28+
29+
Third, Matplotlib has narrative docs written in ReST_ in subdirectories of
30+
:file:`doc/users/`. If you would like to add new documentation that is suited
31+
to an ``.rst`` file rather than a gallery or tutorial example, choose an
32+
appropriate subdirectory to put it in, and add the file to the table of
33+
contents of :file:`index.rst` of the subdirectory. See
34+
:ref:`writing-rest-pages` below.
3435

3536
.. note::
3637

37-
Don't directly edit the ``.rst`` files in :file:`doc/gallery`,
38-
:file:`doc/tutorials`, and :file:`doc/api` (excepting
39-
:file:`doc/api/api_changes/`). Sphinx_ regenerates files in these
40-
directories when building documentation.
38+
Don't directly edit the ``.rst`` files in :file:`doc/plot_types`,
39+
:file:`doc/gallery`, :file:`doc/tutorials`, and :file:`doc/api`
40+
(excepting :file:`doc/api/api_changes/`). Sphinx_ regenerates
41+
files in these directories when building documentation.
4142

4243
Setting up the doc build
4344
------------------------
@@ -181,22 +182,22 @@ Documents can be linked with the ``:doc:`` directive:
181182

182183
.. code-block:: rst
183184
184-
See the :doc:`/faq/installing_faq`
185+
See the :doc:`/users/faq/installing_faq`
185186
186187
See the tutorial :doc:`/tutorials/introductory/sample_plots`
187188
188189
See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
189190
190191
will render as:
191192

192-
See the :doc:`/faq/installing_faq`
193+
See the :doc:`/users/faq/installing_faq`
193194

194195
See the tutorial :doc:`/tutorials/introductory/sample_plots`
195196

196197
See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
197198

198199
Sections can also be given reference names. For instance from the
199-
:doc:`/faq/installing_faq` link:
200+
:doc:`/users/faq/installing_faq` link:
200201

201202
.. code-block:: rst
202203

‎doc/index.rst

Copy file name to clipboardExpand all lines: doc/index.rst
+6-6Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ Installation
3838
pip install matplotlib
3939
4040
41-
Further details are available in the :doc:`Installation Guide <users/installing>`.
41+
Further details are available in the :doc:`Installation Guide <users/installing/index>`.
4242

4343

4444
Learning resources
@@ -53,7 +53,7 @@ Learning resources
5353
- :doc:`Quick-start guide <tutorials/introductory/usage>`
5454
- :doc:`Plot types <plot_types/index>`
5555
- `Introductory tutorials <../tutorials/index.html#introductory>`_
56-
- :doc:`External learning resources <resources/index>`
56+
- :doc:`External learning resources <users/resources/index>`
5757

5858
---
5959

@@ -67,7 +67,7 @@ Learning resources
6767
Understand how Matplotlib works
6868
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6969

70-
- The :ref:`users-guide-explain` in the :doc:`Usage guide <users/index>`
70+
- The :ref:`users-guide-explain` in the :doc:`Users guide <users/index>`
7171
- Many of the :ref:`Intermediate <tutorials-intermediate>` and
7272
:ref:`Advanced <tutorials-advanced>` tutorials
7373
have explanatory material
@@ -106,7 +106,7 @@ you can help!
106106
- or improve the :ref:`documentation and code <developers-guide-index>`
107107

108108

109-
Site map
110-
--------
109+
Users guide
110+
-----------
111111

112-
The :ref:`complete contents of the docs <complete_sitemap>`.
112+
The `contents of the docs <users/index.html>`_.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.