Contents
Welcome to learn_readthedocs
Documentation¶
ReadTheDocs 是一个能在你每次Commit到GitHub后, 自动Build并部署你的文档网站的服务。免除了繁琐的自行Build文档, 然后部署网站的过程。
ReadTheDocs使用Python社区的 Sphinx 文档创建引擎。
使用ReadTheDocs服务¶
请按照下面的流程, 学习如何使用ReadTheDocs。你可以Folk 此项目 用于练习。然后可以在 这里看到本项目的例子的成品网站。
第一步, 创建你的文档网站, 并将代码放在GitHub上¶
首先, 你需要在 GitHub 上 创建 一个代码库。然后使用Sphinx 创建 你的文档网站, 确保能在本地成功的Build。
第二步, 设置ReadTheDocs¶
首先你要将项目关联到ReadTheDocs。你需要在 控制面板 导入 你的项目。
然后, 你需要进入Admin菜单进行一些设置。下面列出了一些比较容易出问题的设置的解说:
- Language: 如果你的文档中是纯英文, 就选择默认的English; 如果是中文文档, 就选择Chinese。
- Programming Language: 如果你是纯文档, 就选择Only Words; 如果需要从Python代码中自动生成文档, 则选择Python2。
高级设置:
- Install Project: 如果你需要从代码中自动生成文档, 则你需要确保你的项目是可import的。所以当然首先需要安装你的项目。勾选此项使得在Build文档前先安装你的包。
- Requirements File: 如果你需要从代码中自动生成文档, 则你需要确保你的项目是可import的。但你的项目可能依赖一些其他的包才能够运行。这些依赖就在 requirments.txt 文件中定义的。
- Single version: 请勾选此选项, 保持网站默认使用最新的文档。
- Python interpreter: Build文档的Python虚拟环境, 请确保和你的项目开发环境一致。
至此, 每当你有新的更新时, ReadTheDocs就会自动Build你的网站了, 如果成功了, 则会自动部署。如果失败了, 你可以查看Build日志了解发生了什么事。
其他替代方案¶
任何支持静态网站部署的服务都可以用于部署你的文档网站。例如AWS的 S3 服务提供了自动部署静态网站的服务。具体做法请参考 官方文档。你所要做的只是将文档网站文件的压缩包上传到S3即可。
你可以自行尝试其他的服务提供商。
ReadTheDocs的限制¶
在后台设置界面, 有一个选项叫Language, 默认设置是en(英文)。此时 不允许文档中出现任何非英文字符, 若出现了, 则会导致Build失败。所以在我们如果要Build一个中文网站, 则需要将Language设置为Chinese。
2016年6月, 发现ReadTheDocs的域名不太稳定。个人比较偏好使用AWS S3或PyPI的PythonHost部署文档。
About the Author¶
(\ (\
( -.-)o I am a lovely Rabbit!
o_(")(")
Sanhe Hu is a very active Python Developer Since 2010. Now working at Whiskerlabs as a Data Scientist. Research area includes Machine Learning, Big Data Infrastructure, Block Chain, Business Intelligent, Open Cloud, Distribute System. Love photography, vocal, outdoor, arts, game, and also the best Python.
- My Github: https://github.com/MacHu-GWU
- My HomePage: http://www.sanhehu.org/