1
<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: HTML Documentation Standard for Twisted</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">HTML Documentation Standard for Twisted</h1><div class="toc"><ol><li><a href="#auto0">Allowable Tags</a></li><li><a href="#auto1">Multi-line Code Snippets</a></li><ul><li><a href="#auto2">python</a></li><li><a href="#auto3">python-interpreter</a></li><li><a href="#auto4">shell</a></li></ul><li><a href="#auto5">Code inside paragraph text</a></li><li><a href="#auto6">Headers</a></li><li><a href="#auto7">XHTML</a></li><li><a href="#auto8">Tag Case</a></li><li><a href="#auto9">Footnotes</a></li><li><a href="#auto10">Suggestions</a></li><li><a href="#auto11">__all__</a></li></ol></div><div class="content"><span></span><h2>Allowable Tags<a name="auto0"></a></h2><p>Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <code><html></code>, <code><title></code>, <code><head></code>, <code><body></code>, <code><h1></code>, <code><h2</code>, <code><h3></code>, <code><ol></code>, <code><ul></code>, <code><dl></code>, <code><li></code>, <code><dt></code>, <code><dd></code>, <code><p></code>, <code><code></code>, <code><img></code>, <code><blockquote></code>, <code><a></code>, <code><cite></code>, <code><div></code>, <code><span></code>, <code><strong></code>, <code><em></code>, <code><pre></code>, <code><q></code>, <code><table></code>,<code><tr></code>, <code><td></code> and <code><th></code>.</p><p>Please avoid using the quote sign (<code>"</code>) for quoting, and use the relevant html tags (<code><q></q></code>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.</p><h2>Multi-line Code Snippets<a name="auto1"></a></h2><p>Multi-line code snippets should be delimited with a
3
<pre> tag, with a mandatory <q>class</q> attribute. The
4
conventionalized classes are <q>python</q>, <q>python-interpreter</q>,
5
and <q>shell</q>. For example:</p><h3><q>python</q><a name="auto2"></a></h3><pre>
7
For example, this is how one defines a Resource:
10
<pre class="python">
11
from twisted.web import resource
13
class MyResource(resource.Resource):
14
def render_GET(self, request):
15
return "Hello, world!"
17
</pre><p>For example, this is how one defines a Resource:</p><pre class="python">
18
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">web</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">resource</span>
20
<span class="py-src-keyword">class</span> <span class="py-src-identifier">MyResource</span>(<span class="py-src-parameter">resource</span>.<span class="py-src-parameter">Resource</span>):
21
<span class="py-src-keyword">def</span> <span class="py-src-identifier">render_GET</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">request</span>):
22
<span class="py-src-keyword">return</span> <span class="py-src-string">"Hello, world!"</span>
23
</pre><p>Note that you should never have leading indentation inside a
24
<pre> block -- this makes it hard for readers to
25
copy/paste the code.</p><h3><q>python-interpreter</q><a name="auto3"></a></h3><pre>
26
<pre class="python-interpreter">
27
&gt;&gt;&gt; from twisted.web import resource
28
&gt;&gt;&gt; class MyResource(resource.Resource):
29
... def render_GET(self, request):
30
... return "Hello, world!"
32
&gt;&gt;&gt; MyResource().render_GET(None)
33
"Hello, world!"
35
</pre><pre class="python-interpreter">
36
>>> from twisted.web import resource
37
>>> class MyResource(resource.Resource):
38
... def render_GET(self, request):
39
... return "Hello, world!"
41
>>> MyResource().render_GET(None)
42
"Hello, world!"
43
</pre><h3><q>shell</q><a name="auto4"></a></h3><pre>
44
<pre class="shell">
45
$ mktap web --path /var/www
47
</pre><pre class="shell">
48
$ mktap web --path /var/www
49
</pre><h2>Code inside paragraph text<a name="auto5"></a></h2><p>For single-line code-snippets and attribute, method, class,
50
and module names, use the <code> tag, with a class of
51
<q>API</q> or <q>python</q>. During processing, module or class-names
52
with class <q>API</q> will automatically be looked up in the API
53
reference and have a link placed around it referencing the
54
actual API documents for that module/classname. If you wish to
55
reference an API document, then make sure you at least have a
56
single module-name so that the processing code will be able to
57
figure out which module or class you're referring to.</p><p>You may also use the <code>base</code> attribute in conjuction
58
with a class of <q>API</q> to indicate the module that should be prepended
59
to the module or classname. This is to help keep the documentation
60
clearer and less cluttered by allowing links to API docs that don't
61
need the module name.</p><pre>
63
To add a <code class="API">twisted.web.widgets.Widget</code>
64
instance to a <code class="API"
65
base="twisted.web.widgets">Gadget</code> instance, do
66
<code class="python">myGadget.putWidget("widgetPath",
67
MyWidget())</code>.
71
(implementation note: the widgets are stored in the <code
72
class="python">gadgetInstance.widgets</code> attribute,
77
</pre><div class="boxed"><p>
78
To add a <code class="API">twisted.web.widgets.Widget</code>
79
instance to a <code base="twisted.web.widgets" class="API">Gadget</code>
81
<code class="python">myGadget.putWidget("widgetPath", MyWidget())</code>.
83
(implementation note: the widgets are stored in the <code class="python">gadgetInstance.widgets</code> attribute,
86
</p></div><h2>Headers<a name="auto6"></a></h2><p>It goes without mentioning that you should use <hN> in
87
a sane way -- <h1> should only appear once in the
88
document, to specify the title. Sections of the document should
89
use <h2>, sub-headers <h3>, and so on.</p><h2>XHTML<a name="auto7"></a></h2><p>XHTML is mandatory. That means tags that don't have a
90
closing tag need a <q>/</q>; for example, <code><hr /></code>
91
. Also, tags which have <q>optional</q> closing tags in HTML
92
<em>need</em> to be closed in XHTML; for example,
93
<code><li>foo</li></code></p><h2>Tag Case<a name="auto8"></a></h2><p>All tags will be done in lower-case. XHTML demands this, and
94
so do I. :-)</p><h2>Footnotes<a name="auto9"></a></h2><p>Footnotes are enclosed inside
95
<code><span class="footnote"></span></code>. They must not
96
contain any markup.</p><h2>Suggestions<a name="auto10"></a></h2><p>Use <code class="shell">lore -o lint</code> to check your documentation
97
is not broken. <code class="shell">lore -o lint</code> will never change
98
your HTML, but it will complain if it doesn't like it.</p><p>Don't use tables for formatting. 'nuff said.</p><h2>__all__<a name="auto11"></a></h2><p><code class="python">__all__</code> is a module level list of strings, naming
99
objects in the module that are public. Make sure publically exported classes,
100
functions and constants are listed here.</p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 2.5.0</span></body></html>
b'\\ No newline at end of file'
added
removed
doc/development/policy/doc-standard.html
