• 风格指南指引
    • 关联
    • 标题
      1. 午餐时间加倍
    • 换行
    • 代码例子
    • 外部链接
    • 指向指南内部章节的链接
    • 注意和警告
    • 要做的事

    风格指南指引

    https://farm4.staticflickr.com/3684/33573755856_7f43d43adf_k_d.jpg
    所有文档都有一致的格式,以帮助更好地理解文档。为了使指导更容易消化,所有贡献都应适应风格指南的规则。

    本指南以 reStructuredText 形式编写。

    注解

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

    注解

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

    关联

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

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

    标题

    使用下列风格作为标题。

    章节标题:

    1. #########
    2. 章节 1
    3. #########

    页面标题:

    1. ===================
    2. 时间是种幻觉
    3. ===================

    小节标题:

    1. 午餐时间加倍

    次小节标题:

    1. 非常深
    2. ~~~~~~~~~

    换行

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

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

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

    代码例子

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

    命令行例子:

    1. .. code-block:: console
    2.  
    3. $ run command --help
    4. $ ls ..

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

    Python解释器例子:

    1. Label the example::
    2.  
    3. .. code-block:: python
    4.  
    5. >>> import this

    Python 例子:

    1. Descriptive title::
    2.  
    3. .. code-block:: python
    4.  
    5. def get_answer():
    6. return 42

    外部链接

    • 链接时最好使用众所周知的主题(比如一些合适的名词):

    Sphinx_ 通常用来文档化Python。

    .. _Sphinx: http://sphinx.pocoo.org

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

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

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

    指向指南内部章节的链接

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

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

    1. .. _some-section-ref:
    2.  
    3. Some Section
    4. ------------

    注意和警告

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

    注意:

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

    警告:

    1. .. warning:: DON'T PANIC

    要做的事

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

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

    原文: http://pythonguidecn.readthedocs.io/zh/latest/notes/styleguide.html