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 41d847e

Browse filesBrowse files
dstansbydstansby
committed
Switch section order
1 parent 030ef66 commit 41d847e
Copy full SHA for 41d847e

File tree

Expand file treeCollapse file tree

1 file changed

+104
-104
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+104
-104
lines changed

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+104-104Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.