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

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 有语法高亮插件,并没有可视化插件。所以寻求其他办法。

好,我认为好的学习方法就是朝目标去:

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

13.png

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏24K纯开源

使用VS2010开发Qt程序的一点经验

导读      相比于Qt Creator,我更喜欢用VS2010来进行开发。虽然启动时间相对较慢,但是VS下强大的快捷键和丰富的插件,以及使用多年的经验,都让...

2798
来自专栏大内老A

WCF中并发(Concurrency)与限流(Throttling)体系深入解析系列[共7篇]

服务(Service)的本质就是提供服务消费者期望的某种功能,服务的价值体现在两个方面:服务本身的质量和寄宿服务的平台应付消费者的数量,并发(Concurren...

1876
来自专栏WeTest质量开放平台团队的专栏

Linker加载so失败问题分析

原文链接:https://wetest.qq.com/lab/view/421.html

1401
来自专栏Python中文社区

如何构建一个分布式爬虫(理论篇)

專 欄 ❈resolvewang,Python中文社区专栏作者 Python和Go爱好者。具有较为丰富的爬虫和反爬虫经验,对web编程略知一二,对基础架构比较感...

5077
来自专栏Albert陈凯

zookeeper详解

Zookeeper--Zookeeper是什么 博客借鉴http://www.cnblogs.com/yuyijq/p/3391945.html​ Googl...

3463
来自专栏达摩兵的技术空间

前端文件下载通识篇

前端如何实现下载文件呢?随着前端技术的发展,越来越多的前端需求中会出现下载文件这样的需求。

5902
来自专栏云计算

重新审视分布式(微服务)体系结构中的全局数据一致性

早在2015年的时候,我写了几篇文章,介绍如何通过搭载标准Java EE事务管理器以获得跨分布式服务的数据一致性(查看原文请点击这里,基于Spri...

1612
来自专栏Java进阶架构师

「架构技术专题」构建网站高可用架构(详细分析篇)(6)

可用性指标时网站架构设计的重要指标,对外是服务承诺,对内是考核指标,具体到每个工程师,更多的是使用故障分。

783
来自专栏Rainbond开源「容器云平台」

开源Rainbond发布v3.4.2更新:应用插件体系进入beta版本

1363
来自专栏butterfly100

Chris Richardson微服务翻译:构建微服务之微服务架构的进程通讯

Chris Richardson 微服务系列翻译全7篇链接: 微服务介绍 构建微服务之使用API网关 构建微服务之微服务架构的进程通讯(本文) 微服务架构中的...

3086

扫码关注云+社区

领取腾讯云代金券