注解

本指南部分内容可能尚未符合本指南指引。欢迎更新这些部分以保持同步。

注解

在任何一个渲染后的HTML页面，您可以点击“查看源码（Show Source）”来看作者是如何排版的。

关联¶

尽量保持任何贡献与本指南目的 相关。

• 避免在主题中包含太多与Python开发并不直接相关的信息。
• 如果其他资源已存在，最好以链接的形式来展示。确保描述出您所链接的内容和原因。
• Cite引用在需要的地方。
• 如果某主题并不与Python直接相关，但是和Python之间的关联又很有用（比如Git、GitHub、数据库等），以链接的形式引用这些资源，并描述为什么它对Python有用。
• 如果疑问，就去询问。

标题¶

使用下列风格作为标题。

章节标题：

#########章节 1#########

页面标题：

===================时间是种幻觉===================

小节标题:

午餐时间加倍-------------------

次小节标题:

非常深~~~~~~~~~

换行¶

每78个字符进行文字换行。必要时可以超过78个字符，尤其是那种换行使得源内容更难阅读的情况。

使用标准的美式英语，而非英式英语。

序列逗号（serial comma）（也称为Oxford comma，牛津逗号）的使用是100%没有选择的。 任何尝试以缺少的连续逗号提交内容将导致该项目的永久性移除，因为完全缺乏品味。

流放？ 您在开玩笑吗？ 希望我们永远不必找出来。

代码例子¶

所有代码示例要在70个字符进行换行，以避免出现水平滚动条。

命令行例子：

..code-block::console$ runcommand --help$ ls ..

确保每行前面包含了$ 前缀。

Python解释器例子：

Label the example::..code-block:: python    >>> import this

Python 例子：

Descriptive title::..code-block::pythondefget_answer():return42

外部链接¶

• 链接时最好使用众所周知的主题（比如一些合适的名词）：

  Sphinx_ 通常用来文档化Python。.._Sphinx: http://sphinx.pocoo.org

• 最好使用带有内联链接的描述性标签，而不是单纯的链接:

  阅读`Sphinx 教程<http://sphinx.pocoo.org/tutorial.html>`_

• 避免使用诸如“点击这里”、“这个”等标签。最好使用描述性标签（值得搜索引擎优化，SEO worthy）。

指向指南内部章节的链接¶

要交叉引用本文档的其他部分，使用:ref: 关键字和标签。

要使引用标签更加清晰和独特，通常加上一个-ref 后缀：

.._some-section-ref:Some Section------------

注意和警告¶

使用适当的警告指示 来说明注意内容。

注意:

..note::    The Hitchhiker’s Guide to the Galaxy has a few things to say    on the subject of towels. A towel, it says, is about the most    massively useful thing an interstellar hitch hiker can have.

警告:

..warning:: DON'T PANIC

要做的事¶

请用todo 指示 来标记本指南中任何未完成的部分。避免使要做的事 混乱，为未完的文档或者大量未完的小节使用单独的todo。

..todo::    Learn the Ultimate Answer to the Ultimate Question    of Life, The Universe, and Everything