Cadoles
/
formations
20
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
formations/python/python3/en/_build/html/documenting.html

177 lines
12 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Technical an user documentation &#8212; pyfundoc documentation</title>
<link rel="stylesheet" href="_static/bizstyle.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: ' ',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/bizstyle.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Coding standards" href="codingstandards.html" />
<link rel="prev" title="The standard library" href="sdl.html" />
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<!--[if lt IE 9]>
<script type="text/javascript" src="_static/css3-mediaqueries.js"></script>
<![endif]-->
</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="codingstandards.html" title="Coding standards"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sdl.html" title="The standard library"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pyfundoc documentation</a> &#187;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body" role="main">
<div class="section" id="technical-an-user-documentation">
<h1>Technical an user documentation<a class="headerlink" href="#technical-an-user-documentation" title="Permalink to this headline"></a></h1>
<ul class="simple">
<li><a class="reference external" href="https://realpython.com/documenting-python-code/">documenting</a></li>
</ul>
<p>The <a class="reference external" href="http://sphinx-doc.org/">sphinx</a> tool is a subset of <a class="reference external" href="http://docutils.sf.net">docutils</a></p>
<div class="section" id="documenting-a-function">
<h2>Documenting a function<a class="headerlink" href="#documenting-a-function" title="Permalink to this headline"></a></h2>
<p><strong>Info field lists</strong></p>
<p>Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:</p>
<ul class="simple">
<li>param, parameter, arg, argument, key, keyword: Description of a parameter.</li>
<li>type: Type of a parameter. Creates a link if possible.</li>
<li>raises, raise, except, exception: That (and when) a specific exception is raised.</li>
<li>var: Description of a variable.</li>
<li>vartype: Type of a variable. Creates a link if possible.</li>
<li>returns, return: Description of the return value.</li>
<li>rtype: Return type. Creates a link if possible.</li>
</ul>
<p>The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">py</span><span class="p">:</span><span class="n">function</span><span class="p">::</span> <span class="n">send_message</span><span class="p">(</span><span class="n">sender</span><span class="p">,</span> <span class="n">recipient</span><span class="p">,</span> <span class="n">message_body</span><span class="p">,</span> <span class="p">[</span><span class="n">priority</span><span class="o">=</span><span class="mi">1</span><span class="p">])</span>
<span class="n">Send</span> <span class="n">a</span> <span class="n">message</span> <span class="n">to</span> <span class="n">a</span> <span class="n">recipient</span>
<span class="p">:</span><span class="n">param</span> <span class="nb">str</span> <span class="n">sender</span><span class="p">:</span> <span class="n">The</span> <span class="n">person</span> <span class="n">sending</span> <span class="n">the</span> <span class="n">message</span>
<span class="p">:</span><span class="n">param</span> <span class="nb">str</span> <span class="n">recipient</span><span class="p">:</span> <span class="n">The</span> <span class="n">recipient</span> <span class="n">of</span> <span class="n">the</span> <span class="n">message</span>
<span class="p">:</span><span class="n">param</span> <span class="nb">str</span> <span class="n">message_body</span><span class="p">:</span> <span class="n">The</span> <span class="n">body</span> <span class="n">of</span> <span class="n">the</span> <span class="n">message</span>
<span class="p">:</span><span class="n">param</span> <span class="n">priority</span><span class="p">:</span> <span class="n">The</span> <span class="n">priority</span> <span class="n">of</span> <span class="n">the</span> <span class="n">message</span><span class="p">,</span> <span class="n">can</span> <span class="n">be</span> <span class="n">a</span> <span class="n">number</span> <span class="mi">1</span><span class="o">-</span><span class="mi">5</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">priority</span><span class="p">:</span> <span class="n">integer</span> <span class="ow">or</span> <span class="kc">None</span>
<span class="p">:</span><span class="k">return</span><span class="p">:</span> <span class="n">the</span> <span class="n">message</span> <span class="nb">id</span>
<span class="p">:</span><span class="n">rtype</span><span class="p">:</span> <span class="nb">int</span>
<span class="p">:</span><span class="n">raises</span> <span class="ne">ValueError</span><span class="p">:</span> <span class="k">if</span> <span class="n">the</span> <span class="n">message_body</span> <span class="n">exceeds</span> <span class="mi">160</span> <span class="n">characters</span>
<span class="p">:</span><span class="n">raises</span> <span class="ne">TypeError</span><span class="p">:</span> <span class="k">if</span> <span class="n">the</span> <span class="n">message_body</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">a</span> <span class="n">basestring</span>
</pre></div>
</div>
<p>This will render like this with spinx-doc:</p>
<dl class="function">
<dt id="send_message">
<code class="descname">send_message</code><span class="sig-paren">(</span><em>sender</em>, <em>recipient</em>, <em>message_body</em><span class="optional">[</span>, <em>priority=1</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#send_message" title="Permalink to this definition"></a></dt>
<dd><p>Send a message to a recipient</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>sender</strong> (<em>str</em>) – The person sending the message</li>
<li><strong>recipient</strong> (<em>str</em>) – The recipient of the message</li>
<li><strong>message_body</strong> (<em>str</em>) – The body of the message</li>
<li><strong>priority</strong> (<em>integer</em><em> or </em><em>None</em>) – The priority of the message, can be a number 1-5</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">the message id</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first">int</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ValueError</strong> – if the message_body exceeds 160 characters</li>
<li><strong>TypeError</strong> – if the message_body is not a basestring</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>It is also possible to combine parameter type and description, if the type is
a single word, like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">:</span><span class="n">param</span> <span class="nb">int</span> <span class="n">priority</span><span class="p">:</span> <span class="n">The</span> <span class="n">priority</span> <span class="n">of</span> <span class="n">the</span> <span class="n">message</span><span class="p">,</span> <span class="n">can</span> <span class="n">be</span> <span class="n">a</span> <span class="n">number</span> <span class="mi">1</span><span class="o">-</span><span class="mi">5</span>
</pre></div>
</div>
<p>Container types such as lists and dictionaries can be linked automatically
using the following syntax:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">:</span><span class="nb">type</span> <span class="n">priorities</span><span class="p">:</span> <span class="nb">list</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">priorities</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">mapping</span><span class="p">:</span> <span class="nb">dict</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">mapping</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">int</span><span class="p">]</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">point</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">(</span><span class="nb">float</span><span class="p">,</span> <span class="nb">float</span><span class="p">)</span>
<span class="p">:</span><span class="nb">type</span> <span class="n">point</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">float</span><span class="p">,</span> <span class="nb">float</span><span class="p">]</span>
</pre></div>
</div>
<p>Multiple types in a type field will be linked automatically if separated by
the word “or”:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">:</span><span class="nb">type</span> <span class="n">an_arg</span><span class="p">:</span> <span class="nb">int</span> <span class="ow">or</span> <span class="kc">None</span>
<span class="p">:</span><span class="n">vartype</span> <span class="n">a_var</span><span class="p">:</span> <span class="nb">str</span> <span class="ow">or</span> <span class="nb">int</span>
<span class="p">:</span><span class="n">rtype</span><span class="p">:</span> <span class="nb">float</span> <span class="ow">or</span> <span class="nb">str</span>
</pre></div>
</div>
</div>
</div>
</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="codingstandards.html" title="Coding standards"
>next</a> |</li>
<li class="right" >
<a href="sdl.html" title="The standard library"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pyfundoc documentation</a> &#187;</li>
</ul>
</div>
<div class="footer" role="contentinfo">
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink