~ntt-pf-lab/nova/monkey_patch_notification

<?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">

<head>

<title>Twisted Documentation: HTML Documentation Standard for Twisted</title>

</head>

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

<span/>

<h2>Allowable Tags<a name="auto0"/></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"/></h2>

<p>Multi-line code snippets should be delimited with a

<pre> tag, with a mandatory <q>class</q> attribute. The

conventionalized classes are <q>python</q>, <q>python-interpreter</q>,

and <q>shell</q>. For example:</p>

<h3><q>python</q><a name="auto2"/></h3>

<p>

For example, this is how one defines a Resource:

</p>

from twisted.web import resource

class MyResource(resource.Resource):

def render_GET(self, request):

return "Hello, world!"

</pre>

<p>For example, this is how one defines a Resource:</p>

<pre class="python"><p class="py-linenumber">1

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

<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>):

<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>):

<span class="py-src-keyword">return</span> <span class="py-src-string">"Hello, world!"</span>

</pre>

<p>Note that you should never have leading indentation inside a

<pre> block -- this makes it hard for readers to

copy/paste the code.</p>

<h3><q>python-interpreter</q><a name="auto3"/></h3>

&gt;&gt;&gt; from twisted.web import resource

&gt;&gt;&gt; class MyResource(resource.Resource):

... def render_GET(self, request):

... return "Hello, world!"

...

&gt;&gt;&gt; MyResource().render_GET(None)

"Hello, world!"

</pre>

>>> from twisted.web import resource

>>> class MyResource(resource.Resource):

... def render_GET(self, request):

... return "Hello, world!"

...

>>> MyResource().render_GET(None)

"Hello, world!"

</pre>

<h3><q>shell</q><a name="auto4"/></h3>

$ twistd web --path /var/www

</pre>

$ twistd web --path /var/www

</pre>

<h2>Code inside paragraph text<a name="auto5"/></h2>

<p>For single-line code-snippets and attribute, method, class,

and module names, use the <code> tag, with a class of

<q>API</q> or <q>python</q>. During processing, module or class-names

with class <q>API</q> will automatically be looked up in the API

reference and have a link placed around it referencing the

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>

103

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

110

<p>

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

116

</p>

117

118

<p>

119

(implementation note: the widgets are stored in the <code

120

class="python">gadgetInstance.widgets</code> attribute,

121

which is a

122

list.)

123

</p>

124

125

</pre>

126

127

128

<p>

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>

131

instance, do

132

<code class="python">myGadget.putWidget("widgetPath", MyWidget())</code>.

133

</p>

134

135

<p>

136

(implementation note: the widgets are stored in the <code class="python">gadgetInstance.widgets</code> attribute,

137

which is a

138

list.)

139

</p>

140

141

</div>

142

143

<h2>Headers<a name="auto6"/></h2>

144

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>

149

150

<h2>XHTML<a name="auto7"/></h2>

151

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

157

158

159

160

<p>All tags will be done in lower-case. XHTML demands this, and

161

so do I. :-)</p>

162

163

<h2>Footnotes<a name="auto9"/></h2>

164

165

<p>Footnotes are enclosed inside

166

<code><span class="footnote"></span></code>. They must not

167

contain any markup.</p>

168

169

<h2>Suggestions<a name="auto10"/></h2>

170

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>

174

175

<p>Don't use tables for formatting. 'nuff said.</p>

176

177

178

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>

182

183

</div>

184

185

<p><a href="../../howto/index.html">Index</a></p>

186

<span class="version">Version: 10.0.0</span>

187

</body>

188

</html>

b'\\ No newline at end of file'

Older »