libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r835774 - in /websites/staging/libcloud/trunk/content: ./ docstring-conventions.html
Date Mon, 22 Oct 2012 18:37:30 GMT
Author: buildbot
Date: Mon Oct 22 18:37:29 2012
New Revision: 835774

Staging update by buildbot for libcloud

    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 @@

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
@@ -0,0 +1,181 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "">
+  <title>Apache Libcloud Python library - Docstring Convetions</title>
+  <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+  <script src="" type="text/javascript"></script>
+  <script src="" 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') + '';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+  <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>
+<h3>Get it</h3>
+<div id="get-it">
+    Latest stable: <a href="/downloads.html">0.11.3</a> (September 25th, 2012)
+<h3>Need help?</h3>
+<div id="help">
+    <a href="">#libcloud @
freenode</a><br /><a
+        href=""></a><br
+	<a href="" rel="publisher">Apache Libcloud
@ Google+</a>
+<h3>What's going on</h3>
+<div id="twitter"></div>
+<div id="apache-logo">
+  <a href=""><img src="images/apache_logo.gif" alt="Apache
+      Software Foundation" /></a>
+    </div>
+    <div id="main" class="span-16 last">
+      <h2 id="docstring-convetions">Docstring Convetions</h2>
+<p>Libcloud follow <a href="">epytext</a>
docstring formatiing.</p>
+<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
+<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>&lt;container_type&gt;
of &lt;objects_type&gt;</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>
+<p>For example:</p>
+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
+        <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
+        <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">&quot;&quot;&quot;</span>
+<span class="s">        pass</span>
+<span class="s">    def deploy_node(self, **kwargs):</span>
+<span class="s">        &quot;&quot;&quot;</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
+        <span class="s">&quot;&quot;</span><span class="err">&quot;</span>
+        <span class="n">pass</span>
+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
+        <span class="s">&quot;&quot;</span><span class="err">&quot;</span>
+        <span class="n">pass</span>
+    </div>
+    <div id="footer" class="span-24">
+    <a href="">License</a> | <a
+    href="/security.html">Security</a> | <a
+    href="">Sponsorship</a> |
+<a href="">Thanks</a> | <a
+    href="/credits.html">Credits</a> | <a href="/sitemap.html">Sitemap</a><br
/><br />
+Copyright © 2009-2011, <a href="">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>

View raw message