[Twisted-Python] HTML in documentation
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?
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> ----
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.
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> ----
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.
participants (1)
-
Chris Armstrong