HTML Documentation Standard for Twisted

Multi-line Code Snippets

Multi-line code snippets should be delimited with a <pre> tag, with a mandatory 'class' attribute. The conventionalized classes are "python", "python-interpreter", and "shell". For example:

"python"

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

    <pre class="python">
from twisted.web import resource

class MyResource(resource.Resource):
    def render(self, request):
        return "Hello, world!"
    </pre>

For example, this is how one defines a Resource:

from twisted.web import resource

class MyResource(resource.Resource):
    def render(self, request):
        return "Hello, world!"
   

Note that you should never have leading indentation inside a <pre> block -- this makes it hard for readers to copy/paste the code.

"python-interpreter"

    <pre class="python-interpreter">
    &gt;&gt;&gt; from twisted.web import resource
    &gt;&gt;&gt; class MyResource(resource.Resource):
    ...     def render(self, request):
    ...         return "Hello, world!"
    ...
    &gt;&gt;&gt; MyResource().render(None)
    "Hello, world!"
    </pre>

>>> from twisted.web import resource
>>> class MyResource(resource.Resource):
...     def render(self, request):
...         return "Hello, world!"
...
>>> MyResource().render(None)
"Hello, world!"

"shell"

    <pre class="shell">
    $ mktap web --path /var/www
    </pre>

$ mktap web --path /var/www

Code inside paragraph text

For single-line code-snippets and attribute, method, class, and module names, use the <code> tag, with a class of "API" or "python". During processing, module or class-names with class "API" 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 reference an API document, then make sure you at least have a single module-name so that the processing code will be able to figure out which module or class you're referring to.

        <p>
    To add a <code class="API">twisted.web.widgets.Widget</code>
    instance to a <code class="API">twisted.web.widgets.Gadget</code>
    instance, do 
    <code class="python">myGadget.putWidget("widgetPath", MyWidget())</code>.  
        </p>
    
        <p> 
    (implementation note: the widgets are stored in the <code
    class="python">gadgetInstance.widgets</code> attribute,
    which is a
    list.)
        </p>
    

Headers

It goes without mentioning that you should use <hN> in a sane way -- <h1> should only appear once in the document, to specify the title. Sections of the document should use <h2>, sub-headers <h3>, and so on.

XHTML

XHTML is mandatory. That means tags that don't have a closing tag need a '/'; for example, <hr /> . Also, tags which have "optional" closing tags in HTML need to be closed in XHTML; for example, <li>foo</li>

Tag Case

All tags will be done in lower-case. XHTML demands this, and so do I. :-)

Suggestions

(Tidy seems to be causing more harm than good right now, so this next suggestion is on hold for the time being...)

Use 'tidy -e -xml foo.html' before every commit! Also, tidy can be utilized in other ways to auto-correct your XHTML (or convert HTML to XHTML), but can sometimes cause undesirable effects, like converting some </p>s to <br />s.

Don't use tables for formatting. 'nuff said.


Chris Armstrong