1
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
3
<title>Twisted Documentation: HTML Documentation Standard for Twisted</title>
4
<link href="../../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
8
<h1 class="title">HTML Documentation Standard for Twisted</h1>
9
<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>
13
<h2>Allowable Tags<a name="auto0"/></h2>
15
<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>
17
<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>
19
<h2>Multi-line Code Snippets<a name="auto1"/></h2>
21
<p>Multi-line code snippets should be delimited with a
22
<pre> tag, with a mandatory <q>class</q> attribute. The
23
conventionalized classes are <q>python</q>, <q>python-interpreter</q>,
24
and <q>shell</q>. For example:</p>
26
<h3><q>python</q><a name="auto2"/></h3>
27
<pre xml:space="preserve">
29
For example, this is how one defines a Resource:
32
<pre class="python">
33
from twisted.web import resource
35
class MyResource(resource.Resource):
36
def render_GET(self, request):
37
return "Hello, world!"
41
<p>For example, this is how one defines a Resource:</p>
42
<pre class="python"><p class="py-linenumber">1
47
</p><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>
49
<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>):
50
<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>):
51
<span class="py-src-keyword">return</span> <span class="py-src-string">"Hello, world!"</span>
54
<p>Note that you should never have leading indentation inside a
55
<pre> block -- this makes it hard for readers to
56
copy/paste the code.</p>
58
<h3><q>python-interpreter</q><a name="auto3"/></h3>
59
<pre xml:space="preserve">
60
<pre class="python-interpreter">
61
&gt;&gt;&gt; from twisted.web import resource
62
&gt;&gt;&gt; class MyResource(resource.Resource):
63
... def render_GET(self, request):
64
... return "Hello, world!"
66
&gt;&gt;&gt; MyResource().render_GET(None)
67
"Hello, world!"
71
<pre class="python-interpreter" xml:space="preserve">
72
>>> from twisted.web import resource
73
>>> class MyResource(resource.Resource):
74
... def render_GET(self, request):
75
... return "Hello, world!"
77
>>> MyResource().render_GET(None)
78
"Hello, world!"
81
<h3><q>shell</q><a name="auto4"/></h3>
82
<pre xml:space="preserve">
83
<pre class="shell">
84
$ twistd web --path /var/www
88
<pre class="shell" xml:space="preserve">
89
$ twistd web --path /var/www
92
<h2>Code inside paragraph text<a name="auto5"/></h2>
94
<p>For single-line code-snippets and attribute, method, class,
95
and module names, use the <code> tag, with a class of
96
<q>API</q> or <q>python</q>. During processing, module or class-names
97
with class <q>API</q> will automatically be looked up in the API
98
reference and have a link placed around it referencing the
99
actual API documents for that module/classname. If you wish to
100
reference an API document, then make sure you at least have a
101
single module-name so that the processing code will be able to
102
figure out which module or class you're referring to.</p>
104
<p>You may also use the <code>base</code> attribute in conjuction
105
with a class of <q>API</q> to indicate the module that should be prepended
106
to the module or classname. This is to help keep the documentation
107
clearer and less cluttered by allowing links to API docs that don't
108
need the module name.</p>
109
<pre xml:space="preserve">
111
To add a <code class="API">twisted.web.widgets.Widget</code>
112
instance to a <code class="API"
113
base="twisted.web.widgets">Gadget</code> instance, do
114
<code class="python">myGadget.putWidget("widgetPath",
115
MyWidget())</code>.
119
(implementation note: the widgets are stored in the <code
120
class="python">gadgetInstance.widgets</code> attribute,
129
To add a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.widgets.Widget.html" title="twisted.web.widgets.Widget">twisted.web.widgets.Widget</a></code>
130
instance to a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.widgets.Gadget.html" title="twisted.web.widgets.Gadget">Gadget</a></code>
132
<code class="python">myGadget.putWidget("widgetPath", MyWidget())</code>.
136
(implementation note: the widgets are stored in the <code class="python">gadgetInstance.widgets</code> attribute,
143
<h2>Headers<a name="auto6"/></h2>
145
<p>It goes without mentioning that you should use <hN> in
146
a sane way -- <h1> should only appear once in the
147
document, to specify the title. Sections of the document should
148
use <h2>, sub-headers <h3>, and so on.</p>
150
<h2>XHTML<a name="auto7"/></h2>
152
<p>XHTML is mandatory. That means tags that don't have a
153
closing tag need a <q>/</q>; for example, <code><hr /></code>
154
. Also, tags which have <q>optional</q> closing tags in HTML
155
<em>need</em> to be closed in XHTML; for example,
156
<code><li>foo</li></code></p>
158
<h2>Tag Case<a name="auto8"/></h2>
160
<p>All tags will be done in lower-case. XHTML demands this, and
163
<h2>Footnotes<a name="auto9"/></h2>
165
<p>Footnotes are enclosed inside
166
<code><span class="footnote"></span></code>. They must not
167
contain any markup.</p>
169
<h2>Suggestions<a name="auto10"/></h2>
171
<p>Use <code class="shell">lore -o lint</code> to check your documentation
172
is not broken. <code class="shell">lore -o lint</code> will never change
173
your HTML, but it will complain if it doesn't like it.</p>
175
<p>Don't use tables for formatting. 'nuff said.</p>
177
<h2>__all__<a name="auto11"/></h2>
179
<p><code class="python">__all__</code> is a module level list of strings, naming
180
objects in the module that are public. Make sure publically exported classes,
181
functions and constants are listed here.</p>
185
<p><a href="../../howto/index.html">Index</a></p>
186
<span class="version">Version: 10.0.0</span>
b'\\ No newline at end of file'