============================ 环境准备 ============================ 什么是reStructuredText ============================ 维基百科: reStructuredText是扩展名为.rst的纯文本文件，含义为‘重新构建的文本’，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。 -- 来自维基百科 .. Hint:: 由于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的包。 .. code-block:: shell pip install pandoc doc8 docutils pylint sphinx docutils ------------------ python语言编写的一个开源文本文档处理工具，也是reStructuredText的创造者。 其主要功能是把plaintext documentation转化成 HTML, LaTeX, man-pages, open-document or XML。 .. hint:: 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 | - HTML格式：包括XHTML，HTML5及HTML slide | | - reStructuredText | - 文字处理软件格式：包括docx、odt、OpenDocument XML | | - textile | - 电子书格式：包括EPUB（第2版及第3版）、FictionBook2 | | - HTML | - 技术文档格式：包括DocBook、GNU TexInfo、Groff manpages、Haddock | | - DocBook | - 页面布局格式：InDesign ICML | | - LaTeX | - 大纲处理标记语言格式：OPML | | - MediaWiki标记语言 | - TeX格式：包括LaTeX、ConTeXt、LaTeX Beamer | | - OPML | - PDF格式：需要LaTeX支持 | | - Org-Mode | - 轻量级标记语言格式：包括Markdown、reStructuredText、textile、Org-Mode、MediaWiki标记语言、AsciiDoc | | - Haddock | - 自定义格式：可使用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提供的分析，转换等多种工具. .. hint:: - 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: images/vscode_编译sphinx.png 阅读结果 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: images/查看最终文档.png pycharm -------------------------- 安装插件 ~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: images/pycharm_rst_plugin.png 安装rst插件 编译sphinx ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: images/pycharm创建sphinx工具链.png 编译sphinx项目，生成HTML 阅读结果 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: images/pycharm_打开html.png 坑王之王 =========================== 编译结果路径 ------------------ 用命令 `make html` 编译和使用pycharm编译产出的结果路径是不一样的。 注意区分！！！！！ 图片文件不能重名 ------------------ 因为在编译成html时，会把所有图片自动放到{build_dir}_static目录中，如果两张图片（即使在不同目录中）重名发覆盖。