ReStructuredText 文档编写全攻略

来源:互联网 时间:2017-09-18


编写文档说明

学 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的使用

Gitbooksphinx 有很多相似之处:


自动的生成文档
使用标记语言:gitbook 使用 markdownsphinx 使用 rst
文档的结构组织方式很相似:gitbookSUMMARY.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 自动创建chapter1chapter2 文件夹,文件夹下存在相应的文件内容


此时目录文件有如下:


_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



相关阅读:
Top