ReStructuredText 文档编写全攻略编写文档说明

编写文档说明

学 python 的人一定会注意到很多python 文档都很相似，不管是整体风格还是结构组织方式都很类似。

比如： scrapy 文档

scrapy.png

再比如： flask 文档

flask.png

再再比如： reStructuredText 中文文档

rst.png

再再再比如： Python-web-guide

web.png

公司内部的项目文档也采用这种方式，近期有接触，把整体流程总结一下。

你肯定会猜测，为什么采用这种方式编写文档，一定存在什么优势？

• 文档即代码：即把文档的编写和 git 代码托管相一致
• 方便的组织结构：利用工具能很好的组织文档的结构
• 风格统一：风格不统一，最后项目维护起来存在巨大的沟通成本

这种文档的组织方式核心是使用了 reStructuredText 标记语言编写文档。

尝试从下面几个步骤讲解文档如何编写：

• reStructuredText 对比 markdown

markdown 同样也是在程序员圈子里比较受欢迎的标记语言，大大减轻了编写文档的难度，reStructuredText 也是一直标记语言，两者存在共性也存在差异性。

• reStructuredText 核心语法

作为 markdown 的重度爱好者，编写文档，真正使用的也就那些语法，同样对于 rst 也只讲解核心的几个语法点

• gitbook 编写文档的流程

gitbook 采用的是 markdown 编写文档，格式不同，但组织方式和 rst 文档的组织方式很相似，可以对比着感受下，选择适合的方式编写文档

• 编写文档的整体流程

rst 只是一种标记语言，需要使用恰当的工具，将 rst 格式的文件转换成 html 等格式的文件，方便托管在服务器上，进行访问，依赖的工具有：sphinx

sphinx 介绍

sphinx 是一个基于python的文档生成工具，许多 python 项目都用使用这个工具自动生成文档。

优势在于：

• 输出格式丰富
• 文档组织结构清晰
• 语法高亮

最大的优势是可以像管理代码一样的管理文档：即文档即代码

安装：默认需要提前安装 python

pip install sphinx

or 

easy_install sphinx

rst vs markdown

markdown:

• 格式简单
• 语法简单
• 原始的 markdown 格式有限，出现了各种扩展：比如 github 风格的 markdown

rst:

• 适合编写复杂项目文档
• 契合 python
• 格式稍复杂于 markdown

reStructuredText 语法

思路：先给出语法，再给出效果的方式讲解

学习语法之前先思考个问题：一篇文档的构成要素有哪些？经过这样的思考便于朝着目标学习核心的语法点。

我的思考结果如下：

• 标题
• 段落
• 文本标记
• 图片
• 表格
• 链接

上述6个部分几乎包括一篇的全部组成，所以学习 rst 语法也从这6个部分着手。

语法：

1.png

结果：

1_1.png

语法：

2.png

结果：

2_1.png

语法：

3.png

结果：

3_1.png

语法：

4.png

结果：

4_1.png

语法：

5.png

结果：

5_1.png

语法：

6.png

结果：

6_1.png

语法：

7.png

结果：

7_1.png

语法：

8.png

8_1.png

结果：

8_2.png

语法：

8_3.png

结果：

8_4.png

具体语法，可以参看上面的中文文档链接，先学会核心的这几个，遇到问题再针对性的查找：

比如：如何在文档内提供下载链接，点击链接就能进行下载

gitbook的使用

Gitbook 和 sphinx 有很多相似之处：

• 自动的生成文档
• 使用标记语言：gitbook 使用 markdown、sphinx 使用 rst
• 文档的结构组织方式很相似：gitbook 是 SUMMARY.md 、sphinx 使用的文件是 index.rst
• 安装 gitbook 客户端

前提需要安装: NodeJs
 
npm install gitbook-cli -g

• 创建一个项目:初始化书本的目录

gitbook init    

生成两个文件：

README.md
SUMMARY.md

• 在 SUMMARY.md 文件中构造目录结构

比如创建两个章节：

# Summary

## one
* [Introduction](README.md)
* [Chapter1](chapter1/README.md)
    * [Section1.1](chapter1/section1.1.md)
    * [Section1.2](chapter1/section1.2.md)

