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

Skip to content

Commit 41d847e

Browse files
dstansbydstansby
committed
Switch section order
1 parent 030ef66 commit 41d847e

File tree

1 file changed

+104
-104
lines changed

1 file changed

+104
-104
lines changed

‎doc/devel/documenting_mpl.rst

Lines changed: 104 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -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-
Since Matplotlib uses a lot of pass-through ``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-
Then in any function accepting `~.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-
Note there is a problem for `~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-
17774
Formatting
17875
==========
17976

@@ -269,7 +166,7 @@ usual way by LaTeX. For example,
269166
yields :math:`\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}`.
270167

271168
IPython code
272-
-----------
169+
------------
273170
Interactive IPython sessions can be illustrated in the documentation using
274171
the 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+
Since Matplotlib uses a lot of pass-through ``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+
Then in any function accepting `~.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+
Note there is a problem for `~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+
319319
Figures
320320
=======
321321

0 commit comments

Comments
 (0)