当前位置: 首页 > 工具软件 > Read the Docs > 使用案例 >

Read the Docs 入门

蒋啸
2023-12-01

入门

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

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

写文档

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

reStructuredText

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

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”。

Markdown

您可以在同一个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是技术文档的首选格式,可以阅读这篇博文

原文:https://docs.readthedocs.io/en/latest/getting_started.html

 类似资料: