You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by bu...@apache.org on 2012/10/22 20:37:30 UTC
svn commit: r835774 - in /websites/staging/libcloud/trunk/content: ./
docstring-conventions.html
Author: buildbot
Date: Mon Oct 22 18:37:29 2012
New Revision: 835774
Log:
Staging update by buildbot for libcloud
Added:
websites/staging/libcloud/trunk/content/docstring-conventions.html
Modified:
websites/staging/libcloud/trunk/content/ (props changed)
Propchange: websites/staging/libcloud/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Oct 22 18:37:29 2012
@@ -1 +1 @@
-1391151
+1400993
Added: websites/staging/libcloud/trunk/content/docstring-conventions.html
==============================================================================
--- websites/staging/libcloud/trunk/content/docstring-conventions.html (added)
+++ websites/staging/libcloud/trunk/content/docstring-conventions.html Mon Oct 22 18:37:29 2012
@@ -0,0 +1,181 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <title>Apache Libcloud Python library - Docstring Convetions</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
+ <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.min.js" type="text/javascript"></script>
+ <script src="/js/clearlink.js" type="text/javascript"></script>
+ <script src="/js/libcloud.js" type="text/javascript"></script>
+ <script src="/js/jquery.tweet.js" type="text/javascript"></script>
+ <script src="/js/twitter.js" type="text/javascript"></script>
+ <link rel="stylesheet" href="/css/screen.css" type="text/css">
+ <link rel="stylesheet" href="/css/libcloud.css" type="text/css">
+ <link rel="stylesheet" href="/css/code.css" type="text/css">
+ <link rel="stylesheet" href="/css/jquery.tweet.css" type="text/css">
+ <link rel="icon" type="image/png" href="/images/favicon.png"/>
+ <script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-23580482-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+</script>
+
+</head>
+<body>
+ <div class="container">
+ <div id="header" class="span-24 last">
+
+ <h1>Apache Libcloud <span>a unified interface to the cloud</span></h1>
+
+ </div>
+
+ <div id="banner" class="span-24 last">
+
+ <h2>Docstring Convetions</h2>
+
+ </div>
+
+ <div id="feature" class="container">
+
+
+ </div>
+
+
+ <div id="sidebar" class="span-8 border">
+
+<div id="menu">
+ <h2><a href="/">home</a></h2>
+<h2><a href="/news.html">news</a></h2>
+<h2><a href="/about.html">about</a></h2>
+<h2><a href="/getting-started.html">getting started</a></h2>
+<h2><a href="/docs/">documentation</a></h2>
+<h2><a href="/whos-using.html">who's using libcloud?</a></h2>
+<h2><a href="/community-resources.html">community resources</a></h2>
+<h2><a href="/devinfo.html">developer information</a></h2>
+<h2><a href="/gsoc-2012.html">google summer of code</a></h2>
+<h2><a href="/contributing.html">contributing</a></h2>
+<h2><a href="/downloads.html">downloads</a></h2>
+
+</div>
+
+
+
+<h3>Get it</h3>
+<div id="get-it">
+ Latest stable: <a href="/downloads.html">0.11.3</a> (September 25th, 2012)
+</div>
+
+<h3>Need help?</h3>
+<div id="help">
+ <a href="http://webchat.freenode.net/?channels=libcloud&uio=d4">#libcloud @ freenode</a><br /><a
+ href="mailto:users-subscribe@libcloud.apache.org">users@libcloud.apache.org</a><br />
+ <a href="https://plus.google.com/100590055818889164025" rel="publisher">Apache Libcloud @ Google+</a>
+</div>
+
+<h3>What's going on</h3>
+<div id="twitter"></div>
+
+<h3>Links</h3>
+<div id="apache-logo">
+ <a href="http://www.apache.org/"><img src="images/apache_logo.gif" alt="Apache
+ Software Foundation" /></a>
+</div>
+
+
+
+ </div>
+
+
+ <div id="main" class="span-16 last">
+
+ <h2 id="docstring-convetions">Docstring Convetions</h2>
+<p>Libcloud follow <a href="http://epydoc.sourceforge.net/epytextintro.html">epytext</a> docstring formatiing.</p>
+<ul>
+<li>Docstrings should always be used to describe the purpose of methods, functions, classes, and modules.</li>
+<li>Method docstring describes all vargs and keywords (varargs and keywords are the names of the * and ** arguments).</li>
+<li>All of the blocks contained by a field must all have equal indentation, and that indentation must be greater than or equal to the indentation of the field's tag.</li>
+<li>All parametrs must have <code>@param</code> or <code>@keyword</code> field and <code>@type</code> field.</li>
+<li><code>@param p: ...</code> A description of the parameter p for a function or method.</li>
+<li><code>@keyword p: ...</code> A description of the keyword parameter p.</li>
+<li><code>@type p: ...</code> The expected type for the parameter. p.</li>
+<li>Return must contain @return and @rtype.</li>
+<li><code>@return: ...</code> A description of return value for a function or method.</li>
+<li><code>@rtype: ...</code> The type of the return value for a function or method.</li>
+<li>Required parameters contain <code>(required)</code> notation in description.
+For example: <code>@keyword image: OS Image to boot on node. (required)</code></li>
+<li>Multiple types separated with "or"
+For example: <code>@type auth: L{NodeAuthSSHKey} or L{NodeAuthPassword}</code></li>
+<li><code>C{type}</code> for Built-in types and <code>L{type}</code> for Libcloud types.</li>
+<li><code>@type ssh_username: C{str}</code></li>
+<li><code>@type node: L{Node}</code></li>
+<li>For a description of constainer types used notation: <code><container_type> of <objects_type></code>
+For example: <code>@rtype: C{list} of L{Node}</code></li>
+<li>Sometimes you need to inhterit all arguments and add new keyword arguments, for this used <code>@inherits</code> field: <code>@inherits: L{class_name.method_name}</code>
+This field should be added before the arguments. If inherited docstring doesn't contain description\rtype, they used from the parent docstring.</li>
+</ul>
+<p>For example:</p>
+<p>```python
+class NodeDriver(BaseDriver):
+ def create_node(self, **kwargs):
+ """
+ Create a new node instance.</p>
+<div class="codehilite"><pre> <span class="nv">@keyword</span> <span class="n">name:</span> <span class="n">String</span> <span class="n">with</span> <span class="n">a</span> <span class="n">name</span> <span class="k">for</span> <span class="n">this</span> <span class="k">new</span> <span class="n">node</span> <span class="p">(</span><span class="n">required</span><span class="p">)</span>
+ <span class="nv">@type</span> <span class="n">name:</span> <span class="n">C</span><span class="p">{</span><span class="n">str</span><span class="p">}</span>
+
+ <span class="nv">@return:</span> <span class="n">The</span> <span class="n">newly</span> <span class="n">created</span> <span class="n">node</span><span class="o">.</span>
+ <span class="nv">@rtype:</span> <span class="n">L</span><span class="p">{</span><span class="n">Node</span><span class="p">}</span>
+ <span class="s">"""</span>
+<span class="s"> pass</span>
+
+<span class="s"> def deploy_node(self, **kwargs):</span>
+<span class="s"> """</span>
+ <span class="n">Create</span> <span class="n">a</span> <span class="k">new</span> <span class="n">node</span><span class="p">,</span> <span class="ow">and</span> <span class="n">start</span> <span class="n">deployment</span><span class="o">.</span>
+
+ <span class="nv">@inherits:</span> <span class="n">L</span><span class="p">{</span><span class="n">NodeDriver</span><span class="o">.</span><span class="n">create_node</span><span class="p">}</span>
+
+ <span class="nv">@keyword</span> <span class="n">deploy:</span> <span class="n">Deployment</span> <span class="n">to</span> <span class="n">run</span> <span class="n">once</span> <span class="n">machine</span> <span class="n">is</span> <span class="n">online</span> <span class="ow">and</span>
+ <span class="n">availble</span> <span class="n">to</span> <span class="n">SSH</span><span class="o">.</span>
+ <span class="nv">@type</span> <span class="n">deploy:</span> <span class="n">L</span><span class="p">{</span><span class="n">Deployment</span><span class="p">}</span>
+ <span class="s">""</span><span class="err">"</span>
+ <span class="n">pass</span>
+</pre></div>
+
+
+<p>```</p>
+<p>```python
+class OpenStackNodeDriver(NodeDriver):
+ def create_node(self, **kwargs):
+ """
+ @inherits: L{NodeDriver.create_node}</p>
+<div class="codehilite"><pre> <span class="nv">@keyword</span> <span class="n">ex_metadata:</span> <span class="n">Key</span><span class="o">/</span><span class="n">Value</span> <span class="n">metadata</span> <span class="n">to</span> <span class="n">associate</span> <span class="n">with</span> <span class="n">a</span> <span class="n">node</span>
+ <span class="nv">@type</span> <span class="n">ex_metadata:</span> <span class="n">C</span><span class="p">{</span><span class="n">dict</span><span class="p">}</span>
+ <span class="s">""</span><span class="err">"</span>
+ <span class="n">pass</span>
+</pre></div>
+
+
+<p>```</p>
+
+ </div>
+
+ <div id="footer" class="span-24">
+ <a href="http://www.apache.org/licenses/">License</a> | <a
+ href="/security.html">Security</a> | <a
+ href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> | <a
+ href="/credits.html">Credits</a> | <a href="/sitemap.html">Sitemap</a><br /><br />
+
+Copyright © 2009-2011, <a href="http://apache.org/">The Apache Software Foundation</a><br />
+Apache Libcloud, Libcloud, Apache, the Apache feather, and the Apache Libcloud
+project logo are trademarks of the Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+
+ </div>
+ </div>
+</body>
+</html>