@@ -10,34 +10,35 @@ Getting started
1010General 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 bySphinx _ from
2619the 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 haveReST _
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 haveReST _ documentation built
27+ into their comments. See:ref: `writing-examples-and-tutorials ` below.
28+
29+ Third, Matplotlib has narrative docs written inReST _ 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 _ regeneratesfiles 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:file: `doc/api `
40+ (excepting :file: `doc/api/api_changes/ `).Sphinx _ regenerates
41+ files in these directories when building documentation.
4142
4243Setting up the doc build
4344------------------------
@@ -181,7 +182,7 @@ 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