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.

You may also use the base attribute in conjuction with a class of "API" to indicate the module that should be prepended to the module or classname. This is to help keep the documentation clearer and less cluttered by allowing links to API docs that don't need the module name.

        <p>
    To add a <code class="API">twisted.web.widgets.Widget</code>
    instance to a <code class="API" base="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>
    

To add a twisted.web.widgets.Widget instance to a Gadget instance, do myGadget.putWidget("widgetPath", MyWidget()).

(implementation note: the widgets are stored in the gadgetInstance.widgets attribute, which is a list.)


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