-
Notifications
You must be signed in to change notification settings - Fork 59
Expand file tree
/
Copy pathdocumenting_mpl.html
More file actions
875 lines (812 loc) · 70.9 KB
/
documenting_mpl.html
File metadata and controls
875 lines (812 loc) · 70.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Writing documentation — Matplotlib 2.2.3 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css"
type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css"
type="text/css" />
<link rel="stylesheet" href="../_static/gallery.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.2.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 2.2.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html"
/>
<link rel="search" title="Search" href="../search.html"
/>
<link rel="top" title="Matplotlib 2.2.3 documentation" href="../index.html" />
<link rel="up" title="The Matplotlib Developers' Guide" href="index.html" />
<link rel="next" title="Plot directive documentation" href="plot_directive.html" />
<link rel="prev" title="Developer's tips for testing" href="testing.html" />
<link rel="canonical" href="https://matplotlib.org/stable/devel/documenting_mpl.html" />
<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>
</head>
<body>
<div id="unreleased-message"> You are reading an old version of the documentation (v2.2.3). For the latest version see <a href="https://matplotlib.org/stable/devel/documenting_mpl.html">https://matplotlib.org/stable/devel/documenting_mpl.html</a></div>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px; position: relative;">
<a href="../index.html">
<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 2.2.3</span></div>
<img src="../_static/logo2.png" height="125px" border="0" alt="matplotlib"/></a>
<!-- The "Fork me on github" ribbon -->
<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="plot_directive.html" title="Plot directive documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="testing.html" title="Developer's tips for testing"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a>| </li>
<li><a href="../gallery/index.html">examples</a>| </li>
<li><a href="../tutorials/index.html">tutorials</a>| </li>
<li><a href="../api/pyplot_summary.html">pyplot</a>| </li>
<li><a href="../contents.html">docs</a> »</li>
<li><a href="index.html" accesskey="U">The Matplotlib Developers' Guide</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Writing documentation</a><ul>
<li><a class="reference internal" href="#getting-started">Getting started</a><ul>
<li><a class="reference internal" href="#general-file-structure">General file structure</a></li>
<li><a class="reference internal" href="#installing-dependencies">Installing dependencies</a></li>
<li><a class="reference internal" href="#building-the-docs">Building the docs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-rest-pages">Writing ReST pages</a><ul>
<li><a class="reference internal" href="#formatting-and-style-conventions">Formatting and style conventions</a><ul>
<li><a class="reference internal" href="#section-name-formatting">Section name formatting</a></li>
<li><a class="reference internal" href="#function-arguments">Function arguments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#referring-to-other-documents-and-sections">Referring to other documents and sections</a></li>
<li><a class="reference internal" href="#referring-to-other-code">Referring to other code</a></li>
<li><a class="reference internal" href="#including-figures-and-files">Including figures and files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-docstrings">Writing docstrings</a><ul>
<li><a class="reference internal" href="#example-docstring">Example docstring</a></li>
<li><a class="reference internal" href="#formatting-conventions">Formatting conventions</a></li>
<li><a class="reference internal" href="#deprecated-formatting-conventions">Deprecated formatting conventions</a></li>
<li><a class="reference internal" href="#linking-to-other-code">Linking to other code</a></li>
<li><a class="reference internal" href="#id3">Function arguments</a></li>
<li><a class="reference internal" href="#setters-and-getters">Setters and getters</a></li>
<li><a class="reference internal" href="#keyword-arguments">Keyword arguments</a></li>
<li><a class="reference internal" href="#adding-figures">Adding figures</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-examples-and-tutorials">Writing examples and tutorials</a></li>
<li><a class="reference internal" href="#miscellaneous">Miscellaneous</a><ul>
<li><a class="reference internal" href="#adding-animations">Adding animations</a></li>
<li><a class="reference internal" href="#generating-inheritance-diagrams">Generating inheritance diagrams</a></li>
<li><a class="reference internal" href="#emacs-helpers">Emacs helpers</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../contents.html">Documentation overview</a><ul>
<li><a href="index.html">The Matplotlib Developers' Guide</a><ul>
<li>Previous: <a href="testing.html" title="previous chapter">Developer's tips for testing</a></li>
<li>Next: <a href="plot_directive.html" title="next chapter">Plot directive documentation</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="sidebar-pagesource" role="note" aria-label="source link"
style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">
<a href="../_sources/devel/documenting_mpl.rst.txt"
style="color: #c0c0c0" rel="nofollow">Show Page Source</a>
</div>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="writing-documentation">
<span id="documenting-matplotlib"></span><h1>Writing documentation<a class="headerlink" href="#writing-documentation" title="Permalink to this headline">¶</a></h1>
<div class="section" id="getting-started">
<h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<div class="section" id="general-file-structure">
<h3>General file structure<a class="headerlink" href="#general-file-structure" title="Permalink to this headline">¶</a></h3>
<p>All documentation is built from the <code class="file docutils literal notranslate"><span class="pre">doc/</span></code> directory. This directory
contains both reStructuredText (<a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>; <code class="docutils literal notranslate"><span class="pre">.rst</span></code>) files that contain pages in
the documentation and configuration files for <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files are kept in <code class="file docutils literal notranslate"><span class="pre">doc/users</span></code>,
<code class="file docutils literal notranslate"><span class="pre">doc/devel</span></code>, <code class="file docutils literal notranslate"><span class="pre">doc/api</span></code> and <code class="file docutils literal notranslate"><span class="pre">doc/faq</span></code>. The main entry point is
<code class="file docutils literal notranslate"><span class="pre">doc/index.rst</span></code>, which pulls in the <code class="file docutils literal notranslate"><span class="pre">index.rst</span></code> file for the users
guide, developers guide, api reference, and FAQs. The documentation suite is
built as a single document in order to make the most effective use of cross
referencing.</p>
<p><a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> also creates <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files that are staged in <code class="file docutils literal notranslate"><span class="pre">doc/api</span></code> from
the docstrings of the classes in the Matplotlib library. Except for
<code class="file docutils literal notranslate"><span class="pre">doc/api/api_changes/</span></code>, these <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files are created when the
documentation is built.</p>
<p>Similarly, the contents of <code class="file docutils literal notranslate"><span class="pre">docs/gallery</span></code> and <code class="file docutils literal notranslate"><span class="pre">docs/tutorials</span></code> are
generated by the <a class="reference external" href="https://sphinx-gallery.readthedocs.io/en/latest/">Sphinx Gallery</a> from the sources in <code class="file docutils literal notranslate"><span class="pre">examples</span></code> and
<code class="file docutils literal notranslate"><span class="pre">tutorials</span></code>. These sources consist of python scripts that have <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>
documentation built into their comments. Don't directly edit the
<code class="docutils literal notranslate"><span class="pre">.rst</span></code> files in <code class="file docutils literal notranslate"><span class="pre">docs/gallery</span></code> and <code class="file docutils literal notranslate"><span class="pre">docs/tutorials</span></code> as they are
regenerated when the documentation are built.</p>
</div>
<div class="section" id="installing-dependencies">
<h3>Installing dependencies<a class="headerlink" href="#installing-dependencies" title="Permalink to this headline">¶</a></h3>
<p>The documentation for Matplotlib is generated from reStructuredText (<a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>)
using the <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> documentation generation tool. There are several extra
requirements that are needed to build the documentation. They are listed in
<code class="file docutils literal notranslate"><span class="pre">doc-requirements.txt</span></code> and listed below:</p>
<ul class="simple">
<li>Sphinx>=1.3, !=1.5.0, !=1.6.4</li>
<li>colorspacious</li>
<li>IPython</li>
<li>mock</li>
<li>numpydoc>=0.4</li>
<li>Pillow</li>
<li>sphinx-gallery>=0.1.12</li>
<li>graphviz</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<ul class="last simple">
<li>You'll need a minimal working LaTeX distribution for many examples to run.</li>
<li><a class="reference external" href="http://www.graphviz.org/Download.php">Graphviz</a> is not a Python package,
and needs to be installed separately.</li>
</ul>
</div>
</div>
<div class="section" id="building-the-docs">
<h3>Building the docs<a class="headerlink" href="#building-the-docs" title="Permalink to this headline">¶</a></h3>
<p>The documentation sources are found in the <code class="file docutils literal notranslate"><span class="pre">doc/</span></code> directory in the trunk.
The configuration file for Sphinx is <code class="file docutils literal notranslate"><span class="pre">doc/conf.py</span></code>. It controls which
directories Sphinx parses, how the docs are built, and how the extensions are
used. To build the documentation in html format, cd into <code class="file docutils literal notranslate"><span class="pre">doc/</span></code> and run:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>make html
</pre></div>
</div>
<p>Other useful invocations include</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Delete built files. May help if you get errors about missing paths or</span>
<span class="c1"># broken links.</span>
make clean
<span class="c1"># Build pdf docs.</span>
make latexpdf
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">SPHINXOPTS</span></code> variable is set to <code class="docutils literal notranslate"><span class="pre">-W</span></code> by default to turn warnings into
errors. To unset it, use</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>make <span class="nv">SPHINXOPTS</span><span class="o">=</span> html
</pre></div>
</div>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">O</span></code> variable to set additional options:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">O=-j4</span> <span class="pre">html</span></code> runs a parallel build with 4 processes.</li>
<li><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">O=-Dplot_formats=png:100</span> <span class="pre">html</span></code> saves figures in low resolution.</li>
<li><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">O=-Dplot_gallery=0</span> <span class="pre">html</span></code> skips the gallery build.</li>
</ul>
<p>Multiple options can be combined using e.g. <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">O='-j4</span> <span class="pre">-Dplot_gallery=0'</span>
<span class="pre">html</span></code>.</p>
<p>On Windows, options needs to be set as environment variables, e.g. <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">O=-W</span>
<span class="pre">-j4</span> <span class="pre">&</span> <span class="pre">make</span> <span class="pre">html</span></code>.</p>
</div>
</div>
<div class="section" id="writing-rest-pages">
<span id="id1"></span><h2>Writing ReST pages<a class="headerlink" href="#writing-rest-pages" title="Permalink to this headline">¶</a></h2>
<p>Most documentation is either in the docstring of individual
classes and methods, in explicit <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files, or in examples and tutorials.
All of these use the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> syntax. Users should look at the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> documentation
for a full description. But some specific hints and conventions Matplotlib
uses are useful for creating documentation.</p>
<div class="section" id="formatting-and-style-conventions">
<h3>Formatting and style conventions<a class="headerlink" href="#formatting-and-style-conventions" title="Permalink to this headline">¶</a></h3>
<p>It is useful to strive for consistency in the Matplotlib documentation. Here
are some formatting and style conventions that are used.</p>
<div class="section" id="section-name-formatting">
<h4>Section name formatting<a class="headerlink" href="#section-name-formatting" title="Permalink to this headline">¶</a></h4>
<p>For everything but top-level chapters, use <code class="docutils literal notranslate"><span class="pre">Upper</span> <span class="pre">lower</span></code> for
section titles, e.g., <code class="docutils literal notranslate"><span class="pre">Possible</span> <span class="pre">hangups</span></code> rather than <code class="docutils literal notranslate"><span class="pre">Possible</span>
<span class="pre">Hangups</span></code></p>
</div>
<div class="section" id="function-arguments">
<h4>Function arguments<a class="headerlink" href="#function-arguments" title="Permalink to this headline">¶</a></h4>
<p>Function arguments and keywords within docstrings should be referred to using
the <code class="docutils literal notranslate"><span class="pre">*emphasis*</span></code> role. This will keep Matplotlib's documentation consistent
with Python's documentation:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Here is a description of <span class="ge">*argument*</span>
</pre></div>
</div>
<p>Do not use the <code class="docutils literal notranslate"><span class="pre">`default</span> <span class="pre">role`</span></code>:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Do not describe <span class="nv">`argument`</span> like this. As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.
</pre></div>
</div>
<p>nor the <code class="docutils literal notranslate"><span class="pre">``literal``</span></code> role:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Do not describe <span class="s">``argument``</span> like this.
</pre></div>
</div>
</div>
</div>
<div class="section" id="referring-to-other-documents-and-sections">
<span id="internal-section-refs"></span><h3>Referring to other documents and sections<a class="headerlink" href="#referring-to-other-documents-and-sections" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> allows internal <a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/inline.html">references</a> between documents.</p>
<p>Documents can be linked with the <code class="xref py py-obj docutils literal notranslate"><span class="pre">:doc:</span></code> directive:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>See the <span class="na">:doc:</span><span class="nv">`/faq/installing_faq`</span>
See the tutorial <span class="na">:doc:</span><span class="nv">`/tutorials/introductory/sample_plots`</span>
See the example <span class="na">:doc:</span><span class="nv">`/gallery/lines_bars_and_markers/simple_plot`</span>
</pre></div>
</div>
<p>will render as:</p>
<blockquote>
<div><p>See the <a class="reference internal" href="../faq/installing_faq.html"><span class="doc">Installation</span></a></p>
<p>See the tutorial <a class="reference internal" href="../tutorials/introductory/sample_plots.html"><span class="doc">Sample plots in Matplotlib</span></a></p>
<p>See the example <a class="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><span class="doc">Simple Plot</span></a></p>
</div></blockquote>
<p>Sections can also be given reference names. For instance from the
<a class="reference internal" href="../faq/installing_faq.html"><span class="doc">Installation</span></a> link:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_clean-install:</span>
<span class="gh">How to completely remove Matplotlib</span>
<span class="gh">===================================</span>
Occasionally, problems with Matplotlib can be solved with a clean...
</pre></div>
</div>
<p>and refer to it using the standard reference syntax:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>See <span class="na">:ref:</span><span class="nv">`clean-install`</span>
</pre></div>
</div>
<p>will give the following link: <a class="reference internal" href="../faq/installing_faq.html#clean-install"><span class="std std-ref">How to completely remove Matplotlib</span></a></p>
<p>To maximize internal consistency in section labeling and references,
use hyphen separated, descriptive labels for section references.
Keep in mind that contents may be reorganized later, so
avoid top level names in references like <code class="docutils literal notranslate"><span class="pre">user</span></code> or <code class="docutils literal notranslate"><span class="pre">devel</span></code>
or <code class="docutils literal notranslate"><span class="pre">faq</span></code> unless necessary, because for example the FAQ "what is a
backend?" could later become part of the users guide, so the label:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_what-is-a-backend:</span>
</pre></div>
</div>
<p>is better than:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_faq-backend:</span>
</pre></div>
</div>
<p>In addition, since underscores are widely used by Sphinx itself, use
hyphens to separate words.</p>
</div>
<div class="section" id="referring-to-other-code">
<h3>Referring to other code<a class="headerlink" href="#referring-to-other-code" title="Permalink to this headline">¶</a></h3>
<p>To link to other methods, classes, or modules in Matplotlib you can use
back ticks, for example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sb">`~matplotlib.collections.LineCollection`</span>
</pre></div>
</div>
<p>returns a link to the documentation of
<a class="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><code class="xref py py-obj docutils literal notranslate"><span class="pre">LineCollection</span></code></a>. For the full path of the
class to be shown, omit the tilde:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sb">`matplotlib.collections.LineCollection`</span>
</pre></div>
</div>
<p>to get <a class="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.collections.LineCollection</span></code></a>. It is often not
necessary to fully specify the class hierarchy unless there is a namespace
collision between two packages:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sb">`~.LineCollection`</span>
</pre></div>
</div>
<p>links just as well: <a class="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><code class="xref py py-obj docutils literal notranslate"><span class="pre">LineCollection</span></code></a>.</p>
<p>Other packages can also be linked via <code class="docutils literal notranslate"><span class="pre">intersphinx</span></code>:</p>
<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="sb">`numpy.mean`</span>
</pre></div>
</div>
<p>will return this link: <a class="reference external" href="https://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html#numpy.mean" title="(in NumPy v1.15)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">numpy.mean</span></code></a>. This works for Python, Numpy, Scipy,
and Pandas (full list is in <code class="file docutils literal notranslate"><span class="pre">doc/conf.py</span></code>). Sometimes it is tricky
to get external Sphinx linking to work; to
check that a something exists to link to the following shell command outputs
a list of all objects that can be referenced (in this case for Numpy):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">sphinx</span><span class="o">.</span><span class="n">ext</span><span class="o">.</span><span class="n">intersphinx</span> <span class="s1">'https://docs.scipy.org/doc/numpy/objects.inv'</span>
</pre></div>
</div>
</div>
<div class="section" id="including-figures-and-files">
<span id="rst-figures-and-includes"></span><h3>Including figures and files<a class="headerlink" href="#including-figures-and-files" title="Permalink to this headline">¶</a></h3>
<p>Image files can directly included in pages with the <code class="docutils literal notranslate"><span class="pre">image::</span></code> directive.
e.g., <code class="file docutils literal notranslate"><span class="pre">users/navigation_toolbar.rst</span></code> displays the toolbar icons
with a call to a static image:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">image</span><span class="p">::</span> <span class="o">../</span><span class="n">_static</span><span class="o">/</span><span class="n">toolbar</span><span class="o">.</span><span class="n">png</span>
</pre></div>
</div>
<p>as rendered on the page: <a class="reference internal" href="../users/navigation_toolbar.html#navigation-toolbar"><span class="std std-ref">Interactive navigation</span></a>.</p>
<p>Files can be included verbatim. For instance the <code class="docutils literal notranslate"><span class="pre">matplotlibrc</span></code> file
is important for customizing Matplotlib, and is included verbatim in the
tutorial in <a class="reference internal" href="../tutorials/introductory/customizing.html"><span class="doc">Customizing Matplotlib with style sheets and rcParams</span></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">literalinclude</span><span class="p">::</span> <span class="o">../../</span><span class="n">_static</span><span class="o">/</span><span class="n">matplotlibrc</span>
</pre></div>
</div>
<p>This is rendered at the bottom of <a class="reference internal" href="../tutorials/introductory/customizing.html"><span class="doc">Customizing Matplotlib with style sheets and rcParams</span></a>.
Note that this is in a tutorial; see <a class="reference internal" href="#writing-examples-and-tutorials"><span class="std std-ref">Writing examples and tutorials</span></a>
below.</p>
<p>The examples directory is also copied to <code class="file docutils literal notranslate"><span class="pre">doc/gallery</span></code> by sphinx-gallery,
so plots from the examples directory can be included using</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">plot</span><span class="p">::</span> gallery/pylab_examples/simple_plot.py
</pre></div>
</div>
<p>Note that the python script that generates the plot is referred to, rather than
any plot that is created. Sphinx-gallery will provide the correct reference
when the documentation is built.</p>
</div>
</div>
<div class="section" id="writing-docstrings">
<span id="id2"></span><h2>Writing docstrings<a class="headerlink" href="#writing-docstrings" title="Permalink to this headline">¶</a></h2>
<p>Much of the documentation lives in "docstrings". These are comment blocks
in source code that explain how the code works. All new or edited docstrings
should conform to the numpydoc guidelines. These split the docstring into a
number of sections - see the <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpy documentation howto</a>
for more details and a guide to how docstrings should be formatted. Much of
the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> syntax discussed above (:ref:writing-rest-pages) can be used for
links and references. These docstrings eventually populate the
<code class="file docutils literal notranslate"><span class="pre">doc/api</span></code> directory and form the reference documentation for the
library.</p>
<div class="section" id="example-docstring">
<h3>Example docstring<a class="headerlink" href="#example-docstring" title="Permalink to this headline">¶</a></h3>
<p>An example docstring looks like:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">hlines</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">xmin</span><span class="p">,</span> <span class="n">xmax</span><span class="p">,</span> <span class="n">colors</span><span class="o">=</span><span class="s1">'k'</span><span class="p">,</span> <span class="n">linestyles</span><span class="o">=</span><span class="s1">'solid'</span><span class="p">,</span>
<span class="n">label</span><span class="o">=</span><span class="s1">''</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Plot horizontal lines at each *y* from *xmin* to *xmax*.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> y : scalar or sequence of scalar</span>
<span class="sd"> y-indexes where to plot the lines.</span>
<span class="sd"> xmin, xmax : scalar or 1D array_like</span>
<span class="sd"> Respective beginning and end of each line. If scalars are</span>
<span class="sd"> provided, all lines will have same length.</span>
<span class="sd"> colors : array_like of colors, optional, default: 'k'</span>
<span class="sd"> linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional</span>
<span class="sd"> label : string, optional, default: ''</span>
<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> lines : `~matplotlib.collections.LineCollection`</span>
<span class="sd"> Other Parameters</span>
<span class="sd"> ----------------</span>
<span class="sd"> **kwargs : `~matplotlib.collections.LineCollection` properties.</span>
<span class="sd"> See also</span>
<span class="sd"> --------</span>
<span class="sd"> vlines : vertical lines</span>
<span class="sd"> axhline: horizontal line across the axes</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>See the <a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.hlines.html#matplotlib.axes.Axes.hlines" title="matplotlib.axes.Axes.hlines"><code class="xref py py-obj docutils literal notranslate"><span class="pre">hlines</span></code></a> documentation for how this renders.</p>
<p>The <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> website also contains plenty of <a class="reference external" href="http://www.sphinx-doc.org/contents.html">documentation</a> concerning ReST
markup and working with Sphinx in general.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Some parts of the documentation do not yet conform to the current
documentation style. If in doubt, follow the rules given here and not what
you may see in the source code. Pull requests updating docstrings to
the current style are very welcome.</p>
</div>
</div>
<div class="section" id="formatting-conventions">
<h3>Formatting conventions<a class="headerlink" href="#formatting-conventions" title="Permalink to this headline">¶</a></h3>
<p>The basic docstring conventions are covered in the <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpy documentation howto</a>
and the <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> documentation. Some Matplotlib-specific formatting conventions
to keep in mind:</p>
<ul>
<li><p class="first">Matplotlib does not have a convention whether to use single-quotes or
double-quotes. There is a mixture of both in the current code.</p>
</li>
<li><p class="first">Long parameter lists should be wrapped using a <code class="docutils literal notranslate"><span class="pre">\</span></code> for continuation and
starting on the new line without any indent:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">add_axes</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> ...</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> projection :</span>
<span class="sd"> {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \</span>
<span class="sd">'rectilinear'}, optional</span>
<span class="sd"> The projection type of the axes.</span>
<span class="sd"> ...</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Alternatively, you can describe the valid parameter values in a dedicated
section of the docstring.</p>
</li>
<li><p class="first">Generally, do not add markup to types for <code class="docutils literal notranslate"><span class="pre">Parameters</span></code> and <code class="docutils literal notranslate"><span class="pre">Returns</span></code>.
This is usually not needed because Sphinx will link them automatically and
would unnecessarily clutter the docstring. However, it does seem to fail in
some situations. If you encounter such a case, you are allowed to add markup:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">Returns</span>
<span class="gh">-------</span>
lines : <span class="nv">`~matplotlib.collections.LineCollection`</span>
</pre></div>
</div>
</li>
<li><p class="first">rcParams can be referenced with the custom <code class="docutils literal notranslate"><span class="pre">:rc:</span></code> role:
<code class="docutils literal notranslate"><span class="pre">:rc:`foo`</span></code> yields <code class="docutils literal notranslate"><span class="pre">rcParams["foo"]</span></code>.</p>
</li>
</ul>
</div>
<div class="section" id="deprecated-formatting-conventions">
<h3>Deprecated formatting conventions<a class="headerlink" href="#deprecated-formatting-conventions" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Formerly, we have used square brackets for explicit parameter lists
<code class="docutils literal notranslate"><span class="pre">['solid'</span> <span class="pre">|</span> <span class="pre">'dashed'</span> <span class="pre">|</span> <span class="pre">'dotted']</span></code>. With numpydoc we have switched to their
standard using curly braces <code class="docutils literal notranslate"><span class="pre">{'solid',</span> <span class="pre">'dashed',</span> <span class="pre">'dotted'}</span></code>.</li>
</ul>
</div>
<div class="section" id="linking-to-other-code">
<h3>Linking to other code<a class="headerlink" href="#linking-to-other-code" title="Permalink to this headline">¶</a></h3>
<p>To link to other methods, classes, or modules in Matplotlib you can encase
the name to refer to in back ticks, for example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sb">`~matplotlib.collections.LineCollection`</span>
</pre></div>
</div>
<p>It is also possible to add links to code in Python, Numpy, Scipy, or Pandas.
Sometimes it is tricky to get external Sphinx linking to work; to check that
a something exists to link to the following shell command outputs a list of all
objects that can be referenced (in this case for Numpy):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">sphinx</span><span class="o">.</span><span class="n">ext</span><span class="o">.</span><span class="n">intersphinx</span> <span class="s1">'https://docs.scipy.org/doc/numpy/objects.inv'</span>
</pre></div>
</div>
</div>
<div class="section" id="id3">
<h3>Function arguments<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
<p>Function arguments and keywords within docstrings should be referred to using
the <code class="docutils literal notranslate"><span class="pre">*emphasis*</span></code> role. This will keep Matplotlib's documentation consistent
with Python's documentation:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Here is a description of <span class="ge">*argument*</span>
</pre></div>
</div>
<p>Do not use the <code class="docutils literal notranslate"><span class="pre">`default</span> <span class="pre">role`</span></code>:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Do not describe <span class="nv">`argument`</span> like this.
</pre></div>
</div>
<p>nor the <code class="docutils literal notranslate"><span class="pre">``literal``</span></code> role:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Do not describe <span class="s">``argument``</span> like this.
</pre></div>
</div>
</div>
<div class="section" id="setters-and-getters">
<h3>Setters and getters<a class="headerlink" href="#setters-and-getters" title="Permalink to this headline">¶</a></h3>
<p>Artist properties are implemented using setter and getter methods (because
Matplotlib predates the introductions of the <a class="reference external" href="https://docs.python.org/3/library/functions.html#property" title="(in Python v3.7)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">property</span></code></a> decorator in Python).
By convention, these setters and getters are named <code class="docutils literal notranslate"><span class="pre">set_PROPERTYNAME</span></code> and
<code class="docutils literal notranslate"><span class="pre">get_PROPERTYNAME</span></code>; the list of properties thusly defined on an artist and
their values can be listed by the <a class="reference internal" href="../api/_as_gen/matplotlib.pyplot.setp.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><code class="xref py py-obj docutils literal notranslate"><span class="pre">setp</span></code></a> and <code class="xref py py-obj docutils literal notranslate"><span class="pre">getp</span></code> functions.</p>
<p>Property setter methods should indicate the values they accept using a (legacy)
special block in the docstring, starting with <code class="docutils literal notranslate"><span class="pre">ACCEPTS</span></code>, as follows:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in lines.py</span>
<span class="k">def</span> <span class="nf">set_linestyle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">linestyle</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Set the linestyle of the line</span>
<span class="sd"> ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>The ACCEPTS block is used to render a table of all properties and their
acceptable values in the docs; it can also be displayed using, e.g.,
<code class="docutils literal notranslate"><span class="pre">plt.setp(Line2D)</span></code> (all properties) or <code class="docutils literal notranslate"><span class="pre">plt.setp(Line2D,</span> <span class="pre">'linestyle')</span></code>
(just one property).</p>
<p>There are cases in which the ACCEPTS string is not useful in the
generated Sphinx documentation, e.g. if the valid parameters are already
defined in the numpydoc parameter list. You can hide the ACCEPTS string from
Sphinx by making it a ReST comment (i.e. use <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">ACCEPTS:</span></code>):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">set_linestyle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">linestyle</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> An ACCEPTS string invisible to Sphinx.</span>
<span class="sd"> .. ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]</span>
<span class="sd"> """</span>
</pre></div>
</div>
</div>
<div class="section" id="keyword-arguments">
<h3>Keyword arguments<a class="headerlink" href="#keyword-arguments" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The information in this section is being actively discussed by the
development team, so use the docstring interpolation only if necessary.
This section has been left in place for now because this interpolation
is part of the existing documentation.</p>
</div>
<p>Since Matplotlib uses a lot of pass-through <code class="docutils literal notranslate"><span class="pre">kwargs</span></code>, e.g., in every function
that creates a line (<a class="reference internal" href="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><code class="xref py py-obj docutils literal notranslate"><span class="pre">plot</span></code></a>, <a class="reference internal" href="../api/_as_gen/matplotlib.pyplot.semilogx.html#matplotlib.pyplot.semilogx" title="matplotlib.pyplot.semilogx"><code class="xref py py-obj docutils literal notranslate"><span class="pre">semilogx</span></code></a>, <a class="reference internal" href="../api/_as_gen/matplotlib.pyplot.semilogy.html#matplotlib.pyplot.semilogy" title="matplotlib.pyplot.semilogy"><code class="xref py py-obj docutils literal notranslate"><span class="pre">semilogy</span></code></a>,
etc...), it can be difficult for the new user to know which <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> are
supported. Matplotlib uses a docstring interpolation scheme to support
documentation of every function that takes a <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code>. The requirements
are:</p>
<ol class="arabic simple">
<li>single point of configuration so changes to the properties don't
require multiple docstring edits.</li>
<li>as automated as possible so that as properties change, the docs
are updated automatically.</li>
</ol>
<p>The function <a class="reference internal" href="../api/_as_gen/matplotlib.artist.kwdoc.html#matplotlib.artist.kwdoc" title="matplotlib.artist.kwdoc"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.artist.kwdoc</span></code></a> and the decorator
<code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.docstring.dedent_interpd</span></code> facilitate this. They combine Python
string interpolation in the docstring with the Matplotlib artist introspection
facility that underlies <code class="docutils literal notranslate"><span class="pre">setp</span></code> and <code class="docutils literal notranslate"><span class="pre">getp</span></code>. The <code class="docutils literal notranslate"><span class="pre">kwdoc</span></code> function gives
the list of properties as a docstring. In order to use this in another
docstring, first update the <code class="docutils literal notranslate"><span class="pre">matplotlib.docstring.interpd</span></code> object, as seen in
this example from <a class="reference internal" href="../api/lines_api.html#module-matplotlib.lines" title="matplotlib.lines"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.lines</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in lines.py</span>
<span class="n">docstring</span><span class="o">.</span><span class="n">interpd</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">Line2D</span><span class="o">=</span><span class="n">artist</span><span class="o">.</span><span class="n">kwdoc</span><span class="p">(</span><span class="n">Line2D</span><span class="p">))</span>
</pre></div>
</div>
<p>Then in any function accepting <a class="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Line2D</span></code></a> pass-through <code class="docutils literal notranslate"><span class="pre">kwargs</span></code>, e.g.,
<a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.axes.Axes.plot</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in axes.py</span>
<span class="nd">@docstring.dedent_interpd</span>
<span class="k">def</span> <span class="nf">plot</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Some stuff omitted</span>
<span class="sd"> The kwargs are Line2D properties:</span>
<span class="sd"> %(Line2D)s</span>
<span class="sd"> kwargs scalex and scaley, if defined, are passed on</span>
<span class="sd"> to autoscale_view to determine whether the x and y axes are</span>
<span class="sd"> autoscaled; default True. See Axes.autoscale_view for more</span>
<span class="sd"> information</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Note there is a problem for <a class="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Artist</span></code></a> <code class="docutils literal notranslate"><span class="pre">__init__</span></code> methods,
e.g., <code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.patches.Patch.__init__</span></code>, which supports <code class="docutils literal notranslate"><span class="pre">Patch</span></code> <code class="docutils literal notranslate"><span class="pre">kwargs</span></code>,
since the artist inspector cannot work until the class is fully defined and
we can't modify the <code class="docutils literal notranslate"><span class="pre">Patch.__init__.__doc__</span></code> docstring outside the class
definition. There are some some manual hacks in this case, violating the
"single entry point" requirement above -- see the <code class="docutils literal notranslate"><span class="pre">docstring.interpd.update</span></code>
calls in <a class="reference internal" href="../api/patches_api.html#module-matplotlib.patches" title="matplotlib.patches"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.patches</span></code></a>.</p>
</div>
<div class="section" id="adding-figures">
<span id="docstring-adding-figures"></span><h3>Adding figures<a class="headerlink" href="#adding-figures" title="Permalink to this headline">¶</a></h3>
<p>As above (see <a class="reference internal" href="#rst-figures-and-includes"><span class="std std-ref">Including figures and files</span></a>), figures in the examples gallery
can be referenced with a <code class="xref py py-obj docutils literal notranslate"><span class="pre">:plot:</span></code> directive pointing to the python script that
created the figure. For instance the <a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.legend.html#matplotlib.axes.Axes.legend" title="matplotlib.axes.Axes.legend"><code class="xref py py-obj docutils literal notranslate"><span class="pre">legend</span></code></a> docstring references
the file <code class="file docutils literal notranslate"><span class="pre">examples/api/legend.py</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
<span class="sd"> ...</span>
<span class="sd">Examples</span>
<span class="sd">--------</span>
<span class="sd">.. plot:: gallery/api/legend.py</span>
<span class="sd">"""</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">examples/api/legend.py</span></code> has been mapped to
<code class="docutils literal notranslate"><span class="pre">gallery/api/legend.py</span></code>, a redirection that may be fixed in future
re-organization of the docs.</p>
<p>Plots can also be directly placed inside docstrings. Details are in
<a class="reference internal" href="plot_directive.html"><span class="doc">Plot directive documentation</span></a>. A short example is:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
<span class="sd"> ...</span>
<span class="sd">Examples</span>
<span class="sd">--------</span>
<span class="sd">.. plot::</span>
<span class="sd"> import matplotlib.image as mpimg</span>
<span class="sd"> img = mpimg.imread('_static/stinkbug.png')</span>
<span class="sd"> imgplot = plt.imshow(img)</span>
<span class="sd">"""</span>
</pre></div>
</div>
<p>An advantage of this style over referencing an example script is that the
code will also appear in interactive docstrings.</p>
</div>
</div>
<div class="section" id="writing-examples-and-tutorials">
<span id="id4"></span><h2>Writing examples and tutorials<a class="headerlink" href="#writing-examples-and-tutorials" title="Permalink to this headline">¶</a></h2>
<p>Examples and tutorials are python scripts that are run by <a class="reference external" href="https://sphinx-gallery.readthedocs.io/en/latest/">Sphinx Gallery</a>
to create a gallery of images in the <code class="file docutils literal notranslate"><span class="pre">/doc/gallery</span></code> and
<code class="file docutils literal notranslate"><span class="pre">/doc/tutorials</span></code> directories respectively. To exclude an example
from having an plot generated insert "sgskip" somewhere in the filename.</p>
<p>The format of these files is relatively straightforward. Properly
formatted comment blocks are treated as <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> text, the code is
displayed, and figures are put into the built page.</p>
<p>For instance the example <a class="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><span class="doc">Simple Plot</span></a>
example is generated from
<code class="file docutils literal notranslate"><span class="pre">/examples/lines_bars_and_markers/simple_plot.py</span></code>, which looks like:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
<span class="sd">===========</span>
<span class="sd">Simple Plot</span>
<span class="sd">===========</span>
<span class="sd">Create a simple plot.</span>
<span class="sd">"""</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="c1"># Data for plotting</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mf">0.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">,</span> <span class="mf">0.01</span><span class="p">)</span>
<span class="n">s</span> <span class="o">=</span> <span class="mi">1</span> <span class="o">+</span> <span class="n">np</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="mi">2</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">pi</span> <span class="o">*</span> <span class="n">t</span><span class="p">)</span>
<span class="c1"># Note that using plt.subplots below is equivalent to using</span>
<span class="c1"># fig = plt.figure and then ax = fig.add_subplot(111)</span>
<span class="n">fig</span><span class="p">,</span> <span class="n">ax</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplots</span><span class="p">()</span>
<span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">xlabel</span><span class="o">=</span><span class="s1">'time (s)'</span><span class="p">,</span> <span class="n">ylabel</span><span class="o">=</span><span class="s1">'voltage (mV)'</span><span class="p">,</span>
<span class="n">title</span><span class="o">=</span><span class="s1">'About as simple as it gets, folks'</span><span class="p">)</span>
<span class="n">ax</span><span class="o">.</span><span class="n">grid</span><span class="p">()</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>The first comment block is treated as <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> text. The other comment blocks
render as comments in <a class="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><span class="doc">Simple Plot</span></a>.</p>
<p>Tutorials are made with the exact same mechanism, except they are longer, and
typically have more than one comment block (i.e.
<a class="reference internal" href="../tutorials/introductory/usage.html"><span class="doc">Usage Guide</span></a>). The first comment block
can be the same as the example above. Subsequent blocks of ReST text
are delimited by a line of <code class="xref py py-obj docutils literal notranslate"><span class="pre">###</span></code> characters:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
<span class="sd">===========</span>
<span class="sd">Simple Plot</span>
<span class="sd">===========</span>
<span class="sd">Create a simple plot.</span>
<span class="sd">"""</span>
<span class="o">...</span>
<span class="n">ax</span><span class="o">.</span><span class="n">grid</span><span class="p">()</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
<span class="c1">##########################################################################</span>
<span class="c1"># Second plot</span>
<span class="c1"># ===========</span>
<span class="c1">#</span>
<span class="c1"># This is a second plot that is very nice</span>
<span class="n">fig</span><span class="p">,</span> <span class="n">ax</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplots</span><span class="p">()</span>
<span class="n">ax</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">50</span><span class="p">)))</span>
</pre></div>
</div>
<p>In this way text, code, and figures are output in a "notebook" style.</p>
</div>
<div class="section" id="miscellaneous">
<h2>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
<div class="section" id="adding-animations">
<h3>Adding animations<a class="headerlink" href="#adding-animations" title="Permalink to this headline">¶</a></h3>
<p>There is a Matplotlib Google/Gmail account with username <code class="docutils literal notranslate"><span class="pre">mplgithub</span></code>
which was used to setup the github account but can be used for other
purposes, like hosting Google docs or Youtube videos. You can embed a
Matplotlib animation in the docs by first saving the animation as a
movie using <a class="reference internal" href="../api/_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation.save" title="matplotlib.animation.Animation.save"><code class="xref py py-meth docutils literal notranslate"><span class="pre">matplotlib.animation.Animation.save()</span></code></a>, and then
uploading to <a class="reference external" href="https://www.youtube.com/user/matplotlib">matplotlib's Youtube
channel</a> and inserting the
embedding string youtube provides like:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">raw</span><span class="p">::</span> html
<iframe width="420" height="315"
src="http://www.youtube.com/embed/32cjc6V0OZY"
frameborder="0" allowfullscreen>
</iframe>
</pre></div>
</div>
<p>An example save command to generate a movie looks like this</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">ani</span> <span class="o">=</span> <span class="n">animation</span><span class="o">.</span><span class="n">FuncAnimation</span><span class="p">(</span><span class="n">fig</span><span class="p">,</span> <span class="n">animate</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">y</span><span class="p">)),</span>
<span class="n">interval</span><span class="o">=</span><span class="mi">25</span><span class="p">,</span> <span class="n">blit</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">init_func</span><span class="o">=</span><span class="n">init</span><span class="p">)</span>
<span class="n">ani</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">'double_pendulum.mp4'</span><span class="p">,</span> <span class="n">fps</span><span class="o">=</span><span class="mi">15</span><span class="p">)</span>
</pre></div>
</div>
<p>Contact Michael Droettboom for the login password to upload youtube videos of
google docs to the mplgithub account.</p>
</div>
<div class="section" id="generating-inheritance-diagrams">
<span id="inheritance-diagrams"></span><h3>Generating inheritance diagrams<a class="headerlink" href="#generating-inheritance-diagrams" title="Permalink to this headline">¶</a></h3>
<p>Class inheritance diagrams can be generated with the
<code class="docutils literal notranslate"><span class="pre">inheritance-diagram</span></code> directive. To use it, provide the
directive with a number of class or module names (separated by
whitespace). If a module name is provided, all classes in that module
will be used. All of the ancestors of these classes will be included
in the inheritance diagram.</p>
<p>A single option is available: <em>parts</em> controls how many of parts in
the path to the class are shown. For example, if <em>parts</em> == 1, the
class <code class="docutils literal notranslate"><span class="pre">matplotlib.patches.Patch</span></code> is shown as <code class="docutils literal notranslate"><span class="pre">Patch</span></code>. If <em>parts</em>
== 2, it is shown as <code class="docutils literal notranslate"><span class="pre">patches.Patch</span></code>. If <em>parts</em> == 0, the full
path is shown.</p>
<p>Example:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">inheritance-diagram</span><span class="p">::</span> matplotlib.patches matplotlib.lines matplotlib.text
<span class="nc">:parts:</span> <span class="nf">2</span>
</pre></div>
</div>
<img src="../_images/inheritance-dedcc1c71ae54be773d8e45d7e30897709db8581.png" alt="Inheritance diagram of matplotlib.patches, matplotlib.lines, matplotlib.text" usemap="#inheritance03ab0131b5" class="inheritance"/>
<map id="inheritance03ab0131b5" name="inheritance03ab0131b5">
<area shape="rect" id="node1" href="../api/artist_api.html#matplotlib.artist.Artist" target="_top" title="Abstract base class for someone who renders into a" alt="" coords="46,282,135,305"/>
<area shape="rect" id="node2" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" target="_top" title="A line - the line can have both a solid linestyle connecting all" alt="" coords="225,236,321,259"/>
<area shape="rect" id="node7" href="../api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch" target="_top" title="A patch is a 2D artist with a face color and an edge color." alt="" coords="221,282,325,305"/>
<area shape="rect" id="node25" href="../api/text_api.html#matplotlib.text.Text" target="_top" title="Handle storing and drawing of text in window or data coordinates." alt="" coords="236,535,310,559"/>
<area shape="rect" id="node3" href="../api/_as_gen/matplotlib.lines.VertexSelector.html#matplotlib.lines.VertexSelector" target="_top" title="Manage the callbacks to maintain a list of selected vertices for" alt="" coords="19,236,161,259"/>
<area shape="rect" id="node4" href="../api/_as_gen/matplotlib.patches.Arc.html#matplotlib.patches.Arc" target="_top" title="An elliptical arc.  Because it performs various optimizations, it" alt="" coords="630,5,722,29"/>
<area shape="rect" id="node5" href="../api/_as_gen/matplotlib.patches.Ellipse.html#matplotlib.patches.Ellipse" target="_top" title="A scale-free ellipse." alt="" coords="401,27,514,51"/>
<area shape="rect" id="node10" href="../api/_as_gen/matplotlib.patches.Circle.html#matplotlib.patches.Circle" target="_top" title="A circle patch." alt="" coords="623,51,730,75"/>
<area shape="rect" id="node6" href="../api/_as_gen/matplotlib.patches.Arrow.html#matplotlib.patches.Arrow" target="_top" title="An arrow patch." alt="" coords="404,74,511,97"/>
<area shape="rect" id="node12" href="../api/_as_gen/matplotlib.patches.RegularPolygon.html#matplotlib.patches.RegularPolygon" target="_top" title="A regular polygon patch." alt="" coords="374,120,541,143"/>
<area shape="rect" id="node14" href="../api/_as_gen/matplotlib.patches.FancyArrowPatch.html#matplotlib.patches.FancyArrowPatch" target="_top" title="A fancy arrow patch. It draws an arrow using the :class:`ArrowStyle`." alt="" coords="370,166,545,190"/>
<area shape="rect" id="node17" href="../api/_as_gen/matplotlib.patches.Polygon.html#matplotlib.patches.Polygon" target="_top" title="A general polygon patch." alt="" coords="397,212,518,236"/>
<area shape="rect" id="node18" href="../api/_as_gen/matplotlib.patches.FancyBboxPatch.html#matplotlib.patches.FancyBboxPatch" target="_top" title="Draw a fancy box around a rectangle with lower left at *xy*=(*x*," alt="" coords="372,258,543,282"/>
<area shape="rect" id="node19" href="../api/_as_gen/matplotlib.patches.PathPatch.html#matplotlib.patches.PathPatch" target="_top" title="A general polycurve path patch." alt="" coords="392,304,523,328"/>
<area shape="rect" id="node20" href="../api/_as_gen/matplotlib.patches.Rectangle.html#matplotlib.patches.Rectangle" target="_top" title="Draw a rectangle with lower left at *xy* = (*x*, *y*) with" alt="" coords="391,350,524,374"/>
<area shape="rect" id="node21" href="../api/_as_gen/matplotlib.patches.Shadow.html#matplotlib.patches.Shadow" target="_top" title="patches.Shadow" alt="" coords="398,396,517,420"/>
<area shape="rect" id="node22" href="../api/_as_gen/matplotlib.patches.Wedge.html#matplotlib.patches.Wedge" target="_top" title="Wedge shaped patch." alt="" coords="401,443,514,466"/>
<area shape="rect" id="node23" href="../api/_as_gen/matplotlib.patches.YAArrow.html#matplotlib.patches.YAArrow" target="_top" title="Yet another arrow class." alt="" coords="396,489,519,512"/>
<area shape="rect" id="node8" href="../api/_as_gen/matplotlib.patches.ArrowStyle.html#matplotlib.patches.ArrowStyle" target="_top" title=":class:`ArrowStyle` is a container class which defines several" alt="" coords="21,190,160,213"/>
<area shape="rect" id="node9" href="../api/_as_gen/matplotlib.patches.BoxStyle.html#matplotlib.patches.BoxStyle" target="_top" title=":class:`BoxStyle` is a container class which defines several" alt="" coords="27,143,153,167"/>
<area shape="rect" id="node11" href="../api/_as_gen/matplotlib.patches.CirclePolygon.html#matplotlib.patches.CirclePolygon" target="_top" title="A polygon-approximation of a circle patch." alt="" coords="598,120,754,143"/>
<area shape="rect" id="node13" href="../api/_as_gen/matplotlib.patches.ConnectionPatch.html#matplotlib.patches.ConnectionPatch" target="_top" title="A :class:`~matplotlib.patches.ConnectionPatch` class is to make" alt="" coords="590,166,763,190"/>
<area shape="rect" id="node15" href="../api/_as_gen/matplotlib.patches.ConnectionStyle.html#matplotlib.patches.ConnectionStyle" target="_top" title=":class:`ConnectionStyle` is a container class which defines" alt="" coords="5,97,176,121"/>
<area shape="rect" id="node16" href="../api/_as_gen/matplotlib.patches.FancyArrow.html#matplotlib.patches.FancyArrow" target="_top" title="Like Arrow, but lets you set head width and head height independently." alt="" coords="605,212,747,236"/>
<area shape="rect" id="node24" href="../api/text_api.html#matplotlib.text.Annotation" target="_top" title="text.Annotation" alt="" coords="400,535,515,559"/>
<area shape="rect" id="node27" href="../api/text_api.html#matplotlib.text.TextWithDash" target="_top" title="This is basically a :class:`~matplotlib.text.Text` with a dash" alt="" coords="391,581,524,605"/>
<area shape="rect" id="node26" href="../api/text_api.html#matplotlib.text.OffsetFrom" target="_top" title="Callable helper class for working with `Annotation`" alt="" coords="33,51,148,75"/>
</map></div>
<div class="section" id="emacs-helpers">
<span id="id5"></span><h3>Emacs helpers<a class="headerlink" href="#emacs-helpers" title="Permalink to this headline">¶</a></h3>
<p>There is an emacs mode <a class="reference external" href="http://docutils.sourceforge.net/tools/editors/emacs/rst.el">rst.el</a> which
automates many important ReST tasks like building and updating
table-of-contents, and promoting or demoting section headings. Here
is the basic <code class="docutils literal notranslate"><span class="pre">.emacs</span></code> configuration:</p>
<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nb">require</span> <span class="ss">'rst</span><span class="p">)</span>
<span class="p">(</span><span class="k">setq</span> <span class="nv">auto-mode-alist</span>
<span class="p">(</span><span class="nb">append</span> <span class="o">'</span><span class="p">((</span><span class="s">"\\.txt$"</span> <span class="o">.</span> <span class="nv">rst-mode</span><span class="p">)</span>
<span class="p">(</span><span class="s">"\\.rst$"</span> <span class="o">.</span> <span class="nv">rst-mode</span><span class="p">)</span>
<span class="p">(</span><span class="s">"\\.rest$"</span> <span class="o">.</span> <span class="nv">rst-mode</span><span class="p">))</span> <span class="nv">auto-mode-alist</span><span class="p">))</span>
</pre></div>
</div>
<p>Some helpful functions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">C</span><span class="o">-</span><span class="n">c</span> <span class="n">TAB</span> <span class="o">-</span> <span class="n">rst</span><span class="o">-</span><span class="n">toc</span><span class="o">-</span><span class="n">insert</span>
<span class="n">Insert</span> <span class="n">table</span> <span class="n">of</span> <span class="n">contents</span> <span class="n">at</span> <span class="n">point</span>
<span class="n">C</span><span class="o">-</span><span class="n">c</span> <span class="n">C</span><span class="o">-</span><span class="n">u</span> <span class="o">-</span> <span class="n">rst</span><span class="o">-</span><span class="n">toc</span><span class="o">-</span><span class="n">update</span>
<span class="n">Update</span> <span class="n">the</span> <span class="n">table</span> <span class="n">of</span> <span class="n">contents</span> <span class="n">at</span> <span class="n">point</span>
<span class="n">C</span><span class="o">-</span><span class="n">c</span> <span class="n">C</span><span class="o">-</span><span class="n">l</span> <span class="n">rst</span><span class="o">-</span><span class="n">shift</span><span class="o">-</span><span class="n">region</span><span class="o">-</span><span class="n">left</span>
<span class="n">Shift</span> <span class="n">region</span> <span class="n">to</span> <span class="n">the</span> <span class="n">left</span>
<span class="n">C</span><span class="o">-</span><span class="n">c</span> <span class="n">C</span><span class="o">-</span><span class="n">r</span> <span class="n">rst</span><span class="o">-</span><span class="n">shift</span><span class="o">-</span><span class="n">region</span><span class="o">-</span><span class="n">right</span>
<span class="n">Shift</span> <span class="n">region</span> <span class="n">to</span> <span class="n">the</span> <span class="n">right</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2018 The Matplotlib development team.
<br />
Last updated on Aug 11, 2018.
Created using
<ahref="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
Doc version v2.2.3-1-gd47e15e7a.
</div>
</body>
<footer>
</footer>
</html>