使用 reST 和使用 HTML 用 Sphinx 编写文档有什么区别？
What's the difference between using reST and using HTML to write documentation with Sphinx?
我已经知道这是一个非常菜鸟的问题，但我对如何为我正在从事的项目编写文档有一些疑问。基本上我使用 Django 构建了一个 API，现在我需要为它编写文档，所以我开始 Sphinx 并且我开始了，所以我创建了我的第一个文档并构建了 HTML使用命令 make html.
现在，我知道为了编写文档我需要使用 rst 文件，但我对它还很陌生，我仍然需要完全理解它的语法是如何工作的，所以我的问题是：为什么我不能只使用 Sphinx 生成的 HTML 并继续在 HTML 文件上编写文档，而不是每次都使用 reST 和 make html？
一旦我对 reST 更加熟悉，我会看到这是一个优势吗？如果我只获取 Sphinx 生成的模板并在相同的 HTML 文件上构建文档，是否仍然可以？
让我们从解决一个关键差异开始：
difference between using reST and using HTML
reST 和 HTML 都是标记语言，但是 reST 比 HTML 更 light-weight。请注意，在 HTML 中，元素被标记包围并且一切都是明确的。而在 reST 中，语法不那么复杂，导致更好的纯文本易读性和可维护性。给定两种语言的 2 个构造，reST 构造将通过依赖缩进等隐式规则更加简洁。
reStructuredText Markup Specification
Simple, implicit markup is used to indicate special constructs (...) The markup used is as minimal and unobtrusive as possible.
然后让我们考虑一下重构文本的一个关键目标：
The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings (...) that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.
这与Docstring Format Goals - PEP 216一致。
现在我们有了一些背景来回答标题中的完整问题：
What's the difference between using reST and using HTML to write documentation with Sphinx?
用简单的技术术语来说，您可以将 HTML 包含在 Sphinx 的 reST 文件中以生成最终文档。这可以通过使用一些 reST 指令来实现，比如 meta, include or raw。但是这样做你会失去前面提到的 reST 优势。
此外，Sphinx 有一个 number of builders 可用于生成不同的输出格式。通过使用 HTML 而不是 reST，您会失去生成这些格式的透明度。
Why can't I just take the HTML generated by Sphinx and keep writing the documentation on the HTML files?
因为编辑最终的 HTML 会很麻烦和乏味，您将不得不手动维护许多 Sphinx 功能，例如 cross-references, an index, and interoperability with a wide array of domains.
自动化和生产力是 reST 和 Sphinx 的标志性优势。例如。它们的使用摘要来自编辑 HTML attributes 和所有其他 HTML 元素是透明生成的，它们的一致性由 Sphinx 为您管理。
我已经知道这是一个非常菜鸟的问题，但我对如何为我正在从事的项目编写文档有一些疑问。基本上我使用 Django 构建了一个 API，现在我需要为它编写文档，所以我开始 Sphinx 并且我开始了，所以我创建了我的第一个文档并构建了 HTML使用命令 make html.
现在，我知道为了编写文档我需要使用 rst 文件，但我对它还很陌生，我仍然需要完全理解它的语法是如何工作的，所以我的问题是：为什么我不能只使用 Sphinx 生成的 HTML 并继续在 HTML 文件上编写文档，而不是每次都使用 reST 和 make html？
一旦我对 reST 更加熟悉，我会看到这是一个优势吗？如果我只获取 Sphinx 生成的模板并在相同的 HTML 文件上构建文档，是否仍然可以？
让我们从解决一个关键差异开始：
difference between using reST and using HTML
reST 和 HTML 都是标记语言，但是 reST 比 HTML 更 light-weight。请注意，在 HTML 中，元素被标记包围并且一切都是明确的。而在 reST 中，语法不那么复杂，导致更好的纯文本易读性和可维护性。给定两种语言的 2 个构造，reST 构造将通过依赖缩进等隐式规则更加简洁。
reStructuredText Markup Specification
Simple, implicit markup is used to indicate special constructs (...) The markup used is as minimal and unobtrusive as possible.
然后让我们考虑一下重构文本的一个关键目标：
The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings (...) that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.
这与Docstring Format Goals - PEP 216一致。
现在我们有了一些背景来回答标题中的完整问题：
What's the difference between using reST and using HTML to write documentation with Sphinx?
用简单的技术术语来说，您可以将 HTML 包含在 Sphinx 的 reST 文件中以生成最终文档。这可以通过使用一些 reST 指令来实现，比如 meta, include or raw。但是这样做你会失去前面提到的 reST 优势。
此外，Sphinx 有一个 number of builders 可用于生成不同的输出格式。通过使用 HTML 而不是 reST，您会失去生成这些格式的透明度。
Why can't I just take the HTML generated by Sphinx and keep writing the documentation on the HTML files?
因为编辑最终的 HTML 会很麻烦和乏味，您将不得不手动维护许多 Sphinx 功能，例如 cross-references, an index, and interoperability with a wide array of domains.
自动化和生产力是 reST 和 Sphinx 的标志性优势。例如。它们的使用摘要来自编辑 HTML attributes 和所有其他 HTML 元素是透明生成的，它们的一致性由 Sphinx 为您管理。