[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