样式指南¶
与所有文档一样，具有一致的格式有助于使文档更易于理解。为了使指南更易于理解，所有贡献都应在适当的情况下符合此样式指南的规则。
指南写为 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控制台示例，请使用 doscon 或 powershell 而不是 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
