[Twisted-Python] HTML in documentation

Chris Armstrong carmstro at twistedmatrix.com
Tue Mar 12 15:17:52 MST 2002


It has become apparent to me that we need to standardize the tags we
use in HTML documentation for Twisted. This will make it easier to
apply stylesheets to it, as well as use processing tools to convert it
to other formats. Here is my proposal (This is especially aimed at
Moshe, since he is the HTML purist of the bunch, and I want to make
sure he's happy with these so he won't decide to rebel and start his
own repository of docs again ;-)). So I would like it if at least
Moshe and Glyph were to both reply to me in some fashion, even if with
a simple "yes" or "no" (if it's a "no", a short explanation would be
nice ;-)). Of course others are very much encouraged to chime in. The
three of us aren't the only important ones around here, by a long
shot. ;-)

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

----

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

<p>
<code><pre>
    from twisted.web import resource

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

----

The <pre> shall not be assigned any special semantic value in
processing tools or StyleSheets. It is only there so browsers will
render it correctly. Special semantics shall only be assigned to
<code>.

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:

----

<p>To add a 
<a
href="../api/current/twisted/web/widgets_Widget.html"><code>twisted.web.widgets.Widget</code></a>
instance to a 
<a
href="../api/current/twisted/web/widgets_Gadget.html"><code>twisted.web.widgets.Gadget</code></a>
instance, do <code>myGadget.putWidget("widgetPath", MyWidget())</code>.
</p>

<p> 
(implementation note: the widgets are stored in the
<code>gadgetInstance.widgets</code> attribute, which is a list.)
</p>

----

I realize that adding the links to the API documentation everywhere is
ugly, so I suppose it would be fine to only add the link to the first
instance a module/classname shows up in the document. Just make sure
there's a link in there somewhere. Maybe I'll hack on generate.py to
automatically insert the links when it sees a fully-qualified
twisted.* name... (but this doesn't mean one should completely
disregard linking to API docs -- the idea is to have the HTML
documents be browsable both with *or* without pre-processing)

3.) It goes without mentioning that one should use <hN> in a sane way
to organize the document: the only <h1> shall be the title of the
document, <h2> shall be sections, <h3> sub-sections, etc.

4.) Tags that have an optional closing tag should have the optional
closing tag (ie, <li> and </li>). This makes it easier for some
editors and processing tools to work with the code. This point isn't
all that important. If it bothers someone enough, I can deal without
having them. :-)

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

That's about it. Any other suggestions? If everyone agrees to this,
I'll go through all the existing docs and update them with these rules
(I doubt there will be many updates), and probably create a
style-sheet to render them nicely.


p.s. -- The only rules I notice that differ with Moshe's style in his
existing documentation are 1.) he doesn't use <code> around multi-line
code snippets and 2.)  he doesn't have ending </li> tags. Is this a
problem for you, Moshe?







More information about the Twisted-Python mailing list