为Flake8编写文档¶

维护者 Flake8 坚信时尚指南的好处。因此，对于所有希望在我们的文档中工作的贡献者，在添加到我们的文档中时，我们提供了一套松散的指导原则和最佳实践。

提交前在本地查看文档¶

在提交包含更改的请求之前，您可以并且应该在本地生成文档。您可以通过运行以下命令来构建文档：

tox -e docs

从包含 tox.ini 文件（其中还包含 docs/ 此文件所在的目录）。

注解

如果文档不是在本地构建的，它们将不会构建在我们的持续集成系统中。我们一般不会合并任何无法持续整合的拉取要求。

你应该跑一趟 doc8 在您准备提交并修复发现的任何错误之前，请先执行linter作业。

我们相信通过资本化 Flake8 在散文中，我们可以帮助减少 flake8 还有这个项目。

我们还定义了一个全局替换 |Flake8| 应该使用并将每个实例替换为 :program:`Flake8 '.

在命令行上记录某些内容时，请使用 .. prompt:: 指令，以便用户更容易地复制和粘贴到终端中。

例子：

.. prompt:: bash

    flake8 --select E123,W503 dir/
    flake8 --ignore E24,W504 dir

我们在文档中使用的最大行长度与中的默认值类似 Flake8 . 请换行79个字符（或更少）。

在一节的最后一段之后和下一节标题之前，用两行新行来分隔它们。这使得阅读纯文本文档更好一些。斯芬克斯在渲染时忽略了这些，因此它们没有语义意义。

例子：

Section Header
==============

Paragraph.


Next Section Header
===================

Paragraph.

为了表示文档的标题，我们放置了相等数量的 = 标题前后行上的符号。例如：

==================================
 Writing Documentation for Flake8
==================================

还请注意，我们通过添加前导空格和 = 在这些线的末尾有符号。

所有的 Flake8 的命令行选项在用户指南中有说明。每个选项都使用 .. option:: 斯芬克斯提供的指令。在文档的顶部，在重新构造的文本注释中，有一个模板，在记录新选项时，应该将该模板复制并粘贴到位。

注解

选项页的顺序是选项在以下输出中的打印顺序：

flake8 --help

请根据订单插入您的选项文档。

使用链接定位允许文档的其他区域使用 :ref: 内部链接文档的角色。例子：

.. _use-anchors:

Use anchors for easy reference linking
======================================

Somewhere in this paragraph we will :ref:`reference anchors
<use-anchors>`.

注解

您不需要为 :ref: 如果章节的标题有足够的标题。

Flake8 的文档有三个不同的（但不是单独的）受众：

目前，你是第三类人之一（因为你正在或正在考虑做出贡献）。

考虑到大多数用户对 Flake8 . 在为用户编写代码时，应将重点放在如何执行某些操作或某个配置或调用的行为上。

插件开发人员只关心 Flake8 他们必须与之互动。保持内部讨论的最小限度。

最后，Flake8开发人员和贡献者需要知道所有东西是如何组合在一起的。我们不需要每一行代码的细节，但是有说服力的解释和设计规范将帮助未来的开发人员理解 Flake8 的内部设计。