样式指南

../_images/33573755856_7f43d43adf_k_d.jpg

与所有文档一样,具有一致的格式有助于使文档更易于理解。为了使指南更易于理解,所有贡献都应在适当的情况下符合此样式指南的规则。

指南写为 reStructuredText

备注

部分指南可能与此样式指南不匹配。请随时更新这些部件以与指南样式指南保持同步

备注

在呈现的HTML的任何页面上,您可以单击“显示源代码”查看作者如何设置页面样式。

相关性

努力保持与 purpose of The Guide

  • 避免包含太多与Python开发无关的主题信息。

  • 如果信息已经存在,则更倾向于链接到其他来源。一定要描述你链接的内容和原因。

  • 在需要的 `地方引用<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#citations>`_参考。

  • 如果主题与Python没有直接关系,但与Python(如Git、GitHub、Databases)结合使用时很有用,请通过链接到有用的资源来引用,并描述它对Python有用的原因。

  • 当有疑问时,问。

标题

标题使用以下样式。

章节标题:

#########
Chapter 1
#########

页面标题:

*******************
Time is an Illusion
*******************

章节标题:

Lunchtime Doubly So
===================

小节标题:

Very Deep
---------

散文

文本行以78个字符换行。必要时,行数可能超过78个字符,特别是换行会使源文本更难阅读。

使用标准美式英语,而不是英式英语。

使用 `连续逗号<https://en.wikipedia.org/wiki/Serial_comma>`_ (也称为牛津逗号)是100%不可选的。由于完全缺乏品味,任何试图提交缺少连续逗号的内容都将导致永久性地被逐出本项目。

驱逐?这是个笑话吗?希望我们永远不必知道。

代码示例

以70个字符包装所有代码示例,以避免水平滚动条。

命令行示例:

.. code-block:: console

    $ run command --help
    $ ls ..

一定要包括 $ 在Unix控制台示例的每行前面加前缀。

对于Windows控制台示例,请使用 dosconpowershell 而不是 console ,省略 $ 前缀。

Python解释器示例:

Label the example::

.. code-block:: python

    >>> import this

Python示例:

Descriptive title::

.. code-block:: python

    def get_answer():
        return 42

外部链接

  • 链接时,首选知名主题(如专有名词)的标签:

    Sphinx_ is used to document Python.
    
    .. _Sphinx: https://www.sphinx-doc.org
    
  • 喜欢将描述性标签与内联链接一起使用,而不是保留裸链接:

    Read the `Sphinx Tutorial <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_
    
  • 避免使用诸如“click here”、“this”等标签,而是使用描述性标签(seo-worthy)。

链接到指南中的节

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

要使参考标签更清晰和唯一,请始终添加 -ref 后缀:

.. _some-section-ref:

Some Section
------------

注释和警告

利用适当的 `告诫指令<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives>`_ 做笔记的时候。

笔记:

.. 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

TODOs

请在指南中不完整的地方用 `待办事项指令<https://www.sphinx-doc.org/en/master/usage/extensions/todo.html>`_。以免弄乱 事項清單 ,使用单个 todo 对于存根文件或较大的不完整部分。

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