@@ -71,109 +71,6 @@ The list of comamnds and flags for ``make.py`` can be listed by running
7171 if Sphinx throws a warning. This is useful for debugging and spot-checking
7272 many warnings at once.
7373
74-
75- Organization of Matplotlib's documentation
76- ==========================================
77-
78- The actual reStructured Text files are kept in:file: `doc/users `,
79- :file: `doc/devel `,:file: `doc/api ` and:file: `doc/faq `. The main entry point is
80- :file: `doc/index.rst `, which pulls in the:file: `index.rst ` file for the users
81- guide, developers guide, api reference, and FAQs. The documentation suite is
82- built as a single document in order to make the most effective use of cross
83- referencing (we want to make navigating the Matplotlib documentation as easy as
84- possible).
85-
86- Additional files can be added to the various guides by including their base
87- file name (the .rst extension is not necessary) in the table of contents.
88- It is also possible to include other documents through the use of an include
89- statement, such as::
90-
91- .. include:: ../../TODO
92-
93- docstrings
94- ----------
95-
96- In addition to the "narrative" documentation described above,
97- Matplotlib also defines its API reference documentation in docstrings.
98- For the most part, these are standard Python docstrings, but
99- Matplotlib also includes some features to better support documenting
100- getters and setters.
101-
102- Matplotlib uses artist introspection of docstrings to support properties.
103- All properties that you want to support through `~.pyplot.setp ` and
104- `~.pyplot.getp ` should have a ``set_property `` and ``get_property `` method in
105- the `~.matplotlib.artist.Artist ` class. Yes, this is not ideal given python
106- properties or enthought traits, but it is a historical legacy for now. The
107- setter methods use the docstring with the ACCEPTS token to indicate the type of
108- argument the method accepts. e.g., in `.Line2D `:
109-
110- ..code-block ::python
111-
112- # in lines.py
113- def set_linestyle (self linestyle ):
114- """
115- Set the linestyle of the line
116-
117- ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
118- """
119-
120- kwargs ``, e.g., in every function
121- that creates a line (`~.pyplot.plot `, `~.pyplot.semilogx `, `~.pyplot.semilogy `,
122- etc...), it can be difficult for the new user to know which ``kwargs `` are
123- supported. Matplotlib uses a docstring interpolation scheme to support
124- documentation of every function that takes a ``**kwargs ``. The requirements
125- are:
126-
127- 1. single point of configuration so changes to the properties don't
128- require multiple docstring edits.
129-
130- 2. as automated as possible so that as properties change, the docs
131- are updated automatically.
132-
133- The function `matplotlib.artist.kwdoc ` and the decorator
134- `matplotlib.docstring.dedent_interpd ` facilitate this. They combine Python
135- string interpolation in the docstring with the Matplotlib artist introspection
136- facility that underlies ``setp `` and ``getp ``. The ``kwdoc `` function gives
137- the list of properties as a docstring. In order to use this in another
138- docstring, first update the ``matplotlib.docstring.interpd `` object, as seen in
139- this example from `matplotlib.lines `:
140-
141- ..code-block ::python
142-
143- # in lines.py
144- docstring.interpd.update(Line2D = artist.kwdoc(Line2D))
145-
146- ~.Line2D ` pass-through ``kwargs ``, e.g.,
147- `matplotlib.axes.Axes.plot `:
148-
149- ..code-block ::python
150-
151- # in axes.py
152- @docstring.dedent_interpd
153- def plot (self * args ,** kwargs ):
154- """
155- Some stuff omitted
156-
157- The kwargs are Line2D properties:
158- %(Line2D)s
159-
160- kwargs scalex and scaley, if defined, are passed on
161- to autoscale_view to determine whether the x and y axes are
162- autoscaled; default True. See Axes.autoscale_view for more
163- information
164- """
165- pass
166-
167- ~matplotlib.artist.Artist ` ``__init__ `` methods,
168- e.g., `matplotlib.patches.Patch.__init__ `, which supports ``Patch `` ``kwargs ``,
169- since the artist inspector cannot work until the class is fully defined and
170- we can't modify the ``Patch.__init__.__doc__ `` docstring outside the class
171- definition. There are some some manual hacks in this case, violating the
172- "single entry point" requirement above -- see the ``docstring.interpd.update ``
173- calls in `matplotlib.patches `.
174-
175- .. _formatting-mpl-docs :
176-
17774Formatting
17875==========
17976
@@ -269,7 +166,7 @@ usual way by LaTeX. For example,
269166:math: `\int _{-\infty }^{\infty }\frac {e^{i\phi }}{1 +x^2 \frac {e^{i\phi }}{1 +x^2 }}`.
270167
271168IPython code
272- -----------
169+ ------------
273170Interactive IPython sessions can be illustrated in the documentation using
274171the following directive:
275172
@@ -316,6 +213,109 @@ Other
316213 arguments, there are a many cases where a table is used in place of a
317214 definition list for autogenerated sections of docstrings.
318215
216+
217+ Organization of Matplotlib's documentation
218+ ==========================================
219+
220+ The actual reStructured Text files are kept in:file: `doc/users `,
221+ :file: `doc/devel `,:file: `doc/api ` and:file: `doc/faq `. The main entry point is
222+ :file: `doc/index.rst `, which pulls in the:file: `index.rst ` file for the users
223+ guide, developers guide, api reference, and FAQs. The documentation suite is
224+ built as a single document in order to make the most effective use of cross
225+ referencing (we want to make navigating the Matplotlib documentation as easy as
226+ possible).
227+
228+ Additional files can be added to the various guides by including their base
229+ file name (the .rst extension is not necessary) in the table of contents.
230+ It is also possible to include other documents through the use of an include
231+ statement, such as::
232+
233+ .. include:: ../../TODO
234+
235+ docstrings
236+ ----------
237+
238+ In addition to the "narrative" documentation described above,
239+ Matplotlib also defines its API reference documentation in docstrings.
240+ For the most part, these are standard Python docstrings, but
241+ Matplotlib also includes some features to better support documenting
242+ getters and setters.
243+
244+ Matplotlib uses artist introspection of docstrings to support properties.
245+ All properties that you want to support through `~.pyplot.setp ` and
246+ `~.pyplot.getp ` should have a ``set_property `` and ``get_property `` method in
247+ the `~.matplotlib.artist.Artist ` class. Yes, this is not ideal given python
248+ properties or enthought traits, but it is a historical legacy for now. The
249+ setter methods use the docstring with the ACCEPTS token to indicate the type of
250+ argument the method accepts. e.g., in `.Line2D `:
251+
252+ ..code-block ::python
253+
254+ # in lines.py
255+ def set_linestyle (self linestyle ):
256+ """
257+ Set the linestyle of the line
258+
259+ ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
260+ """
261+
262+ kwargs ``, e.g., in every function
263+ that creates a line (`~.pyplot.plot `, `~.pyplot.semilogx `, `~.pyplot.semilogy `,
264+ etc...), it can be difficult for the new user to know which ``kwargs `` are
265+ supported. Matplotlib uses a docstring interpolation scheme to support
266+ documentation of every function that takes a ``**kwargs ``. The requirements
267+ are:
268+
269+ 1. single point of configuration so changes to the properties don't
270+ require multiple docstring edits.
271+
272+ 2. as automated as possible so that as properties change, the docs
273+ are updated automatically.
274+
275+ The function `matplotlib.artist.kwdoc ` and the decorator
276+ `matplotlib.docstring.dedent_interpd ` facilitate this. They combine Python
277+ string interpolation in the docstring with the Matplotlib artist introspection
278+ facility that underlies ``setp `` and ``getp ``. The ``kwdoc `` function gives
279+ the list of properties as a docstring. In order to use this in another
280+ docstring, first update the ``matplotlib.docstring.interpd `` object, as seen in
281+ this example from `matplotlib.lines `:
282+
283+ ..code-block ::python
284+
285+ # in lines.py
286+ docstring.interpd.update(Line2D = artist.kwdoc(Line2D))
287+
288+ ~.Line2D ` pass-through ``kwargs ``, e.g.,
289+ `matplotlib.axes.Axes.plot `:
290+
291+ ..code-block ::python
292+
293+ # in axes.py
294+ @docstring.dedent_interpd
295+ def plot (self * args ,** kwargs ):
296+ """
297+ Some stuff omitted
298+
299+ The kwargs are Line2D properties:
300+ %(Line2D)s
301+
302+ kwargs scalex and scaley, if defined, are passed on
303+ to autoscale_view to determine whether the x and y axes are
304+ autoscaled; default True. See Axes.autoscale_view for more
305+ information
306+ """
307+ pass
308+
309+ ~matplotlib.artist.Artist ` ``__init__ `` methods,
310+ e.g., `matplotlib.patches.Patch.__init__ `, which supports ``Patch `` ``kwargs ``,
311+ since the artist inspector cannot work until the class is fully defined and
312+ we can't modify the ``Patch.__init__.__doc__ `` docstring outside the class
313+ definition. There are some some manual hacks in this case, violating the
314+ "single entry point" requirement above -- see the ``docstring.interpd.update ``
315+ calls in `matplotlib.patches `.
316+
317+ .. _formatting-mpl-docs :
318+
319319Figures
320320=======
321321