Read the Docs 入门

蒋啸

2023-12-01

入门

本文将向您展示如何使用Read the Docs。您可以在5分钟内将您的文档导入Read the Docs，为世界精美展现。

如果您已经为您的文档使用了Sphinx或Markdown，请直接跳到导入您的文档。

您有两种方式格式化文档：

有一个屏幕录制，如果您愿意，它可以帮助您。

Sphinx 是一个可以很容易地创建漂亮文档的工具。假设你已经有了 Python，安装 Sphinx：

$ pip install sphinx sphinx-autobuild

在您的项目中创建一个目录来保存您的文档：

$ cd /path/to/project
$ mkdir docs

在那里运行sphinx-quickstart：

$ cd docs
$ sphinx-quickstart

快速入门将引导您创建一些基本配置，一般情况下，您可以使用默认值。完成后，您将拥有一个index.rst、一个conf.py和一些其它文件。将它们添加到版本控制。

现在，编辑您的index.rst并添加一些关于您项目的信息。尽可能多地包含详细信息（如果需要帮助，请参阅reStructuredText语法或此模板）。构建它们以查看它们的外观：

$ make html

注意

您可以使用sphinx-autobuild自动重新加载文档。改为运行sphinx-autobuild . _build/html。

编辑你的文件并重新构建，直到你喜欢所看到的，然后提交你的修改并推送到你的公共存储库。一旦您将Sphinx文档存储在公共存储库中，您就可以开始使用“Read the Docs”。

您可以在同一个Sphinx项目中同时使用Markdown和reStructuredText。Read the Docs支持这一点，您可以在本地执行此操作：

$ pip install recommonmark

然后在你的conf.py增加：

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

注意

Markdown不支持Sphinx的许多功能，如内联标记和指令。但是，它适用于基本散文内容。reStructuredText是技术文档的首选格式，可以阅读这篇博文。