## two
* [Chapter2](chapter2/README.md)
    * [Section2.1](chapter2/section2.1.md)

使用 gitbook init 自动创建chapter1 和 chapter2 文件夹，文件夹下存在相应的文件内容

此时目录文件有如下：

_book/  chapter1/  chapter2/  README.md  SUMMARY.md

• 分别在 chaper1 文件夹下编辑 section1.1.md 文件等
• 使用命令：gitbook server 编译和预览书籍
• 访问：http://localhost:4000/

9.png

总结：

• 初始化书籍： gitbook init
• 编写SUMMARY.md 文件组织文档结构
• gitbook init 自动创建文件夹和文件
• 编写相应的文件
• gitbook serve 编译和预览书籍内容和结构

编写rst文档的流程

• python
• sphinx
• 编写文档
• 组织文档结构
• make html
• 查看效果

1. 安装python

前提需要 python 环境

2. 安装sphinx

pip install sphinx

3. 创建文档项目

sphinx_quickstart

几乎是一路默认下来。看操作提示。

之后文件目录结构如下：

_build/  _static/  _templates/  conf.py*  index.rst  make.bat  Makefile

其中：

• conf.py 是配置文件，比如theme ， 语言， 插件，等
• index.rst 是文档结构组织的文件，类似于 gitbook SUMMARY.md
• _build 文件夹是文档运行后的结果存放目录

4. 根据需求创建目录和文件，再在 index.rst 文件中进行结构组织

比如：如图所示

文档结构如下：

│  conf.py
│  index.rst
│  make.bat
│  Makefile
│
├─Learn
│      markdown.rst
│      rest.rst
│
├─Practice
│      go.rst
│      ppt.rst
│      python.rst
│
├─_build
├─_static
└─_templates

增加了两个文件夹，文件夹下面各自有各自的 rst 文件

修改 index.rst 文件

Learn
----------------------

.. toctree::
   :caption: Learn 20170916

   Learn/markdown
   Learn/rest


Practice
----------------------

.. toctree::
  :caption: Practice 20170916

  Practice/go
  Practice/python
  Practice/ppt

增加了对新增的两个文件夹的文件的组织。

执行 make html 进行编译和预览，没报错后， 在 _build 文件下 html 文件夹下 index.html 用浏览器打开`， 结果如下：

E:\gerrit\docs_rst
(env35) λ make html
Running Sphinx v1.5.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.


# build succeeded 表示正确

10.png

但看上去结果更像上面的 flask 文档的结构， 假如我想要 scrapy 文档的那种风格呢？

没问题，问题出在两者采用了不同的主题，scrapy 文档的风格是： sphinx-rtd-theme

pip install sphinx_rtd_theme

配置：conf.py 文件

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]


# or

html_theme = "sphinx_rtd_theme"

# or


html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]

11.png

重新编译： make html ，再打开 _build/html/index.html 文件

结果如下：

12.png

总结：

• sphinx-quickstart 初始化文档项目
• 根据需求创建文件夹和文件
• 修改 index.rst 对文档结构进行组织 toctree 指令
• 修改 conf.py 对配置进行修改
• make html 编译
• _build/html/index.html 文件打开预览效果

一个问题：如何支持中文

• 编码方式：utf-8
• conf.py 设置 language = 'zh_CN'

可视化工具介绍

我认为这种标记语言的学习可视化很重要，你立马知道你写的语法符不符合要求，是不是你想要的。

我比较喜欢 JetBrains 旗下的开发工具，几乎我要使用的IDE 都从其中进行选择，风格很相似，会一款了，其他的几乎都会用，而且支持的插件也很多，比如学习 markdown 标记语言，就有可是化插件。rst 有语法高亮插件，并没有可视化插件。所以寻求其他办法。

• Atom + rst-preview-pandoc
• 在线可视化工具: Online reStructuredText edutor
• 开发工具：webstorm、Pycharm、ReText

好，我认为好的学习方法就是朝目标去：

比如你想文档写成 scrapy 文档的形式，那么你应该上 github 查找源代码，然后就着源代码查看效果，边干边学。

13.png