-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathdoc_standard.html
More file actions
313 lines (294 loc) · 16.1 KB
/
Copy pathdoc_standard.html
File metadata and controls
313 lines (294 loc) · 16.1 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
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<title>Documentation Standard — SpacePy v0.7.0 Manual</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css?v=92e3d466" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<script src="_static/documentation_options.js?v=fe7df9b0"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script type="text/javascript" src="_static/copybutton.js"></script>
<link rel="icon" href="_static/spacepy_favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Unit tests" href="tests.html" />
<link rel="prev" title="Dependency version support" href="dep_versions.html" />
</head><body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/spacepy_logo.jpg" border="0" alt="spacepy_logo"/></a>
</div>
<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="tests.html" title="Unit tests"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="dep_versions.html" title="Dependency version support"
accesskey="P">previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Documentation Standard</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="documentation-standard">
<h1>Documentation Standard<a class="headerlink" href="#documentation-standard" title="Link to this heading">¶</a></h1>
<p>SpacePy aims to be a high quality product, and as such we (the SpacePy Team) encourage
a a high degree of uniformity in the documentation across included modules. If you are
contributing to SpacePy, or hope to, please take the time to make your code compliant
with the documentation standard.</p>
<p>SpacePy uses <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> to generate its documentation. This allows most of the documentation
to be built from docstrings in the code, with additional information being provided in
reStructured Text files. This allows easy generation of high-quality, searchable HTML
documentation.</p>
<dl class="simple">
<dt>In addition to Sphinx, SpacePy uses the following extensions:</dt><dd><ul class="simple">
<li><p>‘sphinx.ext.autodoc’</p></li>
<li><p>‘sphinx.ext.doctest’’</p></li>
<li><p>‘sphinx.ext.intersphinx’</p></li>
<li><p>‘sphinx.ext.todo’</p></li>
<li><p>‘sphinx.ext.imgmath’ (falls back to ‘sphinx.ext.pngmath’ if imgmath is not available)</p></li>
<li><p>‘sphinx.ext.ifconfig’</p></li>
<li><p>‘sphinx.ext.viewcode’</p></li>
<li><p>‘numpydoc’</p></li>
<li><p>‘sphinx.ext.inheritance_diagram’</p></li>
<li><p>‘sphinx.ext.autosummary’</p></li>
<li><p>‘sphinx.ext.extlinks’</p></li>
</ul>
</dd>
</dl>
<section id="so-what-do-i-need-to-do-in-my-code">
<h2>So what do I need to do in my code?<a class="headerlink" href="#so-what-do-i-need-to-do-in-my-code" title="Link to this heading">¶</a></h2>
<p>Since we are using the ‘numpydoc’ extension there are fixed headings that may
appear in your documentation block. There are a few things to note:
* No other headings can appear in your docstrings
* Most reStructuredText commands cannot appear in your docstrings either (e.g. .. Note:)
* Since ‘numpydoc’ is not well documented, the best way of finding out what you can do in your docstrings is to look at the source for the SpacePy documentation or the numpy documentation.</p>
<section id="allowed-headings">
<h3>Allowed headings<a class="headerlink" href="#allowed-headings" title="Link to this heading">¶</a></h3>
<dl class="simple">
<dt><strong>Always use</strong></dt><dd><ul class="simple">
<li><p>Parameters</p></li>
<li><p>Returns</p></li>
</ul>
</dd>
<dt><strong>Use as needed</strong></dt><dd><ul class="simple">
<li><p>Attributes</p></li>
<li><p>Raises</p></li>
<li><p>Warns</p></li>
<li><p>Other Parameters</p></li>
<li><p>See Also</p></li>
<li><p>Notes</p></li>
<li><p>Warnings</p></li>
<li><p>References</p></li>
<li><p>Examples</p></li>
<li><p>Methods</p></li>
</ul>
</dd>
<dt><strong>No need to use</strong></dt><dd><ul class="simple">
<li><p>Summary</p></li>
<li><p>Extended Summary</p></li>
<li><p>index</p></li>
</ul>
</dd>
<dt><strong>Do not use</strong></dt><dd><ul class="simple">
<li><p>Signature</p></li>
</ul>
</dd>
<dt><strong>Examples</strong></dt><dd><ul class="simple">
<li><p>Use them, but they must be fully stand alone; the user should be able to type the exact
code in the example and it should work as shown (doctest can help with this)</p></li>
</ul>
</dd>
</dl>
</section>
</section>
<section id="function-example">
<h2>Function Example<a class="headerlink" href="#function-example" title="Link to this heading">¶</a></h2>
<p>This code from toolbox shows what a function should look like in your code</p>
<blockquote>
<div><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">logspace</span><span class="p">(</span><span class="nb">min</span><span class="p">,</span> <span class="nb">max</span><span class="p">,</span> <span class="n">num</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""</span>
<span class="sd"> Returns log spaced bins. Same as numpy logspace except the min and max are the ,min and max</span>
<span class="sd"> not log10(min) and log10(max)</span>
<span class="sd"> Parameters</span>
<span class="sd"> ==========</span>
<span class="sd"> min : float</span>
<span class="sd"> minimum value</span>
<span class="sd"> max : float</span>
<span class="sd"> maximum value</span>
<span class="sd"> num : integer</span>
<span class="sd"> number of log spaced bins</span>
<span class="sd"> Other Parameters</span>
<span class="sd"> ================</span>
<span class="sd"> kwargs : dict</span>
<span class="sd"> additional keywords passed into matplotlib.dates.num2date</span>
<span class="sd"> Returns</span>
<span class="sd"> =======</span>
<span class="sd"> out : array</span>
<span class="sd"> log spaced bins from min to max in a numpy array</span>
<span class="sd"> Notes</span>
<span class="sd"> =====</span>
<span class="sd"> This function works on both numbers and datetime objects</span>
<span class="sd"> Examples</span>
<span class="sd"> ========</span>
<span class="sd"> >>> import spacepy.toolbox as tb</span>
<span class="sd"> >>> tb.logspace(1, 100, 5)</span>
<span class="sd"> array([ 1. , 3.16227766, 10. , 31.6227766 , 100. ])</span>
<span class="sd"> """</span>
<span class="kn">from</span> <span class="nn">numpy</span> <span class="kn">import</span> <span class="n">logspace</span><span class="p">,</span> <span class="n">log10</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="nb">min</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">):</span>
<span class="kn">from</span> <span class="nn">matplotlib.dates</span> <span class="kn">import</span> <span class="n">date2num</span><span class="p">,</span> <span class="n">num2date</span>
<span class="k">return</span> <span class="n">num2date</span><span class="p">(</span><span class="n">logspace</span><span class="p">(</span><span class="n">log10</span><span class="p">(</span><span class="n">date2num</span><span class="p">(</span><span class="nb">min</span><span class="p">)),</span> <span class="n">log10</span><span class="p">(</span><span class="n">date2num</span><span class="p">(</span><span class="nb">max</span><span class="p">)),</span> <span class="n">num</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">))</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="n">logspace</span><span class="p">(</span><span class="n">log10</span><span class="p">(</span><span class="nb">min</span><span class="p">),</span> <span class="n">log10</span><span class="p">(</span><span class="nb">max</span><span class="p">),</span> <span class="n">num</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
<p>Which then renders as:</p>
<blockquote>
<div><dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">spacepy.toolbox.</span></span><span class="sig-name descname"><span class="pre">logspace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">min</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">num</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/spacepy/toolbox.html#logspace"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Returns log-spaced bins. Same as numpy.logspace except the min and max are the min and max
not log10(min) and log10(max)</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>min</strong><span class="classifier">float</span></dt><dd><p>minimum value</p>
</dd>
<dt><strong>max</strong><span class="classifier">float</span></dt><dd><p>maximum value</p>
</dd>
<dt><strong>num</strong><span class="classifier">integer</span></dt><dd><p>number of log spaced bins</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><dl class="simple">
<dt><strong>out</strong><span class="classifier">array</span></dt><dd><p>log-spaced bins from min to max in a numpy array</p>
</dd>
</dl>
</dd>
<dt class="field-odd">Other Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>kwargs</strong><span class="classifier">dict</span></dt><dd><p>additional keywords passed into matplotlib.dates.num2date</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.geomspace" title="spacepy.toolbox.geomspace"><code class="xref py py-obj docutils literal notranslate"><span class="pre">geomspace</span></code></a></dt><dd></dd>
<dt><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.linspace" title="spacepy.toolbox.linspace"><code class="xref py py-obj docutils literal notranslate"><span class="pre">linspace</span></code></a></dt><dd></dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>This function works on both numbers and datetime objects. Not leapsecond aware.</p>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">>>> </span><span class="n">tb</span><span class="o">.</span><span class="n">logspace</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">100</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="go">array([ 1. , 3.16227766, 10. , 31.6227766 , 100. ])</span>
</pre></div>
</div>
</dd></dl>
</div></blockquote>
</section>
</section>
<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">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Documentation Standard</a><ul>
<li><a class="reference internal" href="#so-what-do-i-need-to-do-in-my-code">So what do I need to do in my code?</a><ul>
<li><a class="reference internal" href="#allowed-headings">Allowed headings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#function-example">Function Example</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="dep_versions.html"
title="previous chapter">Dependency version support</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="tests.html"
title="next chapter">Unit tests</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/doc_standard.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search 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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<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="tests.html" title="Unit tests"
>next</a> |</li>
<li class="right" >
<a href="dep_versions.html" title="Dependency version support"
>previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Documentation Standard</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2024, The SpacePy Team.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
</div>
</body>
</html>