-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdevguide.html
392 lines (353 loc) · 19.8 KB
/
devguide.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Developer’s Guide — AnyPyTools 1.11.5 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/cloud.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/table_styling.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" type="text/css" href="_static/nbsphinx-code-cells.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noticia+Text:400,i,b,bi|Open+Sans:400,i,b,bi|Roboto+Mono:400,i,b,bi&display=swap" 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 crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@^1.0.1/dist/embed-amd.js"></script>
<script src="_static/jquery.cookie.js"></script>
<script src="_static/cloud.base.js"></script>
<script src="_static/cloud.js"></script>
<link rel="shortcut icon" href="_static/anypytools.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="AnyPyTools Change Log" href="changelog.html" />
<link rel="prev" title="PyTest plugin." href="pytest_plugin.html" />
<meta name="viewport" content="width=device-width, initial-scale=1">
</head><body>
<div class="relbar-top">
<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="index.html" title="Table Of Contents"
accesskey="C">toc</a> </li>
<li class="right" >
<a href="changelog.html" title="AnyPyTools Change Log"
accesskey="N">next</a> </li>
<li class="right" >
<a href="pytest_plugin.html" title="PyTest plugin."
accesskey="P">previous</a> </li>
<li><a href="index.html">AnyPyTools 1.11.5 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Developer’s Guide</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="tex2jax_ignore mathjax_ignore section" id="developer-s-guide">
<span id="devguide"></span><h1>Developer’s Guide<a class="headerlink" href="#developer-s-guide" title="Permalink to this headline">¶</a></h1>
<div class="figure align-center" id="id1">
<a class="reference internal image-reference" href="_images/relax.png"><img alt="don't panic" src="_images/relax.png" style="width: 80%;" /></a>
<p class="caption"><span class="caption-text">Don’t panic</span><a class="headerlink" href="#id1" title="Permalink to this image">¶</a></p>
</div>
<p>This is place for developer information that does not belong in the user
guides or the API reference, but is useful for people developing or contributing
to AnyPyTools.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All code changes must go through the pull request review procedure.</p>
</div>
<div class="section" id="style-guide">
<h2>Style Guide<a class="headerlink" href="#style-guide" title="Permalink to this headline">¶</a></h2>
<p>AnyPyTools use PEP8 (with some relaxations to the line length) to
ensure consistency throughout the code base.</p>
</div>
<div class="section" id="how-to-test">
<h2>How to Test<a class="headerlink" href="#how-to-test" title="Permalink to this headline">¶</a></h2>
<div class="section" id="dependencies">
<h3>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h3>
<p>Prep your environment for running the tests:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install -r requirements-tests.txt
</pre></div>
</div>
</div>
<div class="section" id="running-the-tests">
<h3>Running the Tests<a class="headerlink" href="#running-the-tests" title="Permalink to this headline">¶</a></h3>
<p>Run all the tests using pytest:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pytest --flake8
</pre></div>
</div>
<p>If you want to run specific tests you can specify the test names to
execute. For example to run test_aliases:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pytest abcutils.py
</pre></div>
</div>
<p>Note that you can pass multiple test names in the above examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pytest abcutils.py datautils.py
</pre></div>
</div>
<p>Happy Testing!</p>
</div>
</div>
<div class="section" id="how-to-document">
<h2>How to Document<a class="headerlink" href="#how-to-document" title="Permalink to this headline">¶</a></h2>
<p>Documentation takes many forms. This will guide you through the steps of
successful documentation.</p>
<div class="section" id="docstrings">
<h3>Docstrings<a class="headerlink" href="#docstrings" title="Permalink to this headline">¶</a></h3>
<p>No matter what language you are writing in, you should always have
documentation strings along with you code. This is so important that it is
part of the style guide. When writing in Python, your docstrings should be
in reStructured Text using the <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc</a> format.</p>
</div>
<div class="section" id="auto-documentation-hooks">
<h3>Auto-Documentation Hooks<a class="headerlink" href="#auto-documentation-hooks" title="Permalink to this headline">¶</a></h3>
<p>The docstrings that you have written will automatically be connected to the
website, once the appropriate hooks have been setup. At this stage, all
documentation lives within AnyPyTools’s top-level <code class="docutils literal notranslate"><span class="pre">docs</span></code> directory.
We uses the sphinx tool to manage and generate the documentation, which
you can learn about from <a class="reference external" href="http://sphinx-doc.org/">the sphinx website</a>.
If you want to generate the documentation, first AnyPyTools itself must be installed
and then you may run the following command from the <code class="docutils literal notranslate"><span class="pre">docs</span></code> dir:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">~/AnyPyTools/docs $ make html</span>
</pre></div>
</div>
<p>All user-facing API should be added to the sphinx documentation. This should be done the
first time that the module, class or function appears in a pull request. From here, call the
new module <code class="docutils literal notranslate"><span class="pre">mymod</span></code>. The following explains how to add hooks.</p>
</div>
<div class="section" id="python-hooks">
<h3>Python Hooks<a class="headerlink" href="#python-hooks" title="Permalink to this headline">¶</a></h3>
<p>Python documentation lives in the <code class="docutils literal notranslate"><span class="pre">docs/api</span></code> directory.
First, create a file in this directory that represents the new module called
<code class="docutils literal notranslate"><span class="pre">mymod.rst</span></code>.
The <code class="docutils literal notranslate"><span class="pre">docs/api</span></code> directory matches the structure of the <code class="docutils literal notranslate"><span class="pre">AnyPyTools/</span></code> directory.
So if your module is in a sub-package, you’ll need to go into the sub-package’s
directory before creating <code class="docutils literal notranslate"><span class="pre">mymod.rst</span></code>.
The contents of this file should be as follows:</p>
<p><strong>mymod.rst:</strong></p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="nt">_AnyPyTools_mymod:</span>
<span class="gh">=======================================</span>
<span class="gh">My Awesome Module -- :mod:`AnyPyTools.mymod`</span>
<span class="gh">=======================================</span>
<span class="p">..</span> <span class="ow">currentmodule</span><span class="p">::</span> AnyPyTools.mymod
<span class="p">..</span> <span class="ow">automodule</span><span class="p">::</span> AnyPyTools.mymod
<span class="nc">:members:</span>
</pre></div>
</div>
<p>This will discover all of the docstrings in <code class="docutils literal notranslate"><span class="pre">mymod</span></code> and create the
appropriate webpage. Now, you need to hook this page up to the rest of the
website.</p>
<p>Go into the <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> file in <code class="docutils literal notranslate"><span class="pre">AnyPyTools/docs/api</span></code> and add
<code class="docutils literal notranslate"><span class="pre">mymod</span></code> to the appropriate <code class="docutils literal notranslate"><span class="pre">toctree</span></code> (which stands for table-of-contents
tree).</p>
</div>
</div>
<div class="section" id="building-the-website">
<h2>Building the Website<a class="headerlink" href="#building-the-website" title="Permalink to this headline">¶</a></h2>
<p>Building the website/documentation requires the following dependencies:</p>
<ol class="arabic simple">
<li><p><a class="reference external" href="http://sphinx-doc.org/">Sphinx</a></p></li>
<li><p><a class="reference external" href="https://pythonhosted.org/cloud_sptheme/cloud_theme.html">Cloud Sphinx Theme</a></p></li>
<li><p><a class="reference external" href="https://recommonmark.readthedocs.io/en/latest/">recommonmark</a></p></li>
<li><p><a class="reference external" href="https://pandoc.org/">pandoc</a></p></li>
<li><p><a class="reference external" href="http://ipython.readthedocs.io/en/stable/install/kernel_install.html">ipykernel</a></p></li>
<li><p><a class="reference external" href="https://nbsphinx.readthedocs.io">nbsphinx</a></p></li>
</ol>
<div class="section" id="procedure-for-modifying-the-website">
<h3>Procedure for modifying the website<a class="headerlink" href="#procedure-for-modifying-the-website" title="Permalink to this headline">¶</a></h3>
<p>The AnyPyTools website source files are located in the <code class="docutils literal notranslate"><span class="pre">docs</span></code> directory.
A developer first makes necessary changes, then rebuilds the website locally
by executing the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make html
</pre></div>
</div>
<p>This will generate html files for the website in the <code class="docutils literal notranslate"><span class="pre">_build/html/</span></code> folder.
The developer may view the local changes by opening these files with their
favorite browser, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ google-chrome _build/html/index.html
</pre></div>
</div>
<p>Once the developer is satisfied with the changes, the changes should be
committed and pull-requested per usual. Once the pull request is accepted, the
documentation is build automatically by travis CI and pushed to the
anybody-research-group/anypytools-docs repository from where it is published with
github pages.</p>
</div>
</div>
<div class="section" id="branches-and-releases">
<h2>Branches and Releases<a class="headerlink" href="#branches-and-releases" title="Permalink to this headline">¶</a></h2>
<p>Mainline AnyPyTools development occurs on the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch. Other branches
may be used for feature development (topical branches) or to represent
past and upcoming releases.</p>
<p>If you have a new fix that needs to be in the next release, you
should make a topical branch and then pull request it into the release branch.
After this has been accepted, the topical branch should be merged with
master as well.</p>
<div class="section" id="maintenance-tasks">
<h3>Maintenance Tasks<a class="headerlink" href="#maintenance-tasks" title="Permalink to this headline">¶</a></h3>
<p>You can cleanup your local repository of transient files such as *.pyc files
created by unit testing by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ rm -f AnyPyTools/*.pyc tests/*.pyc
$ rm -fr build
</pre></div>
</div>
</div>
<div class="section" id="performing-the-release">
<h3>Performing the Release<a class="headerlink" href="#performing-the-release" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ol class="arabic simple">
<li><p>Update and push the release log</p></li>
<li><p>Update version number in <code class="docutils literal notranslate"><span class="pre">anypytools.__init__.py</span></code></p></li>
<li><p>Ensure test pass</p></li>
<li><p>Make PR on GitHub, and check docs compile correctly on Github Actions</p></li>
<li><p>Create a tag with the version number and push it.</p></li>
<li><dl class="simple myst">
<dt>Crate PYPI pckage</dt><dd><ol class="arabic simple">
<li><p>Run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">build</span> <span class="pre">.</span> <span class="pre">--sdist</span></code></p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">twine</span> <span class="pre">upload</span> <span class="pre">dist/*</span></code></p></li>
</ol>
</dd>
</dl>
</li>
<li><p>Update the conda forge package on <a class="reference external" href="https://github.com/conda-forge/anypytools-feedstock">https://github.com/conda-forge/anypytools-feedstock</a></p></li>
</ol>
</div></blockquote>
</div>
</div>
<div class="section" id="document-history">
<h2>Document History<a class="headerlink" href="#document-history" title="Permalink to this headline">¶</a></h2>
<p>Portions of this page have been forked from</p>
<blockquote>
<div><ul class="simple">
<li><p>Xonsh documentation, Copyright 2014-2017, the Xonsh Development Team. All rights reserved.</p></li>
<li><p>PyNE documentation,Copyright 2011-2015, the PyNE Development Team. All rights reserved.</p></li>
</ul>
</div></blockquote>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html" title="index">
<img class="logo" src="_static/anypytools_logo.png" alt="Logo"/>
</a></p><div class="sphinx-toc sphinxlocaltoc">
<h3><a href="index.html">Page contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Developer’s Guide</a><ul>
<li><a class="reference internal" href="#style-guide">Style Guide</a></li>
<li><a class="reference internal" href="#how-to-test">How to Test</a><ul>
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li><a class="reference internal" href="#running-the-tests">Running the Tests</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-document">How to Document</a><ul>
<li><a class="reference internal" href="#docstrings">Docstrings</a></li>
<li><a class="reference internal" href="#auto-documentation-hooks">Auto-Documentation Hooks</a></li>
<li><a class="reference internal" href="#python-hooks">Python Hooks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-the-website">Building the Website</a><ul>
<li><a class="reference internal" href="#procedure-for-modifying-the-website">Procedure for modifying the website</a></li>
</ul>
</li>
<li><a class="reference internal" href="#branches-and-releases">Branches and Releases</a><ul>
<li><a class="reference internal" href="#maintenance-tasks">Maintenance Tasks</a></li>
<li><a class="reference internal" href="#performing-the-release">Performing the Release</a></li>
</ul>
</li>
<li><a class="reference internal" href="#document-history">Document History</a></li>
</ul>
</li>
</ul>
</div>
<div class="sphinxprev">
<h4>Previous page</h4>
<p class="topless"><a href="pytest_plugin.html"
title="Previous page">← PyTest plugin.</a></p>
</div>
<div class="sphinxnext">
<h4>Next page</h4>
<p class="topless"><a href="changelog.html"
title="Next page">→ AnyPyTools Change Log</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/devguide.md.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="sidebar-toggle-group no-js">
<button class="sidebar-toggle" id="sidebar-hide" title="Hide the sidebar menu">
«
<span class="show-for-small">hide menu</span>
</button>
<button class="sidebar-toggle" id="sidebar-show" title="Show the sidebar menu">
<span class="show-for-small">menu</span>
<span class="hide-for-small">sidebar</span>
»
</button>
</div>
<div class="clearer"></div>
</div>
<div class="relbar-bottom">
<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"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="index.html" title="Table Of Contents"
>toc</a> </li>
<li class="right" >
<a href="changelog.html" title="AnyPyTools Change Log"
>next</a> </li>
<li class="right" >
<a href="pytest_plugin.html" title="PyTest plugin."
>previous</a> </li>
<li><a href="index.html">AnyPyTools 1.11.5 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Developer’s Guide</a></li>
</ul>
</div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2021, Morten Enemark Lund.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
<!-- cloud_sptheme 1.4 -->
</body>
</html>