-
Notifications
You must be signed in to change notification settings - Fork 0
/
chapter2.html
231 lines (217 loc) · 19.9 KB
/
chapter2.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>2. Sphinx extensions for embedded plots, math and more — learn-sphinx 1.0.0rc1 documentation</title>
<link rel="stylesheet" href="_static/scrolls.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/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 async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script src="_static/theme_extras.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="3. Markdown Cheatsheet" href="chapter3.html" />
<link rel="prev" title="1. Getting started" href="chapter1.html" />
</head><body>
<div id="content">
<div class="header">
<h1 class="heading"><a href="index.html"
title="back to the documentation overview"><span>2. Sphinx extensions for embedded plots, math and more</span></a></h1>
</div>
<div class="relnav" role="navigation" aria-label="related navigation">
<a href="chapter1.html">« <span class="section-number">1. </span>Getting started</a> |
<a href="#"><span class="section-number">2. </span>Sphinx extensions for embedded plots, math and more</a>
| <a href="chapter3.html"><span class="section-number">3. </span>Markdown Cheatsheet »</a>
</div>
<div id="contentwrapper">
<div id="toc" role="navigation" aria-label="table of contents navigation">
<h3>Table of Contents</h3>
<ul>
<li><a class="reference internal" href="#">2. Sphinx extensions for embedded plots, math and more</a><ul>
<li><a class="reference internal" href="#ipython-sessions">2.1. ipython sessions</a></li>
<li><a class="reference internal" href="#using-math">2.2. Using math</a></li>
<li><a class="reference internal" href="#inserting-matplotlib-plots">2.3. Inserting matplotlib plots</a></li>
<li><a class="reference internal" href="#inheritance-diagrams">2.4. Inheritance diagrams</a></li>
<li><a class="reference internal" href="#this-file">2.5. This file</a></li>
</ul>
</li>
</ul>
</div>
<div role="main">
<div class="section" id="sphinx-extensions-for-embedded-plots-math-and-more">
<span id="extensions"></span><h1><span class="section-number">2. </span>Sphinx extensions for embedded plots, math and more<a class="headerlink" href="#sphinx-extensions-for-embedded-plots-math-and-more" title="Permalink to this headline">¶</a></h1>
<p>Sphinx is written in python, and supports the ability to write custom
extensions. We’ve written a few for the matplotlib documentation,
some of which are part of matplotlib itself in the
matplotlib.sphinxext module, some of which are included only in the
sphinx doc directory, and there are other extensions written by other
groups, eg numpy and ipython. We’re collecting these in this tutorial
and showing you how to install and use them for your own project.
First let’s grab the python extension files from the <code class="file docutils literal notranslate"><span class="pre">sphinxext</span></code>
directory from git (see <a class="reference internal" href="chapter1.html#fetching-the-data"><span class="std std-ref">Fetching the data</span></a>), and install them in
our <code class="file docutils literal notranslate"><span class="pre">sampledoc</span></code> project <code class="file docutils literal notranslate"><span class="pre">sphinxext</span></code> directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">mkdir</span> <span class="n">sphinxext</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">cp</span> <span class="o">../</span><span class="n">sampledoc_tut</span><span class="o">/</span><span class="n">sphinxext</span><span class="o">/*.</span><span class="n">py</span> <span class="n">sphinxext</span><span class="o">/</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">ls</span> <span class="n">sphinxext</span><span class="o">/</span>
<span class="n">apigen</span><span class="o">.</span><span class="n">py</span> <span class="n">docscrape</span><span class="o">.</span><span class="n">py</span> <span class="n">docscrape_sphinx</span><span class="o">.</span><span class="n">py</span> <span class="n">numpydoc</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>In addition to the builtin matplotlib extensions for embedding pyplot
plots and rendering math with matplotlib’s native math engine, we also
have extensions for syntax highlighting ipython sessions, making
inhertiance diagrams, and more.</p>
<p>We need to inform sphinx of our new extensions in the <code class="file docutils literal notranslate"><span class="pre">conf.py</span></code>
file by adding the following. First we tell it where to find the extensions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># If your extensions are in another directory, add it here. If the</span>
<span class="c1"># directory is relative to the documentation root, use</span>
<span class="c1"># os.path.abspath to make it absolute, like shown here.</span>
<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="s1">'sphinxext'</span><span class="p">))</span>
</pre></div>
</div>
<p>And then we tell it what extensions to load:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Add any Sphinx extension module names here, as strings. They can be extensions</span>
<span class="c1"># coming with Sphinx (named 'sphinx.ext.*') or your custom ones.</span>
<span class="n">extensions</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'matplotlib.sphinxext.only_directives'</span><span class="p">,</span>
<span class="s1">'matplotlib.sphinxext.plot_directive'</span><span class="p">,</span>
<span class="s1">'IPython.sphinxext.ipython_directive'</span><span class="p">,</span>
<span class="s1">'IPython.sphinxext.ipython_console_highlighting'</span><span class="p">,</span>
<span class="s1">'sphinx.ext.mathjax'</span><span class="p">,</span>
<span class="s1">'sphinx.ext.autodoc'</span><span class="p">,</span>
<span class="s1">'sphinx.ext.doctest'</span><span class="p">,</span>
<span class="s1">'sphinx.ext.inheritance_diagram'</span><span class="p">,</span>
<span class="s1">'numpydoc'</span><span class="p">]</span>
</pre></div>
</div>
<p>Now let’s look at some of these in action. You can see the literal
source for this file at <a class="reference internal" href="#extensions-literal"><span class="std std-ref">This file</span></a>.</p>
<div class="section" id="ipython-sessions">
<span id="ipython-highlighting"></span><h2><span class="section-number">2.1. </span>ipython sessions<a class="headerlink" href="#ipython-sessions" title="Permalink to this headline">¶</a></h2>
<p>Michael Droettboom contributed a sphinx extension which does <a class="reference external" href="http://pygments.org">pygments</a> syntax highlighting on <a class="reference external" href="http://ipython.scipy.org">ipython</a> sessions. Just use ipython as the
language in the <code class="docutils literal notranslate"><span class="pre">sourcecode</span></code> directive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">sourcecode</span><span class="p">::</span> <span class="n">ipython</span>
<span class="n">In</span> <span class="p">[</span><span class="mi">69</span><span class="p">]:</span> <span class="n">lines</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="n">In</span> <span class="p">[</span><span class="mi">70</span><span class="p">]:</span> <span class="n">setp</span><span class="p">(</span><span class="n">lines</span><span class="p">)</span>
<span class="n">alpha</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">animated</span><span class="p">:</span> <span class="p">[</span><span class="kc">True</span> <span class="o">|</span> <span class="kc">False</span><span class="p">]</span>
<span class="n">antialiased</span> <span class="ow">or</span> <span class="n">aa</span><span class="p">:</span> <span class="p">[</span><span class="kc">True</span> <span class="o">|</span> <span class="kc">False</span><span class="p">]</span>
<span class="o">...</span><span class="n">snip</span>
</pre></div>
</div>
<p>and you will get the syntax highlighted output below.</p>
<div class="highlight-ipython notranslate"><div class="highlight"><pre><span></span><span class="n">In</span> <span class="p">[</span><span class="mi">69</span><span class="p">]:</span> <span class="n">lines</span> <span class="o">=</span> <span class="n">plot</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="n">In</span> <span class="p">[</span><span class="mi">70</span><span class="p">]:</span> <span class="n">setp</span><span class="p">(</span><span class="n">lines</span><span class="p">)</span>
<span class="n">alpha</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">animated</span><span class="p">:</span> <span class="p">[</span><span class="kc">True</span> <span class="o">|</span> <span class="kc">False</span><span class="p">]</span>
<span class="n">antialiased</span> <span class="ow">or</span> <span class="n">aa</span><span class="p">:</span> <span class="p">[</span><span class="kc">True</span> <span class="o">|</span> <span class="kc">False</span><span class="p">]</span>
<span class="o">...</span><span class="n">snip</span>
</pre></div>
</div>
<p>This support is included in this template, but will also be included
in a future version of Pygments by default.</p>
</div>
<div class="section" id="using-math">
<span id="id1"></span><h2><span class="section-number">2.2. </span>Using math<a class="headerlink" href="#using-math" title="Permalink to this headline">¶</a></h2>
<p>In sphinx you can include inline math <span class="math notranslate nohighlight">\(x\leftarrow y\ x\forall
y\ x-y\)</span> or display math</p>
<div class="math notranslate nohighlight">
\[W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1 \rho_1} + \frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d \alpha^\prime_2 \left[\frac{ U^{2\beta}_{\delta_1 \rho_1} - \alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2} }{U^{0\beta}_{\rho_1 \sigma_2}}\right]\]</div>
<p>To include math in your document, just use the math directive; here is
a simpler equation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">math</span><span class="p">::</span>
<span class="n">W</span><span class="o">^</span><span class="p">{</span><span class="mi">3</span>\<span class="n">beta</span><span class="p">}</span><span class="n">_</span><span class="p">{</span>\<span class="n">delta_1</span> \<span class="n">rho_1</span> \<span class="n">sigma_2</span><span class="p">}</span> \<span class="n">approx</span> <span class="n">U</span><span class="o">^</span><span class="p">{</span><span class="mi">3</span>\<span class="n">beta</span><span class="p">}</span><span class="n">_</span><span class="p">{</span>\<span class="n">delta_1</span> \<span class="n">rho_1</span><span class="p">}</span>
</pre></div>
</div>
<p>which is rendered as</p>
<div class="math notranslate nohighlight">
\[W^{3\beta}_{\delta_1 \rho_1 \sigma_2} \approx U^{3\beta}_{\delta_1 \rho_1}\]</div>
<p>Recent versions of Sphinx include built-in support for math.
There are three flavors:</p>
<blockquote>
<div><ul class="simple">
<li><p>sphinx.ext.imgmath: uses dvipng to render the equation</p></li>
<li><p>sphinx.ext.mathjax: renders the math in the browser using Javascript</p></li>
<li><p>sphinx.ext.jsmath: it’s an older code, but it checks out</p></li>
</ul>
</div></blockquote>
<p>Additionally, matplotlib has its own math support:</p>
<blockquote>
<div><ul class="simple">
<li><p>matplotlib.sphinxext.mathmpl</p></li>
</ul>
</div></blockquote>
<p>See the matplotlib <a class="reference external" href="https://matplotlib.org/users/mathtext.html">mathtext guide</a> for lots
more information on writing mathematical expressions in matplotlib.</p>
</div>
<div class="section" id="inserting-matplotlib-plots">
<span id="pyplots"></span><h2><span class="section-number">2.3. </span>Inserting matplotlib plots<a class="headerlink" href="#inserting-matplotlib-plots" title="Permalink to this headline">¶</a></h2>
<p>Inserting automatically-generated plots is easy. Simply put the
script to generate the plot in the <code class="file docutils literal notranslate"><span class="pre">pyplots</span></code> directory, and
refer to it using the <code class="docutils literal notranslate"><span class="pre">plot</span></code> directive. First make a
<code class="file docutils literal notranslate"><span class="pre">pyplots</span></code> directory at the top level of your project (next to
:<code class="docutils literal notranslate"><span class="pre">conf.py</span></code>) and copy the <code class="file docutils literal notranslate"><span class="pre">ellipses.py`</span></code> file into it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">mkdir</span> <span class="n">pyplots</span>
<span class="n">home</span><span class="p">:</span><span class="o">~/</span><span class="n">tmp</span><span class="o">/</span><span class="n">sampledoc</span><span class="o">></span> <span class="n">cp</span> <span class="o">../</span><span class="n">sampledoc_tut</span><span class="o">/</span><span class="n">pyplots</span><span class="o">/</span><span class="n">ellipses</span><span class="o">.</span><span class="n">py</span> <span class="n">pyplots</span><span class="o">/</span>
</pre></div>
</div>
<p>You can refer to this file in your sphinx documentation; by default it
will just inline the plot with links to the source and PF and high
resolution PNGS. To also include the source code for the plot in the
document, pass the <code class="docutils literal notranslate"><span class="pre">include-source</span></code> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">plot</span><span class="p">::</span> <span class="n">pyplots</span><span class="o">/</span><span class="n">ellipses</span><span class="o">.</span><span class="n">py</span>
<span class="p">:</span><span class="n">include</span><span class="o">-</span><span class="n">source</span><span class="p">:</span>
</pre></div>
</div>
<p>In the HTML version of the document, the plot includes links to the
original source code, a high-resolution PNG and a PDF. In the PDF
version of the document, the plot is included as a scalable PDF.</p>
<p>You can also inline code for plots directly, and the code will be
executed at documentation build time and the figure inserted into your
docs; the following code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">plot</span><span class="p">::</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="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">hist</span><span class="p">(</span> <span class="n">x</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="n">plt</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">title</span><span class="p">(</span><span class="sa">r</span><span class="s1">'Normal: $\mu=</span><span class="si">%.2f</span><span class="s1">, \sigma=</span><span class="si">%.2f</span><span class="s1">$'</span><span class="o">%</span><span class="p">(</span><span class="n">x</span><span class="o">.</span><span class="n">mean</span><span class="p">(),</span> <span class="n">x</span><span class="o">.</span><span class="n">std</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>produces this output:</p>
<p>See the matplotlib <a class="reference external" href="https://matplotlib.org/users/pyplot_tutorial.html">pyplot tutorial</a> and
the <a class="reference external" href="https://matplotlib.org/gallery.html">gallery</a> for
lots of examples of matplotlib plots.</p>
</div>
<div class="section" id="inheritance-diagrams">
<h2><span class="section-number">2.4. </span>Inheritance diagrams<a class="headerlink" href="#inheritance-diagrams" title="Permalink to this headline">¶</a></h2>
<p>Inheritance diagrams can be inserted directly into the document by
providing a list of class or module names to the
<code class="docutils literal notranslate"><span class="pre">inheritance-diagram</span></code> directive.</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">inheritance</span><span class="o">-</span><span class="n">diagram</span><span class="p">::</span> <span class="n">codecs</span>
</pre></div>
</div>
<p>produces:</p>
<p>See the <span class="xref std std-ref">ipython_directive</span> for a tutorial on embedding stateful,
matplotlib aware ipython sessions into your rest docs with multiline
and doctest support.</p>
</div>
<div class="section" id="this-file">
<span id="extensions-literal"></span><h2><span class="section-number">2.5. </span>This file<a class="headerlink" href="#this-file" title="Permalink to this headline">¶</a></h2>
</div>
</div>
</div>
</div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2021, pku.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.2.
</div>
</body>
</html>