-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathdocumentation-style-guide.html
1291 lines (1213 loc) · 101 KB
/
documentation-style-guide.html
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>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>SymPy Documentation Style Guide — SymPy 1.8 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="https://live.sympy.org/static/live-core.css" />
<link rel="stylesheet" type="text/css" href="https://live.sympy.org/static/live-autocomplete.css" />
<link rel="stylesheet" type="text/css" href="https://live.sympy.org/static/live-sphinx.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="https://live.sympy.org/static/utilities.js"></script>
<script src="https://live.sympy.org/static/external/classy.js"></script>
<script src="https://live.sympy.org/static/live-core.js"></script>
<script src="https://live.sympy.org/static/live-autocomplete.js"></script>
<script src="https://live.sympy.org/static/live-sphinx.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS_HTML-full"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["\\(", "\\)"]], "displayMath": [["\\[", "\\]"]]}})</script>
<link rel="shortcut icon" href="_static/sympy-notailtext-favicon.ico"/>
<link href="https://docs.sympy.org/latest/documentation-style-guide.html" rel="canonical" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Citing SymPy" href="citing.html" />
</head><body>
<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="citing.html" title="Citing SymPy"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SymPy 1.8 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">SymPy Documentation Style Guide</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="sympy-documentation-style-guide">
<h1>SymPy Documentation Style Guide<a class="headerlink" href="#sympy-documentation-style-guide" title="Permalink to this headline">¶</a></h1>
<p><strong>A Writing Resource for Documentation and Docstrings</strong></p>
<div class="section" id="general-guidelines">
<h2>General Guidelines<a class="headerlink" href="#general-guidelines" title="Permalink to this headline">¶</a></h2>
<p>Documentation is one of the most highly valued aspects of an open source
project. Documentation teaches users and contributors how to use a project, how
to contribute, and the standards of conduct within an open source community.
But according to GitHub’s <a class="reference external" href="https://opensourcesurvey.org/2017/">Open Source Survey</a>, incomplete or confusing documentation is
the most commonly encountered problem in open source. This style guide aims to
change that.</p>
<p>The purpose of this style guide is to provide the SymPy community with a set of
style and formatting guidelines that can be utilized and followed when writing
SymPy documentation. Adhering to the guidelines offered in this style guide
will bring greater consistency and clarity to SymPy’s documentation, supporting
its mission to become a full-featured, open source computer algebra system
(CAS).</p>
<p>The SymPy documentation found at <a class="reference external" href="https://docs.sympy.org/latest/index.html">docs.sympy.org</a> is generated from docstrings in the
source code and dedicated narrative documentation files in the <a class="reference external" href="https://github.com/sympy/sympy/tree/master/doc/src">doc/src
directory</a>. Both are
written in <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> format
extended by <a class="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx</a>.</p>
<p>The documentation contained in the <a class="reference external" href="https://github.com/sympy/sympy/tree/master/doc/src">doc/src directory</a> and the docstrings
embedded in the Python source code are processed by Sphinx and various Sphinx
extensions. This means that the documentation source format is specified by the
documentation processing tools. The SymPy Documentation Style Guide provides
both the essential elements for writing SymPy documentation as well as any
deviations in style we specify relative to these documentation processing tools.
The following lists the processing tools:</p>
<ul class="simple">
<li><p>reStructuredText: Narrative documentation files and documentation strings
embedded in Python code follow the reStructuredText format. Advanced features
not described in this document can be found at
<a class="reference external" href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a>.</p></li>
<li><p>Sphinx: Sphinx includes additional default features for the
reStructuredText specification that are described at: <a class="reference external" href="http://www.sphinx-doc.org/">http://www.sphinx-doc.org/</a>.</p></li>
<li><p>Sphinx extensions included with Sphinx that we enable:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx.ext.autodoc</span></code>: Processes Python source code files for the
associated documentation strings to automatically generate pages containing
the Application Programming Interface (API). See section on calling autodoc
directives in this document to get started. More information is at:
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html">https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html</a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx.ext.graphviz</span></code>: Provides a directive for adding Graphviz graphics.
See <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html">https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html</a> for
more info.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx.ext.mathjax</span></code>: Causes math written in LaTeX to display using
MathJax in the HTML version of the documentation. More information is at:
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax">https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax</a>.
<em>No bearing on documentation source format.</em></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx.ext.linkcode</span></code>: Causes links to source code to direct to the
related files on Github. More information is at:
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html">https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html</a>. <em>No
bearing on documentation source format.</em></p></li>
</ul>
</li>
<li><p>Sphinx extensions that are not included with Sphinx that we enable:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">numpydoc</span></code>: Processes docstrings written in the “numpydoc” format, see
<a class="reference external" href="https://numpydoc.readthedocs.io">https://numpydoc.readthedocs.io</a>. We recommend the subset of numpydoc
formatting features in this document. (Note that we currently use an older
modified fork of numpydoc, which is included in the SymPy source code.)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sphinx_math_dollar</span></code>: Allows math to be delimited with dollar signs
instead of reStructuredText directives (e.g., <code class="docutils literal notranslate"><span class="pre">$a^2$</span></code> instead of
<code class="docutils literal notranslate"><span class="pre">:math:`a^2`</span></code>). See <a class="reference external" href="https://www.sympy.org/sphinx-math-dollar/">https://www.sympy.org/sphinx-math-dollar/</a> for more info.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">matplotlib.sphinxext.plot_directive</span></code>: Provides directives for included
matplotlib generated figures in reStructuredText. See
<a class="reference external" href="https://matplotlib.org/devel/plot_directive.html">https://matplotlib.org/devel/plot_directive.html</a> for more info.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sympylive</span></code>: Adds a button on each example in the HTML documentation that
opens the example in SymPy Live. <em>No bearing on documentation source
format.</em></p></li>
</ul>
</li>
</ul>
<p>Everything supported by the above processing tools is available for use in the
SymPy documentation, but this style guide supersedes any recommendations made
in the above documents. Note that we do not follow PEP 257 or the
www.python.org documentation recommendations.</p>
<p>If you are contributing to SymPy for the first time, please read our
<a class="reference external" href="https://github.com/sympy/sympy/wiki/Introduction-to-contributing">Introduction to Contributing</a> page as
well as this guide.</p>
</div>
<div class="section" id="types-of-documentation">
<h2>Types of Documentation<a class="headerlink" href="#types-of-documentation" title="Permalink to this headline">¶</a></h2>
<p>There are four main locations where SymPy’s documentation can be found:</p>
<p><strong>SymPy Website</strong> <a class="reference external" href="https://sympy.org">https://sympy.org</a></p>
<p>The SymPy website’s primary function is to advertise the software to users and
developers. It also serves as an initial location to point viewers to other
relevant resources on the web. The SymPy website has basic information on SymPy
and how to obtain it, as well as examples to advertise it to users, but it does
not have technical documentation. The source files are located in the SymPy
<a class="reference external" href="https://github.com/sympy/sympy.github.com">webpage directory</a>. Appropriate
items for the website are:</p>
<ul class="simple">
<li><p>General descriptions of what SymPy and the SymPy community are</p></li>
<li><p>Explanations/demonstrations of major software features</p></li>
<li><p>Listings of other major software that uses SymPy</p></li>
<li><p>Getting started info for users (download and install instructions)</p></li>
<li><p>Getting started info for developers</p></li>
<li><p>Where users can get help and support on using SymPy</p></li>
<li><p>News about SymPy</p></li>
</ul>
<p><strong>SymPy Documentation</strong> <a class="reference external" href="https://docs.sympy.org">https://docs.sympy.org</a></p>
<p>This is the main place where users go to learn how to use SymPy. It contains a
tutorial for SymPy as well as technical documentation for all of the modules.
The source files are hosted in the main SymPy repository in the <a class="reference external" href="https://github.com/sympy/sympy/tree/master/doc">doc directory</a> at and are built using the
<a class="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx site generator</a> and uploaded to
the docs.sympy.org site automatically. The docs website also contains a built-
in shell (SymPy Live) that allows users to interactively execute examples.
There are two primary types of pages that are generated from different source
files in the docs directory:</p>
<ul class="simple">
<li><p>Narrative Pages: reStructuredText files that correspond to manually written
documentation pages not present in the Python source code. Examples are the
<a class="reference external" href="https://github.com/sympy/sympy/tree/master/doc/src/tutorial">tutorial RST files</a>. In general,
if your documentation is not API documentation it belongs in a narrative page.</p></li>
<li><p>API Documentation Pages: reStructuredText files that contain directives that
generate the Application Programming Interface documentation. These are
automatically generated from the SymPy Python source code.</p></li>
</ul>
<p><strong>SymPy Source Code</strong> <a class="reference external" href="https://github.com/sympy/sympy">https://github.com/sympy/sympy</a></p>
<p>Most functions and classes have documentation written inside it in the form of a
docstring, which explains the function and includes examples called doctests.
The purpose of these docstrings are to explain the API of that class or
function. The doctests examples are tested as part of the test suite, so that we
know that they always produce the output that they say that they do. Here is an
<a class="reference external" href="https://github.com/sympy/sympy/blob/b176f6a1d9890b42dc361857c887992315e3d5ad/sympy/functions/elementary/complexes.py#L22-L47">example docstring</a>.
Most docstrings are also automatically included in the Sphinx documentation
above, so that they appear on the SymPy Documentation website. Here is that
<a class="reference internal" href="modules/functions/elementary.html#sympy.functions.elementary.complexes.im" title="sympy.functions.elementary.complexes.im"><code class="xref py py-obj docutils literal notranslate"><span class="pre">same</span> <span class="pre">docstring</span></code></a> on the SymPy website. The docstrings are formatted
in a specific way so that Sphinx can render them correctly for the docs
website. The SymPy sources all contain sparse technical documentation in the
form of source code comments, although this does not generally constitute
anything substantial and is not displayed on the documentation website.</p>
<p><strong>SymPy Wiki</strong> <a class="reference external" href="https://github.com/sympy/sympy/wiki">https://github.com/sympy/sympy/wiki</a></p>
<p>The SymPy Wiki can be edited by anyone without review. It contains various
types of documentation, including:</p>
<ul class="simple">
<li><p>High-level developer documentation (for example: <a class="reference external" href="https://github.com/sympy/sympy/wiki/Args-Invariant">https://github.com/sympy/sympy/wiki/Args-Invariant</a>)</p></li>
<li><p>Guides for new contributors (for example: <a class="reference external" href="https://github.com/sympy/sympy/wiki/Introduction-to-contributing">https://github.com/sympy/sympy/wiki/Introduction-to-contributing</a>)</p></li>
<li><p>Development policies (for example: <a class="reference external" href="https://github.com/sympy/sympy/wiki/Python-version-support-policy">https://github.com/sympy/sympy/wiki/Python-version-support-policy</a>)</p></li>
<li><p>Release notes (for example: <a class="reference external" href="https://github.com/sympy/sympy/wiki/Release-Notes-for-1.5">https://github.com/sympy/sympy/wiki/Release-Notes-for-1.5</a>)</p></li>
<li><p>Various pages that different contributors have added</p></li>
</ul>
</div>
<div class="section" id="getting-started">
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>The first step to contributing to the code base is creating your development
environment. Please find instructions on how to create your development
environment in our <a class="reference external" href="https://github.com/sympy/sympy/wiki/Development-workflow#create-your-environment">Development Workflow – Create Your Environment</a>
guide.</p>
<p>Once you have created your development environment, follow these steps:</p>
<div class="section" id="installation">
<h3>1. Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>
<p><strong>Debian/Ubuntu</strong></p>
<p>For Debian/Ubuntu, install the prerequisites:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">python3</span><span class="o">-</span><span class="n">sphinx</span> <span class="n">texlive</span><span class="o">-</span><span class="n">latex</span><span class="o">-</span><span class="n">recommended</span> <span class="n">dvipng</span> <span class="n">librsvg2</span><span class="o">-</span><span class="nb">bin</span> <span class="n">imagemagick</span> <span class="n">docbook2x</span> <span class="n">graphviz</span>
<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">sphinx</span><span class="o">-</span><span class="n">math</span><span class="o">-</span><span class="n">dollar</span>
</pre></div>
</div>
<p>And do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>If you get mpmath error, install python-mpmath package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">mpmath</span>
</pre></div>
</div>
<p>If you get matplotlib error, install python-matplotlib package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">matplotlib</span>
</pre></div>
</div>
<p>And to view it, do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">firefox</span> <span class="n">_build</span><span class="o">/</span><span class="n">html</span><span class="o">/</span><span class="n">index</span><span class="o">.</span><span class="n">html</span>
</pre></div>
</div>
<p><strong>Fedora</strong></p>
<p>For Fedora (and maybe other RPM-based distributions), install the
prerequisites:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dnf</span> <span class="n">install</span> <span class="n">python3</span><span class="o">-</span><span class="n">sphinx</span> <span class="n">librsvg2</span> <span class="n">ImageMagick</span> <span class="n">docbook2X</span> <span class="n">texlive</span><span class="o">-</span><span class="n">dvipng</span><span class="o">-</span><span class="nb">bin</span>
<span class="n">texlive</span><span class="o">-</span><span class="n">scheme</span><span class="o">-</span><span class="n">medium</span> <span class="n">librsvg2</span><span class="o">-</span><span class="n">tools</span>
<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">sphinx</span><span class="o">-</span><span class="n">math</span><span class="o">-</span><span class="n">dollar</span>
</pre></div>
</div>
<p>After that, run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>If you get mpmath error, install python3-mpmath package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dnf</span> <span class="n">install</span> <span class="n">python3</span><span class="o">-</span><span class="n">mpmath</span>
</pre></div>
</div>
<p>If you get matplotlib error, install python3-matplotlib package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dnf</span> <span class="n">install</span> <span class="n">python3</span><span class="o">-</span><span class="n">matplotlib</span>
</pre></div>
</div>
<p>And view it at:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">_build</span><span class="o">/</span><span class="n">html</span><span class="o">/</span><span class="n">index</span><span class="o">.</span><span class="n">html</span>
</pre></div>
</div>
<p><strong>Mac</strong></p>
<p>For Mac, first install homebrew: <a class="reference external" href="https://brew.sh/">https://brew.sh/</a></p>
<p>Then install these packages with homebrew:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">install</span> <span class="n">imagemagick</span> <span class="n">graphviz</span> <span class="n">docbook</span> <span class="n">librsvg</span>
</pre></div>
</div>
<p>Install these packages with either pip or conda:</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">pip</span> <span class="n">install</span> <span class="n">mpmath</span> <span class="n">matplotlib</span> <span class="n">sphinx</span> <span class="n">sphinx</span><span class="o">-</span><span class="n">math</span><span class="o">-</span><span class="n">dollar</span>
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">install</span> <span class="o">-</span><span class="n">c</span> <span class="n">conda</span><span class="o">-</span><span class="n">forge</span> <span class="n">mpmath</span> <span class="n">matplotlib</span> <span class="n">sphinx</span> <span class="n">sphinx</span><span class="o">-</span><span class="n">math</span><span class="o">-</span><span class="n">dollar</span>
</pre></div>
</div>
<p><strong>Windows 10</strong></p>
<p>Making your Sphinx build successful on the Windows system is tricky because
some dependencies like <code class="docutils literal notranslate"><span class="pre">dvipng</span></code> or <code class="docutils literal notranslate"><span class="pre">docbook2x</span></code> are not available.</p>
<p>For Windows 10, however, the Windows Subsystem for Linux can be a possible
workaround solution, and you can install Ubuntu shell on your Windows system
after following the tutorial below:</p>
<p><a class="reference external" href="https://github.com/MicrosoftDocs/WSL/blob/live/WSL/install-win10.md">https://github.com/MicrosoftDocs/WSL/blob/live/WSL/install-win10.md</a></p>
<p>In your command prompt, run <code class="docutils literal notranslate"><span class="pre">ubuntu</span></code> to transfer to Linux terminal, and
follow the Debian/Ubuntu tutorial above to install the dependencies, and then
you can run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> to build. (Note that you also have to install
<code class="docutils literal notranslate"><span class="pre">make</span></code> via <code class="docutils literal notranslate"><span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">make</span></code>.)</p>
<p>If you want to change the directory in your prompt to your working folder of
SymPy in the Windows file system, you can prepend <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">/mnt/</span></code> to your file
path in Windows, and run in your shell to navigate to the folder. (Also note
that Linux uses <code class="docutils literal notranslate"><span class="pre">/</span></code> instead of <code class="docutils literal notranslate"><span class="pre">\</span></code> for file paths.)</p>
<p>This method provides better compatibility than Cygwin or MSYS2 and more
convenience than a virtual machine if you partially need a Linux environment
for your workflow, however this method is only viable for Windows 10 64-bit
users.</p>
</div>
<div class="section" id="build-the-documentation">
<h3>2. Build the Documentation<a class="headerlink" href="#build-the-documentation" title="Permalink to this headline">¶</a></h3>
<p>The documentation can be built by running the <code class="docutils literal notranslate"><span class="pre">makefile</span></code> in the <code class="docutils literal notranslate"><span class="pre">doc</span></code>
subdirectory.</p>
<p>To start, in your preferred web browser, use the drop down menu and select
“open file” to navigate into the sympy/doc folder saved on your computer. In
the doc folder, select the _build folder, then the html folder, and in the html
folder, open the index.html file.</p>
<p>To build the HTML documentation, run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">doc</span>
<span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>This builds a local version of the documentation in <code class="docutils literal notranslate"><span class="pre">doc/_build/html</span></code> in your
web browser.</p>
<p>Open <code class="docutils literal notranslate"><span class="pre">_build/html/index.html</span></code>.</p>
</div>
<div class="section" id="make-a-contribution">
<h3>3. Make a Contribution<a class="headerlink" href="#make-a-contribution" title="Permalink to this headline">¶</a></h3>
<p>For in-depth instructions on how to contribute to SymPy’s code base including
coding conventions, creating your environment, picking an issue to fix, and
opening a pull request, please read our full <a class="reference external" href="https://github.com/sympy/sympy/wiki/Development-workflow">Development Workflow</a> guide.</p>
</div>
</div>
<div class="section" id="narrative-documentation-guidelines">
<h2>Narrative Documentation Guidelines<a class="headerlink" href="#narrative-documentation-guidelines" title="Permalink to this headline">¶</a></h2>
<p>Extensive documentation, or documentation that is not centered around an API
reference, should be written as a narrative document in the Sphinx docs (located
in the <a class="reference external" href="https://github.com/sympy/sympy/tree/master/doc/src">doc/src directory</a>). The narrative documents
do not reside in the Python source files, but as standalone restructured files
in the doc/src directory. SymPy’s narrative documentation is defined as the
collective documents, tutorials, and guides that teach users how to use SymPy.
Reference documentation should go in the docstrings and be pulled into the RST
with autodoc. The RST itself should only have narrative style documentation
that is not a reference for a single specific function.</p>
<div class="section" id="best-practices-for-writing-documentation">
<span id="style-guide-best-practices-for-writing-documentation"></span><h3>Best Practices for Writing Documentation<a class="headerlink" href="#best-practices-for-writing-documentation" title="Permalink to this headline">¶</a></h3>
<p>Please follow these formatting, style, and tone preferences when writing
documentation.</p>
<div class="section" id="formatting-preferences">
<h4>Formatting Preferences<a class="headerlink" href="#formatting-preferences" title="Permalink to this headline">¶</a></h4>
<p>In order for math and code to render correctly on the SymPy website, please
follow these formatting guidelines.</p>
<div class="section" id="math">
<span id="style-guide-math-formatting"></span><h5>Math<a class="headerlink" href="#math" title="Permalink to this headline">¶</a></h5>
<p>Text that is surrounded by dollar signs $ _ $ will be rendered as LaTeX math.
Any text that is meant to appear as LaTeX math should be written as <code class="docutils literal notranslate"><span class="pre">$math$</span></code>.
In the HTML version of the docs, MathJax will render the math.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>The Bessel $J$ function of order $\nu$ is defined to be the function
satisfying Bessel’s differential equation.
</pre></div>
</div>
</div>
<div class="section" id="latex-recommendations">
<h5>LaTeX Recommendations<a class="headerlink" href="#latex-recommendations" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li><p>If a docstring has any LaTeX, be sure to make it “raw.” See the
<a class="reference internal" href="#style-guide-docstring-formatting"><span class="std std-ref">Docstring Formatting</span></a> section for
details.</p></li>
<li><p>If you are not sure how to render something, you can use the SymPy
<a class="reference internal" href="modules/printing.html#sympy.printing.latex.latex" title="sympy.printing.latex.latex"><code class="xref py py-func docutils literal notranslate"><span class="pre">latex()</span></code></a> function. But be sure to strip out the unimportant parts (the
bullet points below).</p></li>
<li><p>Avoid unnecessary <code class="docutils literal notranslate"><span class="pre">\left</span></code> and <code class="docutils literal notranslate"><span class="pre">\right</span></code> (but be sure to use them when they
are required).</p></li>
<li><p>Avoid unnecessary <code class="docutils literal notranslate"><span class="pre">{}</span></code>. (For example, write <code class="docutils literal notranslate"><span class="pre">x^2</span></code> instead of <code class="docutils literal notranslate"><span class="pre">x^{2}</span></code>.)</p></li>
<li><p>Use whitespace in a way that makes the equation easiest to read.</p></li>
<li><p>Always check the final rendering to make sure it looks the way you expect it
to.</p></li>
</ul>
<p><strong>Examples</strong></p>
<p>Correct:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>\<span class="nb">int</span> \<span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>\<span class="p">,</span><span class="n">dx</span>
</pre></div>
</div>
<p>Incorrect:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>\<span class="nb">int</span> \<span class="n">sin</span><span class="p">{</span>\<span class="n">left</span><span class="p">(</span> <span class="n">x</span>\<span class="n">right</span><span class="p">)}</span>\<span class="p">,</span> <span class="n">dx</span>
</pre></div>
</div>
<p>For more in-depth resources on how to write math in LaTeX, see:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference">https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference</a></p></li>
<li><p><a class="reference external" href="https://en.wikibooks.org/wiki/LaTeX/Mathematics">https://en.wikibooks.org/wiki/LaTeX/Mathematics</a></p></li>
<li><p><a class="reference external" href="https://www.overleaf.com/learn/latex/Mathematical_expressions">https://www.overleaf.com/learn/latex/Mathematical_expressions</a></p></li>
</ul>
</div>
<div class="section" id="code">
<h5>Code<a class="headerlink" href="#code" title="Permalink to this headline">¶</a></h5>
<p>Text that should be printed verbatim, such as code, should be surrounded by a
set of double backticks <code class="docutils literal notranslate"><span class="pre">like</span> <span class="pre">this</span></code>.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>To use this class, define the ``_rewrite()`` and ``_expand()`` methods.
</pre></div>
</div>
<p>Sometimes a variable will be the same in both math and code, and can even
appear in the same paragraph, making it difficult to know if it should be
formatted as math or code. If the sentence in question is discussing
mathematics, then LaTeX should be used, but if the sentence is discussing the
SymPy implementation specifically, then code should be used.</p>
<p>In general, the rule of thumb is to consider if the variable in question were
something that rendered differently in code and in math. For example, the Greek
letter α would be written as <code class="docutils literal notranslate"><span class="pre">alpha</span></code> in code and <code class="docutils literal notranslate"><span class="pre">$\alpha$</span></code> in LaTeX. The
reason being that <code class="docutils literal notranslate"><span class="pre">$\alpha$</span></code> cannot be used in contexts referring to Python
code because it is not valid Python, and conversely <code class="docutils literal notranslate"><span class="pre">alpha</span></code> would be
incorrect in a math context because it does not render as the Greek letter (α).</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">loggamma</span><span class="p">(</span><span class="n">Function</span><span class="p">):</span>
<span class="sa">r</span><span class="sd">"""</span>
<span class="sd"> The ``loggamma`` function implements the logarithm of the gamma</span>
<span class="sd"> function (i.e, $\log\Gamma(x)$).</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Variables listed in the parameters after the function name should, in written
text, be italicized using Sphinx emphasis with asterisks like <code class="docutils literal notranslate"><span class="pre">*this*</span></code>.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">stirling</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">k</span><span class="p">,</span> <span class="n">d</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">kind</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">signed</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> ...</span>
<span class="sd"> The first kind of Stirling number counts the number of permutations of</span>
<span class="sd"> *n* distinct items that have *k* cycles; the second kind counts the</span>
<span class="sd"> ways in which *n* distinct items can be partitioned into *k* parts.</span>
<span class="sd"> If *d* is given, the "reduced Stirling number of the second kind" is</span>
<span class="sd"> returned: $S^{d}(n, k) = S(n - d + 1, k - d + 1)$ with $n \ge k \ge d$.</span>
<span class="sd"> This counts the ways to partition $n$ consecutive integers into $k$</span>
<span class="sd"> groups with no pairwise difference less than $d$.</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Note that in the above example, the first instances of <em>n</em> and <em>k</em> are
referring to the input parameters of the function <code class="docutils literal notranslate"><span class="pre">stirling</span></code>. Because they
are Python variables but also parameters listed by themselves, they are
formatted as parameters in italics. The last instances of <span class="math notranslate nohighlight">\(n\)</span> and <span class="math notranslate nohighlight">\(k\)</span> are
talking about mathematical expressions, so they are formatted as math.</p>
<p>If a variable is code, but is also a parameter written by itself, the parameter
formatting takes precedence and it should be rendered in italics. However, if a
parameter appears in a larger code expression it should be within double
backticks to be rendered as code. If a variable is only code and not a
parameter as well, it should be in double backticks to be rendered as code.</p>
<p>Please note that references to other functions in SymPy are handled differently
from parameters or code. If something is referencing another function in SymPy,
the cross-reference reStructuredText syntax should be used. See the section on
<a class="reference internal" href="#style-guide-cross-referencing"><span class="std std-ref">Cross-Referencing</span></a> for more information.</p>
</div>
<div class="section" id="headings">
<h5>Headings<a class="headerlink" href="#headings" title="Permalink to this headline">¶</a></h5>
<p>Section headings in reStructuredText files are created by underlining (and
optionally overlining) the section title with a punctuation character at least
as long as the text.</p>
<p>Normally, there are no heading levels assigned to certain characters as the
structure is determined from the succession of headings. However, for SymPy’s
documentation, here is a suggested convention:</p>
<p><code class="docutils literal notranslate"><span class="pre">===</span></code> with overline: title (top level heading)</p>
<p><code class="docutils literal notranslate"><span class="pre">===</span></code> heading 1</p>
<p><code class="docutils literal notranslate"><span class="pre">---</span></code> heading 2</p>
<p><code class="docutils literal notranslate"><span class="pre">^^^</span></code> heading 3</p>
<p><code class="docutils literal notranslate"><span class="pre">~~~</span></code> heading 4</p>
<p><code class="docutils literal notranslate"><span class="pre">"""</span></code> heading 5</p>
</div>
</div>
<div class="section" id="style-preferences">
<h4>Style Preferences<a class="headerlink" href="#style-preferences" title="Permalink to this headline">¶</a></h4>
<div class="section" id="spelling-and-punctuation">
<h5>Spelling and Punctuation<a class="headerlink" href="#spelling-and-punctuation" title="Permalink to this headline">¶</a></h5>
<p>All narrative writing in SymPy follows American spelling and punctuation
standards. For example, “color” is preferred over “colour” and commas should be
placed inside of quotation marks.</p>
<p><strong>Examples</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>If the ``line_color`` aesthetic is a function of arity 1, then the coloring
is a function of the x value of a point.
The term "unrestricted necklace," or "bracelet," is used to imply an object
that can be turned over or a sequence that can be reversed.
</pre></div>
</div>
<p>If there is any ambiguity about the spelling of a word, such as in the case of
a function named after a person, refer to the spelling of the actual SymPy
function.</p>
<p>For example, Chebyshev polynomials are named after Pafnuty Lvovich Tchebychev,
whose name is sometimes transliterated from Russian to be spelled with a “T,”
but in SymPy it should always be spelled “Chebyshev” to refer to the SymPy
function.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">chebyshevt</span><span class="p">(</span><span class="n">OrthogonalPolynomial</span><span class="p">):</span>
<span class="sa">r</span><span class="sd">"""</span>
<span class="sd"> Chebyshev polynomial of the first kind, $T_n(x)$</span>
<span class="sd"> ...</span>
<span class="sd"> """</span>
</pre></div>
</div>
</div>
<div class="section" id="capitalization">
<h5>Capitalization<a class="headerlink" href="#capitalization" title="Permalink to this headline">¶</a></h5>
<p>Title case capitalization is preferred in all SymPy headings.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>What is Symbolic Computation?
-----------------------------
</pre></div>
</div>
</div>
</div>
<div class="section" id="tone-preferences">
<h4>Tone Preferences<a class="headerlink" href="#tone-preferences" title="Permalink to this headline">¶</a></h4>
<p>Across SymPy documentation, please write in:</p>
<ul class="simple">
<li><p>The present tense (e.g., In the following section, we are going to learn…)</p></li>
<li><p>The first-person inclusive plural (e.g., We did this the long way, but now we
can try it the short way…)</p></li>
<li><p>Use the generic pronoun “you” instead of “one.” Or use “the reader” or “the
user.” (e.g., You can access this function by… The user can then access
this function by…)</p></li>
<li><p>Use the gender-neutral pronoun “they” instead of “he” or “she.” (e.g., A good
docstring tells the user exactly what they need to know.)</p></li>
</ul>
<p>Avoid extraneous or belittling words such as “obviously,” “easily,” “simply,”
“just,” or “straightforward.”</p>
<p>Avoid unwelcoming or judgement-based phrases like “That is wrong.” Instead use
friendly and inclusive language like “A common mistake is…”</p>
<p>Avoid extraneous phrases like, “we just have to do one more thing.”</p>
</div>
</div>
</div>
<div class="section" id="docstring-guidelines">
<span id="style-guide-docstring-guidelines"></span><h2>Docstring Guidelines<a class="headerlink" href="#docstring-guidelines" title="Permalink to this headline">¶</a></h2>
<p>To contribute to SymPy’s docstrings, please read these guidelines in full.</p>
<p>A documentation string (docstring) is a string literal that occurs as the first
statement in a module, function, class, or method definition. Such a docstring
becomes the <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> special attribute of that object.</p>
<p><strong>Example</strong></p>
<p>Here is a basic docstring:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">fdiff</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">argindex</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Returns the first derivative of a Heaviside Function.</span>
<span class="sd"> Examples</span>
<span class="sd"> ========</span>
<span class="sd"> >>> from sympy import Heaviside, diff</span>
<span class="sd"> >>> from sympy.abc import x</span>
<span class="sd"> >>> Heaviside(x).fdiff()</span>
<span class="sd"> DiracDelta(x)</span>
<span class="sd"> >>> Heaviside(x**2 - 1).fdiff()</span>
<span class="sd"> DiracDelta(x**2 - 1)</span>
<span class="sd"> >>> diff(Heaviside(x)).fdiff()</span>
<span class="sd"> DiracDelta(x, 1)</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Every public function, class, method, and module should have a docstring that
describes what it does. Documentation that is specific to a function or class
in the module should be in the docstring of that function or class. The module
level docstring should discuss the purpose and scope of the module, and give a
high-level example of how to use the functions or classes in the module. A
module docstring is the docstring at the very top of the file, for example, the
docstring for <a class="reference external" href="https://github.com/sympy/sympy/blob/85e684f782c71d247b13af71f2f134a9d894507e/sympy/solvers/ode.py">solvers.ode</a>.</p>
<p>A public function is one that is intended to be used by the end-
user, or the public. Documentation is important for public functions because
they will be seen and used by many people.</p>
<p>A private function, on the other hand, is one that is only intended to be used
in the code in SymPy itself. Although it is less important to document private
functions, it also helps to have docstrings on private functions to help other
SymPy developers understand how to use the function.</p>
<p>It may not always be clear what is a public function and what is a private
function. If a function begins with an underscore, it is private, and if a
function is included in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> it is public, but the converse is not
always true, so sometimes you have to decide based on context. In general, if
you are unsure, having documentation on a function is better than not having
documentation, regardless if it is public or private.</p>
<p>Docstrings should contain information aimed at users of the function. Comments
specific to the code or other notes that would only distract users should go in
comments in the code, not in docstrings.</p>
<p>Every docstring should have examples that show how the function works. Examples
are the most important part of a docstring. A single example showing input and
output to a function can be more helpful than a paragraph of descriptive text.</p>
<p>Remember that the primary consumers of docstrings are other human beings, not
machines, so it is important to describe what the function does in plain
English. Likewise, examples of how to use the function should be designed for
human readers, not just for the doctest machinery.</p>
<p>Keep in mind that while Sphinx is the primary way users consume docstrings, and
therefore the first platform to keep in mind while writing docstrings
(especially for public functions), it is not the only way users consume
docstrings. You can also view docstrings using <code class="docutils literal notranslate"><span class="pre">help()</span></code> or <code class="docutils literal notranslate"><span class="pre">?</span></code> in IPython.
When using <code class="docutils literal notranslate"><span class="pre">help()</span></code>, for instance, it will show you all of the docstrings on
private methods. Additionally, anyone reading the source code directly will see
every docstring.</p>
<p>All public functions, classes, and methods and their corresponding docstrings
should be imported into the Sphinx docs, instructions on which can be found at
the end of this guide.</p>
<div class="section" id="docstring-formatting">
<span id="style-guide-docstring-formatting"></span><h3>Docstring Formatting<a class="headerlink" href="#docstring-formatting" title="Permalink to this headline">¶</a></h3>
<p>Docstrings are are written in <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> format extended by <a class="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx</a>. Here is a concise guide to <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">Quick
reStructuredText</a>. More in-depth
information about using reStructuredText can be found in the <a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">Sphinx
Documentation</a>.</p>
<p>In order for Sphinx to render docstrings nicely in the HTML documentation, some
formatting guidelines should be followed when writing docstrings:</p>
<ul class="simple">
<li><p>Always use “””triple double quotes””” around docstrings. Use r”””raw triple
double quotes””” if you use any backslashes in your docstrings.</p></li>
<li><p>Include a blank line before the docstring’s closing quotes.</p></li>
<li><p>Lines should not be longer than 80 characters.</p></li>
<li><p>Always write class-level docstrings under the class definition line, as that
is better to read in the source code.</p></li>
<li><p>The various methods on the class can be mentioned in the docstring or
examples if they are important, but details on them should go in the
docstring for the method itself.</p></li>
<li><p>Be aware that :: creates code blocks, which are rarely used in the
docstrings. Any code example with example Python should be put in a doctest.
Always check that the final version as rendered by Sphinx looks correct in
the HTML.</p></li>
<li><p>In order to make section underlining work nicely in docstrings, <a class="reference external" href="https://pypi.org/project/numpydoc/">numpydoc
Sphinx extension</a> is used.</p></li>
<li><p>Always double check that you have formatted your docstring correctly:</p></li>
</ul>
<ol class="arabic simple">
<li><p>Make sure that your docstring is imported into Sphinx.</p></li>
<li><p>Build the Sphinx docs (<code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">doc;</span> <span class="pre">make</span> <span class="pre">html</span></code>).</p></li>
<li><p>Make sure that Sphinx doesn’t output any errors.</p></li>
<li><p>Open the page in <code class="docutils literal notranslate"><span class="pre">_build/html</span></code> and make sure that it is formatted
correctly.</p></li>
</ol>
</div>
<div class="section" id="docstring-sections">
<h3>Docstring Sections<a class="headerlink" href="#docstring-sections" title="Permalink to this headline">¶</a></h3>
<p>In SymPy’s docstrings, it is preferred that function, class, and method
docstrings consist of the following sections in this order:</p>
<ol class="arabic simple">
<li><p>Single-Sentence Summary</p></li>
<li><p>Explanation</p></li>
<li><p>Examples</p></li>
<li><p>Parameters</p></li>
<li><p>See Also</p></li>
<li><p>References</p></li>
</ol>
<p>The Single-Sentence Summary and Examples sections are <strong>required</strong> for every
docstring. Docstrings will not pass review if these sections are not included.</p>
<p>Do not change the names of these supported sections, for example, the heading
“Examples” as a plural should be used even if there is only one example.</p>
<p>SymPy will continue to support all of the section headings listed in the <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">NumPy
Docstring Guide</a>.</p>
<p>Headings should be underlined with the same length in equals signs.</p>
<p>If a section is not required and that information for the function in question
is unnecessary, do not use it. Unnecessary sections and cluttered docstrings
can make a function harder to understand. Aim for the minimal amount of
information required to understand the function.</p>
</div>
<div class="section" id="single-sentence-summary">
<h3>1. Single-Sentence Summary<a class="headerlink" href="#single-sentence-summary" title="Permalink to this headline">¶</a></h3>
<p>This section is <strong>required</strong> for every docstring. A docstring will not pass
review if it is not included. No heading is necessary for this section.</p>
<p>This section consists of a one-line sentence ending in a period that describes
the function, class, or method’s effect.</p>
<p>Deprecation warnings should go directly after the Single-Sentence Summary, so
as to notify users right away. Deprecation warnings should be written as a note
in the Sphinx directive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">note</span><span class="p">::</span> <span class="n">Deprecated</span> <span class="ow">in</span> <span class="n">Sympy</span> <span class="mf">0.7</span><span class="o">.</span><span class="mf">1.</span>
</pre></div>
</div>
</div>
<div class="section" id="explanation-section">
<h3>2. Explanation Section<a class="headerlink" href="#explanation-section" title="Permalink to this headline">¶</a></h3>
<p>This section is encouraged. If you choose to include an Explanation section in
your docstring, it should be labeled with the heading “Explanation” underlined
with the same length in equals signs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Explanation</span>
<span class="o">===========</span>
</pre></div>
</div>
<p>This section consists of a more elaborate description of what the function,
class, or method does when the concise Single-Sentence Summary will not
suffice. This section should be used to clarify functionality in several
sentences or paragraphs.</p>
</div>
<div class="section" id="examples-section">
<h3>3. Examples Section<a class="headerlink" href="#examples-section" title="Permalink to this headline">¶</a></h3>
<p>This section is <strong>required</strong> for every docstring. A docstring will not pass
review if it is not included. It should be labeled with the heading “Examples”
(even if there is only one example) underlined with the same length in equals
signs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Examples</span>
<span class="o">========</span>
</pre></div>
</div>
<p>This section consists of examples that show how the function works, called
doctests. Doctests should be complicated enough that they fully demonstrate the
API and functionality of the function, but simple enough that a user can
understand them without too much thought. The perfect doctest tells the user
exactly what they need to know about the function without reading any other
part of the docstring.</p>
<p>There should always be a blank line before the doctest. When multiple examples
are provided, they should be separated by blank lines. Comments explaining the
examples should have blank lines both above and below them.</p>
<p>Do not think of doctests as tests. Think of them as examples that happen to be
tested. They should demonstrate the API of the function to the user (i.e., what
the input parameters look like, what the output looks like, and what it does).
If you only want to test something, add a test to the relevant <code class="docutils literal notranslate"><span class="pre">test_*.py</span> <span class="pre">file</span></code>.</p>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">./bin/coverage_doctest.py</span></code> script to test the doctest
coverage of a file or module. Run the doctests with <code class="docutils literal notranslate"><span class="pre">./bin/doctest</span></code>.</p>
<p>You should only skip the testing of an example if it is impossible to test it.
If necessary, testing of an example can be skipped by adding a special comment.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">random</span>
<span class="gp">>>> </span><span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span>
<span class="go">0.6868680200532414</span>
</pre></div>
</div>
<p>If an example is longer than 80 characters, it should be line wrapped. Examples
should be line wrapped so that they are still valid Python code, using <code class="docutils literal notranslate"><span class="pre">...</span></code>
continuation as in a Python prompt. For example, from the ODE module
documentation:</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sympy</span> <span class="kn">import</span> <span class="n">Function</span><span class="p">,</span> <span class="n">dsolve</span><span class="p">,</span> <span class="n">cos</span><span class="p">,</span> <span class="n">sin</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sympy.abc</span> <span class="kn">import</span> <span class="n">x</span>
<span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">Function</span><span class="p">(</span><span class="s1">'f'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">dsolve</span><span class="p">(</span><span class="n">cos</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">))</span> <span class="o">-</span> <span class="p">(</span><span class="n">x</span><span class="o">*</span><span class="n">sin</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">))</span> <span class="o">-</span> <span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">**</span><span class="mi">2</span><span class="p">)</span><span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="n">x</span><span class="p">),</span>
<span class="gp">... </span><span class="n">f</span><span class="p">(</span><span class="n">x</span><span class="p">),</span> <span class="n">hint</span><span class="o">=</span><span class="s1">'1st_exact'</span><span class="p">)</span>
<span class="go">Eq(x*cos(f(x)) + f(x)**3/3, C1)</span>
</pre></div>
</div>
<p>Here <code class="docutils literal notranslate"><span class="pre">dsolve(cos(f(x))</span> <span class="pre">-</span> <span class="pre">(x*sin(f(x))</span> <span class="pre">-</span> <span class="pre">f(x)**2)*f(x).diff(x),</span> <span class="pre">f(x),</span> <span class="pre">hint='1st_exact')</span></code> is too long, so we line break it after a comma so that it
is readable, and put <code class="docutils literal notranslate"><span class="pre">...</span></code> on the continuation lines. If this is not done
correctly, the doctests will fail.</p>
<p>The output of a command can also be line wrapped. No <code class="docutils literal notranslate"><span class="pre">...</span></code> should be used in
this case. The doctester automatically accepts output that is line wrapped.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">30</span><span class="p">))</span>
<span class="go">[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,</span>
<span class="go">21, 22, 23, 24, 25, 26, 27, 28, 29]</span>
</pre></div>
</div>
<p>In a doctest, write imports like <code class="docutils literal notranslate"><span class="pre">sympy</span> <span class="pre">import</span> <span class="pre">...</span></code> instead of <code class="docutils literal notranslate"><span class="pre">import</span>
<span class="pre">sympy</span></code> or <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sympy</span> <span class="pre">import</span> <span class="pre">*</span></code>. To define symbols, use <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sympy.abc</span>
<span class="pre">import</span> <span class="pre">x</span></code>, unless the name is not in <code class="docutils literal notranslate"><span class="pre">sympy.abc</span></code> (for instance, if it has
assumptions), in which case use <code class="docutils literal notranslate"><span class="pre">symbols</span></code> like <code class="docutils literal notranslate"><span class="pre">x,</span> <span class="pre">y</span> <span class="pre">=</span> <span class="pre">symbols('x</span> <span class="pre">y')</span></code>.</p>
<p>In general, you should run <code class="docutils literal notranslate"><span class="pre">./bin/doctest</span></code> to make sure your examples run
correctly, and fix them if they do not.</p>
</div>
<div class="section" id="parameters-section">
<h3>4. Parameters Section<a class="headerlink" href="#parameters-section" title="Permalink to this headline">¶</a></h3>
<p>This section is encouraged. If you choose to include a Parameters section in
your docstring, it should be labeled with the heading “Parameters” underlined
with the same length in equals signs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Parameters</span>
<span class="o">==========</span>
</pre></div>
</div>
<p>If you have parameters listed in parentheses after a function, class, or method
name, you must include a parameters section.</p>
<p>This section consists of descriptions of the function arguments, keywords, and
their respective types.</p>
<p>Enclose variables in double backticks. The colon must be preceded by a space,
or omitted if the type is absent. For the parameter types, be as precise as
possible. If it is not necessary to specify a keyword argument, use
<code class="docutils literal notranslate"><span class="pre">optional</span></code>. Optional keyword parameters have default values, which are
displayed as part of the function signature. They can also be detailed in the
description.</p>
<p>When a parameter can only assume one of a fixed set of values, those values can
be listed in braces, with the default appearing first. When two or more input
parameters have exactly the same type, shape, and description, they can be
combined.</p>
<p>If the Parameters section is not formatted correctly, the documentation build
will render incorrectly.</p>
<p>If you wish to include a Returns section, write it as its own section with its
own heading.</p>
<p><strong>Example</strong></p>
<p>Here is an example of a correctly formatted Parameters section:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">opt_cse</span><span class="p">(</span><span class="n">exprs</span><span class="p">,</span> <span class="n">order</span><span class="o">=</span><span class="s1">'canonical'</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Find optimization opportunities in Adds, Muls, Pows and negative</span>
<span class="sd"> coefficient Muls.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ==========</span>
<span class="sd"> exprs : list of sympy expressions</span>
<span class="sd"> The expressions to optimize.</span>
<span class="sd"> order : string, 'none' or 'canonical'</span>
<span class="sd"> The order by which Mul and Add arguments are processed. For large</span>
<span class="sd"> expressions where speed is a concern, use the setting order='none'.</span>
<span class="sd"> """</span>
</pre></div>
</div>
</div>
<div class="section" id="see-also-section">
<span id="style-guide-see-also"></span><h3>5. See Also Section<a class="headerlink" href="#see-also-section" title="Permalink to this headline">¶</a></h3>
<p>This section is encouraged. If you choose to include a See Also section in your
docstring, it should be labeled with the heading “See Also” underlined with the
same length in equals signs.</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>
</pre></div>
</div>
<p>This section consists of a listing of related functions, classes, and methods.
The related items can be described with a concise fragment (not a full
sentence) if desired, but this is not required. If the description spans more
than one line, subsequent lines must be indented.</p>
<p>The See Also section should only be used to reference other SymPy objects.
Anything that is a link should be embedded as a hyperlink in the text of the
docstring instead; see the References section for details.</p>
<p>Do not reference classes with <code class="docutils literal notranslate"><span class="pre">class:Classname</span></code>, <code class="docutils literal notranslate"><span class="pre">class:`Classname`</span></code>, or
<code class="docutils literal notranslate"><span class="pre">:class:`Classname`</span></code>, but rather only by their class name.</p>
<p><strong>Examples</strong></p>
<p>Here is a correctly formatted See Also section with concise descriptions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">erf</span><span class="p">(</span><span class="n">Function</span><span class="p">):</span>
<span class="sa">r</span><span class="sd">"""</span>
<span class="sd"> The Gauss error function.</span>
<span class="sd"> See Also</span>
<span class="sd"> ========</span>
<span class="sd"> erfc: Complementary error function.</span>
<span class="sd"> erfi: Imaginary error function.</span>
<span class="sd"> erf2: Two-argument error function.</span>
<span class="sd"> erfinv: Inverse error function.</span>
<span class="sd"> erfcinv: Inverse Complementary error function.</span>
<span class="sd"> erf2inv: Inverse two-argument error function.</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Here is a correctly formatted See Also section with just a list of names:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">besselj</span><span class="p">(</span><span class="n">BesselBase</span><span class="p">):</span>
<span class="sa">r</span><span class="sd">"""</span>
<span class="sd"> Bessel function of the first kind.</span>
<span class="sd"> See Also</span>
<span class="sd"> ========</span>
<span class="sd"> bessely, besseli, besselk</span>
<span class="sd"> """</span>
</pre></div>
</div>
</div>
<div class="section" id="references-section">
<h3>6. References Section<a class="headerlink" href="#references-section" title="Permalink to this headline">¶</a></h3>
<p>This section is encouraged. If you choose to include a References section in
your docstring, it should be labeled with the heading “References” underlined
with the same length in equals signs.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">References</span>
<span class="o">==========</span>
</pre></div>
</div>
<p>This section consists of a list of references cited anywhere in the previous
sections. Any reference to other SymPy objects should go in the See Also
section instead.</p>
<p>The References section should include online resources, paper citations, and/or
any other printed resource giving general information about the function.
References are meant to augment the docstring, but should not be required to
understand it. References are numbered, starting from one, in the order in
which they are cited.</p>
<p>For online resources, only link to freely accessible and stable online
resources such as Wikipedia, Wolfram MathWorld, and the NIST Digital Library of
Mathematical Functions (DLMF), which are unlikely to suffer from hyperlink rot.</p>
<p>References for papers should include, in this order: reference citation, author
name, title of work, journal or publication, year published, page number.</p>
<p>If there is a DOI (Digital Object Identifier), include it in the citation and
make sure it is a clickable hyperlink.</p>
<p><strong>Examples</strong></p>
<p>Here is a References section that cites a printed resource:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">References</span>
<span class="o">==========</span>
<span class="o">..</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="p">[</span><span class="n">Kozen89</span><span class="p">]</span> <span class="n">D</span><span class="o">.</span> <span class="n">Kozen</span><span class="p">,</span> <span class="n">S</span><span class="o">.</span> <span class="n">Landau</span><span class="p">,</span> <span class="n">Polynomial</span> <span class="n">Decomposition</span> <span class="n">Algorithms</span><span class="p">,</span>
<span class="n">Journal</span> <span class="n">of</span> <span class="n">Symbolic</span> <span class="n">Computation</span> <span class="mi">7</span> <span class="p">(</span><span class="mi">1989</span><span class="p">),</span> <span class="n">pp</span><span class="o">.</span> <span class="mi">445</span><span class="o">-</span><span class="mi">456</span>
</pre></div>
</div>
<p>Here is a References section that cites printed and online resources:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">References</span>
<span class="o">==========</span>
<span class="o">..</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="n">Abramowitz</span><span class="p">,</span> <span class="n">Milton</span><span class="p">;</span> <span class="n">Stegun</span><span class="p">,</span> <span class="n">Irene</span> <span class="n">A</span><span class="o">.</span><span class="p">,</span> <span class="s2">"Chapter 9,"</span> <span class="n">Handbook</span> <span class="n">of</span>
<span class="n">Mathematical</span> <span class="n">Functions</span> <span class="k">with</span> <span class="n">Formulas</span><span class="p">,</span> <span class="n">Graphs</span><span class="p">,</span> <span class="ow">and</span> <span class="n">Mathematical</span>
<span class="n">Tables</span><span class="p">,</span> <span class="n">eds</span><span class="o">.</span> <span class="p">(</span><span class="mi">1965</span><span class="p">)</span>
<span class="o">..</span> <span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="n">Luke</span><span class="p">,</span> <span class="n">Y</span><span class="o">.</span> <span class="n">L</span><span class="o">.</span><span class="p">,</span> <span class="n">The</span> <span class="n">Special</span> <span class="n">Functions</span> <span class="ow">and</span> <span class="n">Their</span> <span class="n">Approximations</span><span class="p">,</span>
<span class="n">Volume</span> <span class="mi">1</span><span class="p">,</span> <span class="p">(</span><span class="mi">1969</span><span class="p">)</span>
<span class="o">..</span> <span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">en</span><span class="o">.</span><span class="n">wikipedia</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">wiki</span><span class="o">/</span><span class="n">Bessel_function</span>
<span class="o">..</span> <span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">functions</span><span class="o">.</span><span class="n">wolfram</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">Bessel</span><span class="o">-</span><span class="n">TypeFunctions</span><span class="o">/</span><span class="n">BesselJ</span><span class="o">/</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="sample-docstring">
<h2>Sample Docstring<a class="headerlink" href="#sample-docstring" title="Permalink to this headline">¶</a></h2>
<p>Here is an example of a correctly formatted docstring:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">gamma</span><span class="p">(</span><span class="n">Function</span><span class="p">):</span>
<span class="sa">r</span><span class="sd">"""</span>
<span class="sd"> The gamma function</span>
<span class="sd"> .. math::</span>
<span class="sd"> \Gamma(x) := \int^{\infty}_{0} t^{x-1} e^{-t} \mathrm{d}t.</span>
<span class="sd"> Explanation</span>
<span class="sd"> ===========</span>
<span class="sd"> The ``gamma`` function implements the function which passes through the</span>
<span class="sd"> values of the factorial function (i.e., $\Gamma(n) = (n - 1)!$), when n</span>
<span class="sd"> is an integer. More generally, $\Gamma(z)$ is defined in the whole</span>
<span class="sd"> complex plane except at the negative integers where there are simple</span>
<span class="sd"> poles.</span>
<span class="sd"> Examples</span>
<span class="sd"> ========</span>
<span class="sd"> >>> from sympy import S, I, pi, oo, gamma</span>
<span class="sd"> >>> from sympy.abc import x</span>
<span class="sd"> Several special values are known:</span>
<span class="sd"> >>> gamma(1)</span>
<span class="sd"> 1</span>
<span class="sd"> >>> gamma(4)</span>
<span class="sd"> 6</span>
<span class="sd"> >>> gamma(S(3)/2)</span>
<span class="sd"> sqrt(pi)/2</span>
<span class="sd"> The ``gamma`` function obeys the mirror symmetry:</span>
<span class="sd"> >>> from sympy import conjugate</span>
<span class="sd"> >>> conjugate(gamma(x))</span>
<span class="sd"> gamma(conjugate(x))</span>
<span class="sd"> Differentiation with respect to $x$ is supported:</span>
<span class="sd"> >>> from sympy import diff</span>
<span class="sd"> >>> diff(gamma(x), x)</span>
<span class="sd"> gamma(x)*polygamma(0, x)</span>
<span class="sd"> Series expansion is also supported:</span>
<span class="sd"> >>> from sympy import series</span>
<span class="sd"> >>> series(gamma(x), x, 0, 3)</span>
<span class="sd"> 1/x - EulerGamma + x*(EulerGamma**2/2 + pi**2/12) + x**2*(-EulerGamma*pi**2/12 +</span>
<span class="sd"> polygamma(2, 1)/6 - EulerGamma**3/6) + O(x**3)</span>
<span class="sd"> We can numerically evaluate the ``gamma`` function to arbitrary</span>
<span class="sd"> precision on the whole complex plane:</span>
<span class="sd"> >>> gamma(pi).evalf(40)</span>
<span class="sd"> 2.288037795340032417959588909060233922890</span>
<span class="sd"> >>> gamma(1+I).evalf(20)</span>
<span class="sd"> 0.49801566811835604271 - 0.15494982830181068512*I</span>
<span class="sd"> See Also</span>
<span class="sd"> ========</span>
<span class="sd"> lowergamma: Lower incomplete gamma function.</span>
<span class="sd"> uppergamma: Upper incomplete gamma function.</span>
<span class="sd"> polygamma: Polygamma function.</span>
<span class="sd"> loggamma: Log Gamma function.</span>
<span class="sd"> digamma: Digamma function.</span>
<span class="sd"> trigamma: Trigamma function.</span>
<span class="sd"> beta: Euler Beta function.</span>
<span class="sd"> References</span>
<span class="sd"> ==========</span>
<span class="sd"> .. [1] https://en.wikipedia.org/wiki/Gamma_function</span>
<span class="sd"> .. [2] http://dlmf.nist.gov/5</span>
<span class="sd"> .. [3] http://mathworld.wolfram.com/GammaFunction.html</span>
<span class="sd"> .. [4] http://functions.wolfram.com/GammaBetaErf/Gamma/</span>
<span class="sd"> """</span>
</pre></div>
</div>
</div>
<div class="section" id="docstrings-for-classes-that-are-mathematical-functions">
<h2>Docstrings for Classes that are Mathematical Functions<a class="headerlink" href="#docstrings-for-classes-that-are-mathematical-functions" title="Permalink to this headline">¶</a></h2>
<p>SymPy is unusual in that it also has classes that are mathematical functions.
The docstrings for classes that are mathematical functions should include
details specific to this kind of class, as noted below:</p>
<ul class="simple">
<li><p>The Explanation section should include a mathematical definition of the
function. This should use LaTeX math. Use $$ for <a class="reference internal" href="#style-guide-math-formatting"><span class="std std-ref">inline math</span></a> and .. math:: for display math, which should be
used for the main definition. The variable names in the formulas should match
the names of the parameters, and the LaTeX formatting should match the LaTeX
pretty printing used by SymPy. As relevant, the mathematical definitions
should mention their domain of definition, especially if the domain is
different from the complex numbers.</p></li>
<li><p>If there are multiple conventions in the literature for a function, make sure
to clearly specify which convention SymPy uses.</p></li>
<li><p>The Explanation section may also include some important mathematical facts
about the function. These can alternately be demonstrated in the Examples
section. Mathematical discussions should not be too long, as users can check
the references for more details.</p></li>
<li><p>The docstring does not need to discuss every implementation detail such as at
which operations are defined on the function or at which points it evaluates
in the “eval” method. Important or illuminating instances of these can be
shown in the Examples section.</p></li>
<li><p>The docstring should go on the class level (right under the line that has
“class”). The “eval” method should not have a docstring.</p></li>
<li><p>Private methods on the class, that is, any method that starts with an
underscore, do not need to be documented. They can still be documented if you
like, but note that these docstrings are not pulled into the Sphinx
documentation, so they will only be seen by developers who are reading the
code, so if there is anything very important that you want to mention here,
it should go in the class-level docstring as well.</p></li>
</ul>
</div>