Twisted HTML文档标准 (HTML Documentation Standard for Twisted)

可接受的标签（Allowable Tags）

你的HTML文档中仅限使用下列HTML标签（这样做仅仅是为了使文档更合乎逻辑，并不会影响视觉效果）：<html>, <title>, <head>, <body>, <h1>, <h2, <h3>, <ol>, <ul>, <dl>, <li>, <dt>, <dd>, <p>, <code>, <img>, <blockquote>, <a>, <cite>, <div>, <span>, <strong>, <em>, <pre>, <q>, <table>,<tr>, <td> 和<th>.
Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <html>, <title>, <head>, <body>, <h1>, <h2, <h3>, <ol>, <ul>, <dl>, <li>, <dt>, <dd>, <p>, <code>, <img>, <blockquote>, <a>, <cite>, <div>, <span>, <strong>, <em>, <pre>, <q>, <table>,<tr>, <td> and <th>. 请避免用双引号（"）来引用，而应该使用相应的HTML标签来实现－－因为用双引号无法区分左右引号，而有些输出方法需要明确区分左右引用。
Please avoid using the quote sign (") for quoting, and use the relevant html tags (<q></q>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.

多行代码片断（Multi-line Code Snippets）

多行代码片断应该使用带有class属性的<pre>标签来界定。通常使用的class属性是python、python-interpreter和shell，例如： 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>
    下面的代码定义了一个Resource类
        
     For example, this is how one defines a Resource:
    </p>
    
    <pre class="python">
    from twisted.web import resource
    
    class MyResource(resource.Resource):
        def render_GET(self, request):
            return "Hello, world!"
    </pre>

    下面的代码定义了一个Resource类
    
    For example, this is how one defines a Resource:
    
    from twisted.web import resource
    
    class MyResource(resource.Resource):
        def render_GET(self, request):
            return "Hello, world!"

注意不要对<pre>标签中的代码进行整体缩进，这样会使读者很难“复制/粘贴”你的代码。

Note that you should never have leading indentation inside a <pre> block -- this makes it hard for readers to copy/paste the code. == Python交互解释环境（python-interpreter） ==

    <pre class="python-interpreter">
    &gt;&gt;&gt; from twisted.web import resource
    &gt;&gt;&gt; class MyResource(resource.Resource):
    ...     def render_GET(self, request):
    ...         return "Hello, world!"
    ...
    &gt;&gt;&gt; MyResource().render_GET(None)
    "Hello, world!"
    </pre>

    >>> from twisted.web import resource
    >>> class MyResource(resource.Resource):
    ...     def render_GET(self, request):
    ...         return "Hello, world!"
    ...
    >>> MyResource().render_GET(None)
    "Hello, world!"

== shell ==

    <pre class="shell">
    $ mktap web --path /var/www
    </pre>

    $ mktap web --path /var/www

一段文字中的代码（Code inside paragraph text）

对于单行的代码段或是属性、方法、类和模块等名称，可以使用class属性为API或是python的<code>标签。在处理的过程中，会自动在类API参考中搜索模块或是类的名称，并在该类或模块名称上添加指向API文档中相应位置的超链接。如果你想要引用API文档，请确保至少有一个单个的模块名称出现在HTML文档中，这样处理代码会自动的为你加上相应的引用链接。
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. 你也可以把值为API的class属性与base属性结合在一起使用，以描述某个模块或类应该属于那个模块。这有助于保持文档清晰，并减少不必要的模块名称的链接绑定。 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.)
```

PyTwisted/WorkingOnTheTwistedCodeBase/DocumentationStandard

可接受的标签（Allowable Tags）

多行代码片断（Multi-line Code Snippets）

一段文字中的代码（Code inside paragraph text）