环境准备

什么是reStructuredText

维基百科:

reStructuredText是扩展名为.rst的纯文本文件，含义为‘重新构建的文本’，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

—来自维基百科

提示

由于reStructuredText是由python项目发起，所以要使用它需要依赖python环境。

简单中文文档

http://www.pythondoc.com/sphinx/rest.html

https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html

最全英文文档

高级用法在英文文档中才能找到

http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

http://docutils.sourceforge.net/rst.html

辅助工具

可视化工具生成表格

https://www.tablesgenerator.com/text_tables

可视化公式工具

python 环境准备

除了安装python外，还需要安装几个python的包。

pip install pandoc doc8 docutils pylint sphinx

docutils

python语言编写的一个开源文本文档处理工具，也是reStructuredText的创造者。 其主要功能是把plaintext documentation转化成 HTML, LaTeX, man-pages, open-document or XML。

提示

Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, open-document or XML. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language.

官方网站:

http://docutils.sourceforge.net/

pandoc

维基百科:

Pandoc是由John MacFarlane开发的标记语言转换工具，可实现不同标记语言间的格式转换，堪称该领域中的“瑞士军刀”[3]。 Pandoc使用Haskell语言编写，以命令行形式实现与用户的交互，可支持多种操作系统；Pandoc采用GNU GPL授权协议发布，属于自由软件。

Pandoc可读取的源格式	Pandoc可生成的目标格式
Markdown reStructuredText textile HTML DocBook LaTeX MediaWiki标记语言 OPML Org-Mode Haddock	HTML格式：包括XHTML，HTML5及HTML slide 文字处理软件格式：包括docx、odt、OpenDocument XML 电子书格式：包括EPUB（第2版及第3版）、FictionBook2 技术文档格式：包括DocBook、GNU TexInfo、Groff manpages、Haddock 页面布局格式：InDesign ICML 大纲处理标记语言格式：OPML TeX格式：包括LaTeX、ConTeXt、LaTeX Beamer PDF格式：需要LaTeX支持 轻量级标记语言格式：包括Markdown、reStructuredText、textile、Org-Mode、MediaWiki标记语言、AsciiDoc 自定义格式：可使用lua自定义转换规则

官方网站:

https://pandoc.org/

sphinx

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

• 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本

• 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息

• 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章

• 美观的自动索引: 可自动生成美观的模块索引

• 精确的语法高亮: 基于 Pygments 自动生成语法高亮

• 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.

提示

• reStructuredText 是一种标记语言，可以编写文本文档。

• docutils 是处理reStructuredText工具包，可以把reStructuredText编写的文档转换HTML、XML等。

• Sphinx 是文档工具，用于大型文档、书记编写，背后使用reStructuredText和docutils。

官方文档:

http://www.sphinx-doc.org/en/master/

中文文档:

https://zh-sphinx-doc.readthedocs.io/en/latest/

pylint

pylint是一个Python代码风格的检查工具, 它依据的标准是Guido van Rossum的PEP8。它分析 Python 代码中的错误，查找不符合代码风格标准和有潜在问题的代码。

官方文档:

https://www.pylint.org/

doc8

Doc8 is an opinionated style checker for rst (with basic support for plain text) styles of documentation.

编写rst的IDE

vs code

安装插件

这个插件依赖python，需要电脑上有python

reStructuredText Language Support for Visual Studio Code

插件文档

https://docs.restructuredtext.net/index.html

配置vscode的python环境

https://code.visualstudio.com/docs/python/settings-reference

编译sphinx

阅读结果

pycharm

安装插件

安装rst插件

编译sphinx

编译sphinx项目，生成HTML

阅读结果

坑王之王

编译结果路径

用命令 make html 编译和使用pycharm编译产出的结果路径是不一样的。 注意区分！！！！！

图片文件不能重名

因为在编译成html时，会把所有图片自动放到{build_dir}_static目录中，如果两张图片（即使在不同目录中）重名发覆盖。