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

Skip to content

Commit 8c398fb

Browse files
tacaswelltacaswell
authored
Merge pull request #21419 from meeseeksmachine/auto-backport-of-pr-21251-on-v3.5.x
Backport PR #21251 on branch v3.5.x (DOC: more site re-org)
2 parents 2ac2bc8 + 4fbf1d8 commit 8c398fb

40 files changed

+224
-181
lines changed

‎INSTALL.rst

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ def _check_dependencies():
213213
source_encoding = "utf-8"
214214

215215
# The master toctree document.
216-
master_doc = 'contents'
216+
master_doc = 'users/index'
217217

218218
# General substitutions.
219219
try:

‎doc/contents.rst

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎doc/devel/contributing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,7 @@ Other ways to contribute
265265
It also helps us if you spread the word: reference the project from your blog
266266
and articles or link to it from your website! If Matplotlib contributes to a
267267
project that leads to a scientific publication, please follow the
268-
:doc:`/citing` guidelines.
268+
:doc:`/users/backmatter/citing` guidelines.
269269

270270
.. _coding_guidelines:
271271

‎doc/devel/documenting_mpl.rst

Lines 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

Lines 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)