可接受的标签（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.)
```

应该正确的使用型如<hN>的Header标签的事儿其实不提也行－－<h1>在一个文档中只能出现一次，就是用来描述文档的题目。一个小节的题目可以用<h2>来描述，它下面的子标题可以用<h3>来描述，依此类推。
It goes without mentioning that you should use <hN> in a sane way -- <h1> should only appear once in the document, to specify the title. Sections of the document should use <h2>, sub-headers <h3>, and so on.

XHTML

文档中强制使用XHTML。这意味着那些没有闭合标签部分的HTML标签需要使用一个/来实现，例如：<hr />。此外，在HTML中具有可选的闭合标签部分的HTML标签在XHTML中必须将闭合部分补全，例如：<li>foo</li>
XHTML is mandatory. That means tags that don't have a closing tag need a /; for example, <hr /> . Also, tags which have optional closing tags in HTML need to be closed in XHTML; for example, <li>foo</li>

标签的大小写（Tag Case）

所有的标签都应该使用小写的形式，XHTML标准要求这样做，因此我们也这样要求，^_
All tags will be done in lower-case. XHTML demands this, and so do I.

脚注（Footnotes）

脚注要放在<span class="footnote"></span>里面，其中不允许包含任何数字或顺序标记。
Footnotes are enclosed inside <span class="footnote"></span>. They must not contain any markup.

建议（Suggestions）

使用lore -o lint来验证你的文档没有违反上述规定。lore -o lint不会改变你的HTML代码，但是如果其中存在任何错误，他都会替你挑出来。 Use lore -o lint to check your documentation is not broken. lore -o lint will never change your HTML, but it will complain if it doesn't like it. 不要使用table标签来格式化输出。这是nuff说的。 Don't use tables for formatting. 'nuff said.

all属性（all）

__all__属性是一个模块级的字符串list，用于暴露模块中的对象名称。请确定你的模块中想要导出的类、函数和常量都列在里面。
__all__ is a module level list of strings, naming objects in the module that are public. Make sure publically exported classes, functions and constants are listed here.

<< 返回（PyTwisted/WorkingOnTheTwistedCodeBase）

Version: 1.3.0

by bigbabon, 2004-06-09

PyTwisted/WorkingOnTheTwistedCodeBase/DocumentationStandard (last edited 2009-12-25 07:16:22 by localhost)

PyTwisted/WorkingOnTheTwistedCodeBase/DocumentationStandard