Read the docs 环境搭建

写文档一向是个苦差事，但只有写出好的文档，才能有资格霸气十足的对别人淡淡道出。为了这一崇高目标，经过一些比较和调查，最终锁定Sphinx + ReadTheDocs作为文档写作工具

首先感谢以下两篇教程

https://www.cnblogs.com/youxin/p/3594161.html

https://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs

以下教程是教如何搭建和撰写 Read the docs 文档。

以下教程以Ubuntu 系统为例子，其他系统类似。

前言

使用Sphinx生成文档

Sphinx是一个基于Python的文档生成项目。最早只是用来生成Python的项目文档，但随着这个项目的逐渐完善，很多非Python的知名项目也采用Sphinx作为文档写作工具，甚至完全可以用Sphinx来写书。

引用一段Sphinx生成文档的优点包括：

• 丰富的输出格式: 支持输出为HTML，LaTeX (可转换为PDF)， manual pages(man), 纯文本等若干种格式
• 完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
• 明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
• 美观的自动索引: 可自动生成美观的模块索引
• 精确的语法高亮: 基于 Pygments 自动生成语法高亮
• 开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等

搭建

1.安装 python-sphinx

输入 sudo apt-get install python-sphinx tree

2.安装 sphinx_rtd_theme主题

pip install sphinx_rtd_theme

 

创建项目

命令行输入sphinx-quickstart会进入一个设置向导，根据向导一步一步设置文档项目，其实必填项只有项目名称，作者和版本，其他设置都可以一路回车：

1. 文档根目录(Root path for the documentation)，默认为当前目录(.)
2. 是否分离文档源代码与生成后的文档(Separate source and build directories): y
3. 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_
4. 项目名称(Project name) : EvaEngine
5. 作者名称(Author name)：AlloVince
6. 项目版本(Project version) : 1.0.1
7. 文档默认扩展名(Source file suffix) : .rst
8. 默认首页文件名(Name of your master document):index
9. 是否添加epub目录(Do you want to use the epub builder):n
10. 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：n
11. 生成Makefile (Create Makefile)：y
12. 生成windows用命令行(Create Windows command file):y

然后运行 tree -C . 查看生成的sphinx结构:

由上面图片可以看出，build是生成的文件，source是源码。source文件夹里面conf.py是read the docs的配置文件。 _static是放置一些图片或者其他文件。index.rst是网站首页。

编写文档

放置文件

可以在_static文件夹下放置一些图片，到时候用作网站链接

修改主题

在conf.py文件夹下面添加这三行代码，添加主题

import sphinx_rtd_theme

html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

 编译并且生成网站

在根目录下输入 make html，即可生成网站构建。在build/html目录下即可看到生成的网站。

点击 index.html即可即时查看网站。