-
Notifications
You must be signed in to change notification settings - Fork 59
Expand file tree
/
Copy pathdocumenting_mpl.html
More file actions
1131 lines (1064 loc) · 94.8 KB
/
documenting_mpl.html
File metadata and controls
1131 lines (1064 loc) · 94.8 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
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Writing documentation — Matplotlib 3.3.2 documentation</title>
<link rel="stylesheet" href="../_static/mpl.css?3.3.2" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery-binder.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery-dataframe.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/clipboard.min.js"></script>
<script src="../_static/copybutton.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Matplotlib 3.3.2 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="next" title="Developer's guide for creating scales and transformations" href="add_new_projection.html" />
<link rel="prev" title="Developer's tips for testing" href="testing.html" />
<link rel="top" title="Matplotlib 3.3.2 documentation" href="#" />
<link rel="canonical" href="https://matplotlib.org/stable/devel/documenting_mpl.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
<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 (v3.3.2). 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 id="annc-banner">
</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 3.3.2</span></div>
<img src="../_static/logo2_compressed.svg" 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>
<nav class="main-nav">
<ul>
<li><a href="../users/installing.html">Installation</a></li>
<li><a href="../contents.html">Documentation</a></li>
<li><a href="../gallery/index.html">Examples</a></li>
<li><a href="../tutorials/index.html">Tutorials</a></li>
<li><a href="index.html">Contributing</a></li>
<li class="nav-right">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" placeholder="Search"/>
</form>
</li>
</ul>
</nav>
<div class="related" role="navigation" aria-label="related navigation">
<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="add_new_projection.html" title="Developer's guide for creating scales and transformations"
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="../contents.html">contents</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Matplotlib Developers' Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">Writing documentation</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<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><ul>
<li><a class="reference internal" href="#quote-positions">Quote positions</a></li>
<li><a class="reference internal" href="#id4">Function arguments</a></li>
<li><a class="reference internal" href="#quotes-for-strings">Quotes for strings</a></li>
<li><a class="reference internal" href="#parameter-type-descriptions">Parameter type descriptions</a></li>
<li><a class="reference internal" href="#referencing-types">Referencing types</a></li>
<li><a class="reference internal" href="#default-values">Default values</a></li>
<li><a class="reference internal" href="#see-also-sections"><code class="docutils literal notranslate"><span class="pre">See</span> <span class="pre">also</span></code> sections</a></li>
<li><a class="reference internal" href="#wrapping-parameter-lists">Wrapping parameter lists</a></li>
<li><a class="reference internal" href="#rcparams">rcParams</a></li>
</ul>
</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="#inheriting-docstrings">Inheriting docstrings</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><ul>
<li><a class="reference internal" href="#order-of-examples-in-the-gallery">Order of examples in the gallery</a></li>
</ul>
</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="add_new_projection.html" title="next chapter">Developer's guide for creating scales and transformations</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" role="main">
<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="contents multicol-toc local topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#getting-started" id="id7">Getting started</a><ul>
<li><a class="reference internal" href="#general-file-structure" id="id8">General file structure</a></li>
<li><a class="reference internal" href="#installing-dependencies" id="id9">Installing dependencies</a></li>
<li><a class="reference internal" href="#building-the-docs" id="id10">Building the docs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-rest-pages" id="id11">Writing ReST pages</a><ul>
<li><a class="reference internal" href="#formatting-and-style-conventions" id="id12">Formatting and style conventions</a><ul>
<li><a class="reference internal" href="#section-name-formatting" id="id13">Section name formatting</a></li>
<li><a class="reference internal" href="#function-arguments" id="id14">Function arguments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#referring-to-other-documents-and-sections" id="id15">Referring to other documents and sections</a></li>
<li><a class="reference internal" href="#referring-to-other-code" id="id16">Referring to other code</a></li>
<li><a class="reference internal" href="#including-figures-and-files" id="id17">Including figures and files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-docstrings" id="id18">Writing docstrings</a><ul>
<li><a class="reference internal" href="#example-docstring" id="id19">Example docstring</a></li>
<li><a class="reference internal" href="#formatting-conventions" id="id20">Formatting conventions</a><ul>
<li><a class="reference internal" href="#quote-positions" id="id21">Quote positions</a></li>
<li><a class="reference internal" href="#id4" id="id22">Function arguments</a></li>
<li><a class="reference internal" href="#quotes-for-strings" id="id23">Quotes for strings</a></li>
<li><a class="reference internal" href="#parameter-type-descriptions" id="id24">Parameter type descriptions</a></li>
<li><a class="reference internal" href="#referencing-types" id="id25">Referencing types</a></li>
<li><a class="reference internal" href="#default-values" id="id26">Default values</a></li>
<li><a class="reference internal" href="#see-also-sections" id="id27"><code class="docutils literal notranslate"><span class="pre">See</span> <span class="pre">also</span></code> sections</a></li>
<li><a class="reference internal" href="#wrapping-parameter-lists" id="id28">Wrapping parameter lists</a></li>
<li><a class="reference internal" href="#rcparams" id="id29">rcParams</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setters-and-getters" id="id30">Setters and getters</a></li>
<li><a class="reference internal" href="#keyword-arguments" id="id31">Keyword arguments</a></li>
<li><a class="reference internal" href="#inheriting-docstrings" id="id32">Inheriting docstrings</a></li>
<li><a class="reference internal" href="#adding-figures" id="id33">Adding figures</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-examples-and-tutorials" id="id34">Writing examples and tutorials</a><ul>
<li><a class="reference internal" href="#order-of-examples-in-the-gallery" id="id35">Order of examples in the gallery</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous" id="id36">Miscellaneous</a><ul>
<li><a class="reference internal" href="#adding-animations" id="id37">Adding animations</a></li>
<li><a class="reference internal" href="#generating-inheritance-diagrams" id="id38">Generating inheritance diagrams</a></li>
<li><a class="reference internal" href="#emacs-helpers" id="id39">Emacs helpers</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="getting-started">
<h2><a class="toc-backref" href="#contents">Getting started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<div class="section" id="general-file-structure">
<h3><a class="toc-backref" href="#contents">General file structure</a><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>, <code class="file docutils literal notranslate"><span class="pre">tutorials/</span></code>, and
<code class="file docutils literal notranslate"><span class="pre">examples/</span></code> directories. The <code class="file docutils literal notranslate"><span class="pre">doc/</span></code> directory contains
configuration files for Sphinx and 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 are rendered to documentation pages.</p>
<p>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 (<code class="file docutils literal notranslate"><span class="pre">doc/users</span></code>), developers
guide (<code class="file docutils literal notranslate"><span class="pre">doc/devel</span></code>), api reference (<code class="file docutils literal notranslate"><span class="pre">doc/api</span></code>), and FAQs
(<code class="file docutils literal notranslate"><span class="pre">doc/faq</span></code>). 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">doc/gallery</span></code> and <code class="file docutils literal notranslate"><span class="pre">doc/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.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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">doc/gallery</span></code>,
<code class="file docutils literal notranslate"><span class="pre">doc/tutorials</span></code>, and <code class="file docutils literal notranslate"><span class="pre">doc/api</span></code> (excepting
<code class="file docutils literal notranslate"><span class="pre">doc/api/api_changes/</span></code>). <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> regenerates files in these
directories when building documentation.</p>
</div>
</div>
<div class="section" id="installing-dependencies">
<h3><a class="toc-backref" href="#contents">Installing dependencies</a><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. To build the documentation
you will need to (1) set up an appropriate Python environment and (2)
separately install LaTeX and Graphviz.</p>
<p>To (1) set up an appropriate Python environment for building the
documentation, you should:</p>
<ul class="simple">
<li>create a clean virtual environment with no existing Matplotlib
installation</li>
<li>install the Python packages required for Matplotlib</li>
<li>install the additional Python packages required to build the documentation</li>
</ul>
<p>There are several extra python packages 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>, which is
shown below:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Requirements for building docs</span>
<span class="c1">#</span>
<span class="c1"># You will first need a matching Matplotlib installation</span>
<span class="c1"># e.g (from the Matplotlib root directory)</span>
<span class="c1"># pip install -e .</span>
<span class="c1">#</span>
<span class="c1"># Install the documentation requirements with:</span>
<span class="c1"># pip install -r requirements/doc/doc-requirements.txt</span>
<span class="c1">#</span>
<span class="n">sphinx</span><span class="o">>=</span><span class="mf">1.8</span><span class="o">.</span><span class="mi">1</span><span class="p">,</span><span class="o">!=</span><span class="mf">2.0</span><span class="o">.</span><span class="mi">0</span>
<span class="n">colorspacious</span>
<span class="n">ipython</span>
<span class="n">ipywidgets</span>
<span class="n">numpydoc</span><span class="o">>=</span><span class="mf">0.8</span>
<span class="n">sphinxcontrib</span><span class="o">-</span><span class="n">svg2pdfconverter</span><span class="o">>=</span><span class="mf">1.1</span><span class="o">.</span><span class="mi">0</span>
<span class="n">sphinx</span><span class="o">-</span><span class="n">gallery</span><span class="o">>=</span><span class="mf">0.7</span>
<span class="n">sphinx</span><span class="o">-</span><span class="n">copybutton</span>
<span class="n">scipy</span>
</pre></div>
</div>
<p>To (2) set up LaTeX and Graphviz dependencies you should:</p>
<ul class="simple">
<li>install a minimal working LaTeX distribution</li>
<li>install the LaTeX packages cm-super and dvipng</li>
<li>install <a class="reference external" href="http://www.graphviz.org/download">Graphviz</a></li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The documentation will not build without LaTeX and Graphviz. These are not
Python packages and must be installed separately.</p>
</div>
</div>
<div class="section" id="building-the-docs">
<h3><a class="toc-backref" href="#contents">Building the docs</a><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> <span class="pre">--keep-going</span></code> by default to build
the complete docs but exit with exit status 1 if there are warnings. 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>On Windows the arguments must be at the end of the statement:</p>
<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span>make html SPHINXOPTS=
</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, either use the format shown above or set options as environment variables, e.g.:</p>
<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span><span class="k">set</span> <span class="nv">O</span><span class="p">=</span>-W --keep-going -j4
make html
</pre></div>
</div>
</div>
</div>
<div class="section" id="writing-rest-pages">
<span id="id1"></span><h2><a class="toc-backref" href="#contents">Writing ReST pages</a><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><a class="toc-backref" href="#contents">Formatting and style conventions</a><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><a class="toc-backref" href="#contents">Section name formatting</a><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><a class="toc-backref" href="#contents">Function arguments</a><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><a class="toc-backref" href="#contents">Referring to other documents and sections</a><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="https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html">references</a> between documents.</p>
<p>Documents can be linked with the <code class="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">
<span id="id2"></span><h3><a class="toc-backref" href="#contents">Referring to other code</a><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-rst notranslate"><div class="highlight"><pre><span></span><span class="nv">`matplotlib.collections.LineCollection`</span>
</pre></div>
</div>
<p>generates a link like this: <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>.</p>
<p><em>Note:</em> We use the sphinx setting <code class="docutils literal notranslate"><span class="pre">default_role</span> <span class="pre">=</span> <span class="pre">'obj'</span></code> so that you don't
have to use qualifiers like <code class="docutils literal notranslate"><span class="pre">:class:</span></code>, <code class="docutils literal notranslate"><span class="pre">:func:</span></code>, <code class="docutils literal notranslate"><span class="pre">:meth:</span></code> and the likes.</p>
<p>Often, you don't want to show the full package and module name. As long as the
target is unanbigous you can simply leave them out:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="nv">`.LineCollection`</span>
</pre></div>
</div>
<p>and the link still works: <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>If there are multiple code elements with the same name (e.g. <code class="docutils literal notranslate"><span class="pre">plot()</span></code> is a
method in multiple classes), you'll have to extend the definition:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="nv">`.pyplot.plot`</span> or <span class="nv">`.Axes.plot`</span>
</pre></div>
</div>
<p>These will show up as <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">pyplot.plot</span></code></a> or <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">Axes.plot</span></code></a>. To still show only the
last segment you can add a tilde as prefix:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="nv">`~.pyplot.plot`</span> or <span class="nv">`~.Axes.plot`</span>
</pre></div>
</div>
<p>will render as <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> or <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">plot</span></code></a>.</p>
<p>Other packages can also be linked via
<a class="reference external" href="http://www.sphinx-doc.org/en/master/ext/intersphinx.html">intersphinx</a>:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="nv">`numpy.mean`</span>
</pre></div>
</div>
<p>will return this link: <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.mean.html#numpy.mean" title="(in NumPy v1.19)"><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>). If external linking fails,
you can check the full list of referenceable objects with the following
commands:</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.python.org/3/objects.inv'</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>
<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/scipy/reference/objects.inv'</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://pandas.pydata.org/pandas-docs/stable/objects.inv'</span>
</pre></div>
</div>
</div>
<div class="section" id="including-figures-and-files">
<span id="rst-figures-and-includes"></span><h3><a class="toc-backref" href="#contents">Including figures and files</a><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">thirdpartypackages/index.rst</span></code> displays the images for the third-party
packages as static images:</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="../thirdpartypackages/index.html#thirdparty-index"><span class="std std-ref">Third party packages</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/lines_bars_and_markers/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="id3"></span><h2><a class="toc-backref" href="#contents">Writing docstrings</a><a class="headerlink" href="#writing-docstrings" title="Permalink to this headline">¶</a></h2>
<p>Most of the API documentation is written in docstrings. These are comment
blocks in source code that explain how the code works.</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>
<p>All new or edited docstrings should conform to the <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a>.
Much of the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> syntax discussed above (<a class="reference internal" href="#writing-rest-pages"><span class="std std-ref">Writing ReST pages</span></a>) 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><a class="toc-backref" href="#contents">Example docstring</a><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 : float or array-like</span>
<span class="sd"> y-indexes where to plot the lines.</span>
<span class="sd"> xmin, xmax : float or 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 the same length.</span>
<span class="sd"> colors : array-like of colors, default: 'k'</span>
<span class="sd"> linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, default: 'solid'</span>
<span class="sd"> label : str, 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="https://www.sphinx-doc.org/en/master/contents.html">documentation</a> concerning ReST
markup and working with Sphinx in general.</p>
</div>
<div class="section" id="formatting-conventions">
<h3><a class="toc-backref" href="#contents">Formatting conventions</a><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://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</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>
<div class="section" id="quote-positions">
<h4><a class="toc-backref" href="#contents">Quote positions</a><a class="headerlink" href="#quote-positions" title="Permalink to this headline">¶</a></h4>
<p>The quotes for single line docstrings are on the same line (pydocstyle D200):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">get_linewidth</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Return the line width in points."""</span>
</pre></div>
</div>
<p>The quotes for multi-line docstrings are on separate lines (pydocstyle D213):</p>
<div class="highlight-default 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">ls</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd">Set the linestyle of the line.</span>
<span class="sd">[...]</span>
<span class="sd">"""</span>
</pre></div>
</div>
</div>
<div class="section" id="id4">
<h4><a class="toc-backref" href="#contents">Function arguments</a><a class="headerlink" href="#id4" 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>If <span class="ge">*linestyles*</span> is <span class="ge">*None*</span>, the default is 'solid'.
</pre></div>
</div>
<p>Do not use the <code class="docutils literal notranslate"><span class="pre">`default</span> <span class="pre">role`</span></code> or 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>Neither <span class="nv">`argument`</span> nor <span class="s">``argument``</span> should be used.
</pre></div>
</div>
</div>
<div class="section" id="quotes-for-strings">
<h4><a class="toc-backref" href="#contents">Quotes for strings</a><a class="headerlink" href="#quotes-for-strings" title="Permalink to this headline">¶</a></h4>
<p>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>
<p>Use simple single or double quotes when giving string values, e.g.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>If 'tight', try to figure out the tight bbox of the figure.
No <span class="s">``'extra'``</span> literal quotes.
</pre></div>
</div>
<p>The use of extra literal quotes around the text is discouraged. While they
slightly improve the rendered docs, they are cumbersome to type and difficult
to read in plain-text docs.</p>
</div>
<div class="section" id="parameter-type-descriptions">
<h4><a class="toc-backref" href="#contents">Parameter type descriptions</a><a class="headerlink" href="#parameter-type-descriptions" title="Permalink to this headline">¶</a></h4>
<p>The main goal for parameter type descriptions is to be readable and
understandable by humans. If the possible types are too complex use a
simplification for the type description and explain the type more
precisely in the text.</p>
<p>Generally, the <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a> conventions apply. The following
rules expand on them where the numpydoc conventions are not specific.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">float</span></code> for a type that can be any number.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">(float,</span> <span class="pre">float)</span></code> to describe a 2D position. The parentheses should be
included to make the tuple-ness more obvious.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">array-like</span></code> for homogeneous numeric sequences, which could
typically be a numpy.array. Dimensionality may be specified using <code class="docutils literal notranslate"><span class="pre">2D</span></code>,
<code class="docutils literal notranslate"><span class="pre">3D</span></code>, <code class="docutils literal notranslate"><span class="pre">n-dimensional</span></code>. If you need to have variables denoting the
sizes of the dimensions, use capital letters in brackets
(<code class="docutils literal notranslate"><span class="pre">array-like</span> <span class="pre">(M,</span> <span class="pre">N)</span></code>). When referring to them in the text they are easier
read and no special formatting is needed.</p>
<p><code class="docutils literal notranslate"><span class="pre">float</span></code> is the implicit default dtype for array-likes. For other dtypes
use <code class="docutils literal notranslate"><span class="pre">array-like</span> <span class="pre">of</span> <span class="pre">int</span></code>.</p>
<p>Some possible uses:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">2</span><span class="n">D</span> <span class="n">array</span><span class="o">-</span><span class="n">like</span>
<span class="n">array</span><span class="o">-</span><span class="n">like</span> <span class="p">(</span><span class="n">N</span><span class="p">)</span>
<span class="n">array</span><span class="o">-</span><span class="n">like</span> <span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">N</span><span class="p">)</span>
<span class="n">array</span><span class="o">-</span><span class="n">like</span> <span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">N</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
<span class="n">array</span><span class="o">-</span><span class="n">like</span> <span class="n">of</span> <span class="nb">int</span>
</pre></div>
</div>
<p>Non-numeric homogeneous sequences are described as lists, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>list of str
list of `.Artist`
</pre></div>
</div>
</div>
<div class="section" id="referencing-types">
<h4><a class="toc-backref" href="#contents">Referencing types</a><a class="headerlink" href="#referencing-types" title="Permalink to this headline">¶</a></h4>
<p>Generally, the rules from <a class="reference internal" href="#referring-to-other-code">referring-to-other-code</a> apply. More specifically:</p>
<p>Use full references <code class="docutils literal notranslate"><span class="pre">`~matplotlib.colors.Normalize`</span></code> with an
abbreviation tilde in parameter types. While the full name helps the
reader of plain text docstrings, the HTML does not need to show the full
name as it links to it. Hence, the <code class="docutils literal notranslate"><span class="pre">~</span></code>-shortening keeps it more readable.</p>
<p>Use abbreviated links <code class="docutils literal notranslate"><span class="pre">`.Normalize`</span></code> in the text.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>norm : <span class="nv">`~matplotlib.colors.Normalize`</span>, optional
A <span class="nv">`.Normalize`</span> instance is used to scale luminance data to 0, 1.
</pre></div>
</div>
</div>
<div class="section" id="default-values">
<h4><a class="toc-backref" href="#contents">Default values</a><a class="headerlink" href="#default-values" title="Permalink to this headline">¶</a></h4>
<p>As opposed to the numpydoc guide, parameters need not be marked as
<em>optional</em> if they have a simple default:</p>
<ul class="simple">
<li>use <code class="docutils literal notranslate"><span class="pre">{name}</span> <span class="pre">:</span> <span class="pre">{type},</span> <span class="pre">default:</span> <span class="pre">{val}</span></code> when possible.</li>
<li>use <code class="docutils literal notranslate"><span class="pre">{name}</span> <span class="pre">:</span> <span class="pre">{type},</span> <span class="pre">optional</span></code> and describe the default in the text if
it cannot be explained sufficiently in the recommended manner.</li>
</ul>
<p>The default value should provide semantic information targeted at a human
reader. In simple cases, it restates the value in the function signature.
If applicable, units should be added.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Prefer:
interval : int, default: 1000ms
over:
interval : int, default: 1000
</pre></div>
</div>
<p>If <em>None</em> is only used as a sentinel value for "parameter not specified", do
not document it as the default. Depending on the context, give the actual
default, or mark the parameter as optional if not specifying has no particular
effect.</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>Prefer:
dpi : float, default: <span class="na">:rc:</span><span class="nv">`figure.dpi`</span>
over:
dpi : float, default: None
Prefer:
textprops : dict, optional
Dictionary of keyword parameters to be passed to the
<span class="nv">`~matplotlib.text.Text`</span> instance contained inside TextArea.
over:
textprops : dict, default: None
Dictionary of keyword parameters to be passed to the
<span class="nv">`~matplotlib.text.Text`</span> instance contained inside TextArea.
</pre></div>
</div>
</div>
<div class="section" id="see-also-sections">
<h4><a class="toc-backref" href="#contents"><code class="docutils literal notranslate"><span class="pre">See</span> <span class="pre">also</span></code> sections</a><a class="headerlink" href="#see-also-sections" title="Permalink to this headline">¶</a></h4>
<p>Sphinx automatically links code elements in the definition blocks of <code class="docutils literal notranslate"><span class="pre">See</span>
<span class="pre">also</span></code> sections. No need to use backticks there:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">See</span> <span class="n">also</span>
<span class="o">--------</span>
<span class="n">vlines</span> <span class="p">:</span> <span class="n">vertical</span> <span class="n">lines</span>
<span class="n">axhline</span><span class="p">:</span> <span class="n">horizontal</span> <span class="n">line</span> <span class="n">across</span> <span class="n">the</span> <span class="n">axes</span>
</pre></div>
</div>
</div>
<div class="section" id="wrapping-parameter-lists">
<h4><a class="toc-backref" href="#contents">Wrapping parameter lists</a><a class="headerlink" href="#wrapping-parameter-lists" title="Permalink to this headline">¶</a></h4>
<p>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 (no indent because pydoc will
parse the docstring and strip the line continuation so that indent would
result in a lot of whitespace within the line):</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 : {'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>
</div>
<div class="section" id="rcparams">
<h4><a class="toc-backref" href="#contents">rcParams</a><a class="headerlink" href="#rcparams" title="Permalink to this headline">¶</a></h4>
<p>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> <span class="pre">=</span> <span class="pre">'default'</span></code>, which is a link
to the <code class="file docutils literal notranslate"><span class="pre">matplotlibrc</span></code> file description.</p>
</div>
</div>
<div class="section" id="setters-and-getters">
<h3><a class="toc-backref" href="#contents">Setters and getters</a><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.8)"><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 <a class="reference internal" href="../api/_as_gen/matplotlib.pyplot.getp.html#matplotlib.pyplot.getp" title="matplotlib.pyplot.getp"><code class="xref py py-obj docutils literal notranslate"><span class="pre">getp</span></code></a> functions.</p>
<p>The Parameters block of property setter methods is parsed to document the
accepted values, e.g. the docstring of <a class="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D.set_linestyle" title="matplotlib.lines.Line2D.set_linestyle"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Line2D.set_linestyle</span></code></a> starts with</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">ls</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Set the linestyle of the line.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}</span>
<span class="sd"> etc.</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>which results in the following line in the output of <code class="docutils literal notranslate"><span class="pre">plt.setp(line)</span></code> or
<code class="docutils literal notranslate"><span class="pre">plt.setp(line,</span> <span class="pre">"linestyle")</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">linestyle</span> <span class="ow">or</span> <span class="n">ls</span><span class="p">:</span> <span class="p">{</span><span class="s1">'-'</span><span class="p">,</span> <span class="s1">'--'</span><span class="p">,</span> <span class="s1">'-.'</span><span class="p">,</span> <span class="s1">':'</span><span class="p">,</span> <span class="s1">''</span><span class="p">,</span> <span class="p">(</span><span class="n">offset</span><span class="p">,</span> <span class="n">on</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">seq</span><span class="p">),</span> <span class="o">...</span><span class="p">}</span>
</pre></div>
</div>
<p>In some rare cases (mostly, setters which accept both a single tuple and an
unpacked tuple), the accepted values cannot be documented in such a fashion;
in that case, they can be documented as an <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">ACCEPTS:</span></code> block, e.g. for
<a class="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.set_xlim.html#matplotlib.axes.Axes.set_xlim" title="matplotlib.axes.Axes.set_xlim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">axes.Axes.set_xlim</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">set_xlim</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">...</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Set the x-axis view limits.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> left : float, optional</span>
<span class="sd"> The left xlim in data coordinates. Passing *None* leaves the</span>
<span class="sd"> limit unchanged.</span>
<span class="sd"> The left and right xlims may also be passed as the tuple</span>
<span class="sd"> (*left*, *right*) as the first positional argument (or as</span>
<span class="sd"> the *left* keyword argument).</span>
<span class="sd"> .. ACCEPTS: (bottom: float, top: float)</span>
<span class="sd"> right : float, optional</span>
<span class="sd"> etc.</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Note that the leading <code class="docutils literal notranslate"><span class="pre">..</span></code> makes the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">ACCEPTS:</span></code> block a reST comment,
hiding it from the rendered docs.</p>
</div>
<div class="section" id="keyword-arguments">
<h3><a class="toc-backref" href="#contents">Keyword arguments</a><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</span><span class="o">.</span><span class="n">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_docstr)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., <a class="reference internal" href="../api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch.__init__" title="matplotlib.patches.Patch.__init__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">matplotlib.patches.Patch.__init__</span></code></a>, 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="inheriting-docstrings">
<h3><a class="toc-backref" href="#contents">Inheriting docstrings</a><a class="headerlink" href="#inheriting-docstrings" title="Permalink to this headline">¶</a></h3>
<p>If a subclass overrides a method but does not change the semantics, we can
reuse the parent docstring for the method of the child class. Python does this
automatically, if the subclass method does not have a docstring.</p>
<p>Use a plain comment <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">docstring</span> <span class="pre">inherited</span></code> to denote the intention to reuse
the parent docstring. That way we do not accidentally create a docstring in
the future:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">A</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
<span class="sd">"""The parent docstring."""</span>
<span class="k">pass</span>
<span class="k">class</span> <span class="nc">B</span><span class="p">(</span><span class="n">A</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
<span class="c1"># docstring inherited</span>
<span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="adding-figures">
<span id="docstring-adding-figures"></span><h3><a class="toc-backref" href="#contents">Adding figures</a><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="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/text_labels_and_annotations/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/text_labels_and_annotations/legend.py</span>
<span class="sd">"""</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">examples/text_labels_and_annotations/legend.py</span></code> has been mapped to
<code class="docutils literal notranslate"><span class="pre">gallery/text_labels_and_annotations/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="../api/sphinxext_plot_directive_api.html"><span class="doc">matplotlib.sphinxext.plot_directive</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="id5"></span><h2><a class="toc-backref" href="#contents">Writing examples and tutorials</a><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="k">as</span> <span class="nn">plt</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="k">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="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 class="section" id="order-of-examples-in-the-gallery">
<h3><a class="toc-backref" href="#contents">Order of examples in the gallery</a><a class="headerlink" href="#order-of-examples-in-the-gallery" title="Permalink to this headline">¶</a></h3>
<p>The order of the sections of the <a class="reference internal" href="../tutorials/index.html#tutorials"><span class="std std-ref">Tutorials</span></a> and the <a class="reference internal" href="../gallery/index.html#gallery"><span class="std std-ref">Gallery</span></a>, as
well as the order of the examples within each section are determined in a
two step process from within the <code class="file docutils literal notranslate"><span class="pre">/doc/sphinxext/gallery_order.py</span></code>:</p>
<ul class="simple">
<li><em>Explicit order</em>: This file contains a list of folders for the section order
and a list of examples for the subsection order. The order of the items
shown in the doc pages is the order those items appear in those lists.</li>
<li><em>Implicit order</em>: If a folder or example is not in those lists, it will be
appended after the explicitly ordered items and all of those additional
items will be ordered by pathname (for the sections) or by filename
(for the subsections).</li>
</ul>
<p>As a consequence, if you want to let your example appear in a certain
position in the gallery, extend those lists with your example.
In case no explicit order is desired or necessary, still make sure
to name your example consistently, i.e. use the main function or subject
of the example as first word in the filename; e.g. an image example
should ideally be named similar to <code class="file docutils literal notranslate"><span class="pre">imshow_mynewexample.py</span></code>.</p>
</div>
</div>
<div class="section" id="miscellaneous">