-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathsphinx-doc.html
More file actions
320 lines (260 loc) · 8.82 KB
/
sphinx-doc.html
File metadata and controls
320 lines (260 loc) · 8.82 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
<!DOCTYPE html>
<html lang = "en">
<head>
<meta charset="utf-8"/>
<title>cpoli</title>
<title>Sphinx documentation</title>
<link rel="stylesheet" href="main.css" >
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Droid+Serif">
<link rel="shortcut icon" href="images/cp.ico">
</head>
<body id="body">
<id id="black-strip">
</id>
<div id="top_menu">
<ul>
<li><a href="index.html"><div class="home">Home</div></a></li>
<li><a href="publi.html"><div class="publi">lications</div></a></li>
<li><a href="thesis.html"> <div class="thesis">sis</div></a></li>
<li><a href="vitae.html"> <div class="vitae">ef vitae</div></a></li>
<li><a href="prog.html"><div class="prog">gramming</div></a></li>
</ul>
</div>
<header id=top_header>
<h1> Charles Poli, PhD </h1>
<h2>Head of Artificial Intelligence, </br>
Cambridge Quantum Computing Limited, London.</h2>
</header>
<div id="big_wrapper">
<img src="images/sphinx.jpeg" height="120px" style="margin-left:160px;">
<article> <!-- RESEARCH INTERESTS -->
Sphinx is a Python documentation generator, it allows to create html and latex documentations of python projects. <br>
Visit the website <a href="http://sphinx-doc.org/">http://sphinx-doc.org/</a>.
</br></br>
<h1> Installation </h1>
</br>
To install Sphinx:</br>
</br>
for Mac:</br>
launch a Terminal and </br>
<div class="shell-wrap">
<ul class="shell-body">
<li>sudo port install pyXX-sphinx</li>
</ul>
</div>
for Ubuntu:</br>
launch a Terminal and </br>
<div class="shell-wrap">
<ul class="shell-body">
<li>apt-get install python-sphinx</li>
</ul>
</div>
for Debian:</br>
launch a Terminal and </br>
<div class="shell-wrap">
<ul class="shell-body">
<li>yum install python-sphinx</li>
</ul>
</div>
for Windows:</br>
launch a PowerShell Terminal and </br>
<div class="shell-wrap">
<ul class="shell-body">
<li>pip install python-sphinx</li>
</ul>
</div>
</br>
<h1>A simple example</h1>
<br>
<h2>Create a directory</h2>
<div class="shell-wrap">
<ul class="shell-body">
<li>mkdir project
<li>cd project
</div>
<h2>Create a Python file (let's call it proj.py)</h2>
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
'''<br>
.. todo::<br>
<br>
Add a modulus_squared function.<br>
'''<br>
<br>
import math<br>
<br>
<br>
def sum_diff(a, b):<br>
'''<br>
Calculate the sum and the difference of two variables.<br>
<br>
:param a: number<br>
:param b: number<br>
<br>
:return sum: sum of *a* and *b*<br>
:return diff: difference between *a* and *b*<br>
<br>
::<br>
<br>
# Examples<br>
sum(1, 3) # output 4, -2<br>
sum(1+1j, -1j) # output 1, 1+2j<br>
'''<br>
sum = a + b<br>
diff = a - b<br>
return sum, diff<br>
<br>
<br>
def modulus(z):<br>
r'''<br>
Calculate the modulus :math:`|z|` of a complex number :math:`z`.<br>
The modulus is given by:<br>
<br>
.. math::<br>
<br>
|z| = \sqrt{[\Re(z)]^2+[\Im(z)]^2}<br>
<br>
:param z: complex number<br>
<br>
:return modulus: modulus of :math:`z`<br>
'''<br>
modulus = math.sqrt(z.real**2 + z.imag**2)<br>
return modulus<br>
<br>
</div>
<h2>Syntax</h2>
</br>
Sphinx is indent and line sensitive.<br>
<br>
3 important Sphinx blocks:
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
.. todo:: <br><br>
Things to be done.<br>
</div>
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
.. note::<br><br>
Some notes.<br>
</div>
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
::<br><br>
# python code<br>
</div>
<h2>Math</h2>
</br>
<!--Note the 'r' before the opening triple quotes has to be used if the comments content math expressions. </br> </br>-->
math expressions:
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
In the text :math:`x+y`, like $x+y$ in latex<br>
</div>
<div style="border:3px solid black; margin: 30px 300px 30px 80px; ">
.. math:: <br>
<br>
x+y
<br>
<br>
like $$x+y$$ in latex<br>
</div>
<br>
<h2>Create the documentation</h2>
<div class="shell-wrap">
<ul class="shell-body">
<li> sphinx-apidoc -F -o path_doc/doc path_project/project <br>
</div>
<strong> path_doc</strong> is the path of the parent directory which will contain the documentations<br><br>
<strong>doc</strong> is the name of folder in which the documentations will be generated<br><br>
<strong>path_project</strong> is the path of the parent directory of the project directory<br><br>
<strong>project</strong> is the name of the directory containing the Python files to be documented<br><br>
If you want doc and project to have the same parent directory run:
<div class="shell-wrap">
<ul class="shell-body">
<li> sphinx-apidoc -F -o doc project <br>
</div>
Go to the doc directory and open conf.py<br><br>
<strong>line 23</strong><br>
Define the path to the Python project.<br>
If doc and project belong to the same parent directory:<br>
sys.path.insert(0, os.path.abspath('../project'))<br>
<br>
<strong>line 37</strong><br>
Add 'sphinx.ext.pngmath', (if you use latex expressions)<br>
<br>
<strong>line xx</strong><br>
If you want the preserve the source ordering (alphabetic ordering otherwise)<br>
copy paste <br>
autodoc_member_order = 'bysource'<br>
<br>
<strong>line 52</strong><br>
Change the name of the index if you have multiple docs<br>
(1 index.html per website).<br>
master_doc = 'index_proj'<br>
And, change the name of index.rst accordingly (to index_proj.rst)
<br>
<strong>line 65</strong><br>
define the version of the project.<br>
version = '0.1'<br>
<br>
<strong>line 56 and 57</strong><br>
Add your name<br>
<br>
<strong>line 106</strong><br>
Change the html theme<br>
visit <a href="http://sphinx-doc.org/theming.html">http://sphinx-doc.org/theming.html</a> to pick up one.<br>
<br>
<strong>line 218</strong> (latex)<br>
Change the font size <br>
'pointsize': '12pt',<br>
<br>
<strong>line 232</strong> (latex)<br>
Add your name <br>
<br>
<br>
Using the terminal, go in the doc directory,
if you want a html documentation, run
<div class="shell-wrap">
<ul class="shell-body">
<li> make html <br>
</div>
if you want a latex documentation, run
<div class="shell-wrap">
<ul class="shell-body">
<li> make pdflatex <br>
</div>
From the doc directory go to _build/html and/or _build/latex, <br>
you will find the html/latex documentation files.<br>
<br><br>
The html folder contains 4 html files:<br>
index.html<br>
proj.html<br>
genindex.html<br>
py-modindex.html<br>
<br>
<h2>A bit of polishing</h2>
Let's make some changes in the index_proj.rst:
Remove lines 16 to 22 (we don't need those for that example).
line 14 change 'proj' to 'code'
line 15 add 'about' (just below 'code')
line 16 add 'examples' (just below 'code')
line 9 remove 'Contents:'
line 6 change the title to 'The Very Simple Example'
line 12
Replace :maxdepth: 4' by :hidden:
rename proj.rst to code.rst,
create about.rst,
create examples.rst
================
<h2>Done!</h2>
<br>
It is also possible to create .rst files and add them to the
The proj.html looks like <a href="sphinx-proj/proj.html">proj.html</a> (with a bizstyle)<br>
<br>
If you post the html doc on github <br>
create an empty file name touch .nojekyll<br>
<div class="shell-wrap">
<ul class="shell-body">
touch .nojekyll
</div>
<footer id="thefooter">
<small>© Copyright cpoli 2014</small>
</footer>
</body>
</html>