使用 reST 和使用 HTML 使用 Sphinx 编写文档有什么区别？答案

【问题标题】：What's the difference between using reST and using HTML to write documentation with Sphinx?使用 reST 和使用 HTML 使用 Sphinx 编写文档有什么区别？
【发布时间】：2021-02-05 21:34:28
【问题描述】：

我已经知道这是一个非常愚蠢的问题，但我对如何为我正在从事的项目编写文档有些疑问。基本上我使用 Django 构建了一个 API，现在我需要为它编写 Docs，所以我开始使用 Sphinx 并且我开始了，所以我创建了我的第一个文档并使用命令 make html 为它构建了 HTML。

现在，我知道为了编写文档，我需要使用 rst 文件，但我对它很陌生，我仍然必须完全理解它的语法是如何工作的，所以我的问题是：为什么我不能只使用 Sphinx 生成的 HTML 并继续在 HTML 文件上编写文档，而不是每次都使用 reST 和 make html 吗？

当我更熟悉 reST 后，我会看到它的优势吗？如果我只是抓取 Sphinx 生成的模板并在相同的 HTML 文件上构建文档，是否仍然可以？

【问题讨论】：

更新 HTML 时比更新 .rst 时更有可能破坏某些内容
为什么不使用机器代码而不是 Python/Django 编写应用程序？（Python 解释器在执行你的应用程序时不断生成机器代码。）如果你知道这个答案，你可以回答这个。
这是有道理的，但是现在写html感觉更容易，但我不能真正判断，因为我不熟悉rst，可能一旦我熟悉了我会说相反
然后写HTML，没有错。它更灵活，可读性更差。你的选择。
ReST 和 Markdown 都是 Sphinx 支持的源标记语言，使用 MyST 您可以混合和匹配这两种语法，并充分利用 reST 的优势。有些人发现 markdown 比 reST 更容易使用，但它的功能更少。 reST、Sphinx 和 MyST 提供了许多有用的功能，包括从 API 文档字符串生成文档、参考链接、索引、词汇表和搜索。 HTML 没有。

标签： python html python-sphinx restructuredtext

【解决方案1】：

让我们从解决一个关键差异开始：

使用 reST 和使用 HTML 的区别

reST 和 HTML 都是标记语言，但是 reST 比 HTML 更轻量级。请注意，在 HTML 中元素被标签包围，一切都是明确的。而在 reST 中，语法不那么复杂，从而提高了纯文本的易读性和可维护性。给定两种语言的 2 个结构，依靠缩进等隐式规则，reST 结构会更加简洁。

reStructuredText Markup Specification

简单、隐式的标记用于指示特殊结构 (...) 使用的标记尽可能少且不显眼。

然后让我们想想重构文本的一个关键目标：

reStructuredText

reStructuredText 的主要目标是定义和实现一种标记语法，以便在 Python 文档字符串 (...) 中使用，该语法可读且简单，但功能强大，可用于非平凡的使用。标记的预期目的是将 reStructuredText 文档转换为有用的结构化数据格式。

这与Docstring Format Goals - PEP 216一致。

现在我们有了一些上下文来回答标题中的完整问题：

用 ReST 和用 HTML 用 Sphinx 写文档有什么区别？

用简单的技术术语来说，您可以在一个 reST 文件中包含 HTML，以便 Sphinx 生成最终文档。这可以通过使用许多 reST 指令来实现，例如 meta、include 或 raw。但是这样做会失去前面提到的 reST 优势。

此外，Sphinx 有一个number of builders 可用于生成不同的输出格式。通过在 reST 上使用 HTML，您会失去生成这些格式的透明度。

为什么我不能只使用 Sphinx 生成的 HTML 并继续在 HTML 文件上编写文档？

由于编辑最终的 HTML 既麻烦又乏味，您必须手动维护一些 Sphinx 功能，例如 cross-references、index，以及与各种 domains 的互操作性。

自动化和生产力是 reST 和 Sphinx 的标志性优势。例如。它们的使用摘要来自编辑HTML attributes 和所有其他 HTML 元素都是透明生成的，它们的一致性由 Sphinx 为您管理。

【讨论】：

完美答案！万分感谢！现在清楚多了