Read the Docs 入门

入门

本文将向您展示如何使用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

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值