[Twisted-Python] HTML in documentation

Chris Armstrong carmstro at twistedmatrix.com
Tue Mar 12 17:44:46 EST 2002


OK, I've discussed this with Glyph and Moshe, and here are the
changes.  (sigh, i'm getting sick of seemingly discussing
documentation with myself on the mailing list. :P)

> 1.) For code-snippets that are separated from paragraph content, we
> should either use the <code> tag, along with <pre>. for example:

We won't be using <code> for multi-line snippets, but rather <pre>
with a mandatory class attribute. The two classes which we have come to
a conclusion on are "python" for regular python snippets, and
"python-interpreter" for examples of python interactive shell
sessions. For example:

----

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

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

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

----

> 2.) For single-line code-snippets and attribute/method/module-names
> interpolated in a paragraph, <code> shall also be used, but without
> the <pre> tag. Also, module and class names should be specified with
> their fully-qualified name, and have a link to the API documentation,
> which is assumed to be in ../api/current/ (this is how it will be set
> up on the web-site). Regular attribute names don't need to be fully
> qualified (as this wouldn't make sense), but should still be enclosed
> in <code> tags. For example:

We are going to rely entirely on processing for putting in links to
the API documentation. Instead of just having
<code>twisted.internet.main</code>, though, we'll have 
<code class="API">twisted.internet.main</code>. <code> tags used to delimit
actual python expressions will need class="python" as well. For example:

----

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

----

> 5.) Glyph says we should use XHTML, but he's a dork. Discuss. ;-)

Everyone has agreed that we shall use XHTML. That means <br />, people!


So, the next steps for me are to publish this documentation standard,
and start updating existing documentation to follow it.





More information about the Twisted-Python mailing list