ODL学习利器－DOCS文档编译及使用

前言

最近在学习odl控制器，总觉得他的资料不是很全面看的也比较累，后来摸索后发现原来还是自己不大会使用其提供的帮助文档。每个odl工程里面都有一个ｄｏｃｓ目录，最开始接触这些的时候还不明所以（对于python了解不深），真的深入学习起来才发现ｄｏｃｓ才是学习的利器，把文章留在这里给那些求文档而不得的新手，让他们少走些弯路，如果你真的想深入了解ｏｄｌ，先编译好每个项目的docs目录，生成帮助文档，然后在开启一段学习之旅！

１ RST文件说明

rst是一种轻量级标记语言，利于多人协同写作。

可以借助Docutils对rst进行文档处理，从conf.py中提取信息，解析转化成我们熟悉的文档格式，如html或者pdf。

该新结构化标记语言是用来存储代码序列和数据段中保存在RST扩展文本文档。

这意味着这些RST文件的内容包括文本块，通过格式化谁创造了RST文件中的用户输入的属性和造型特征。

rst之于python类似于javadoc之于java;

2 Sphinx–RST文档转换

Sphinx是一个Python的自动文档生成工具，可以自动的把docstring转换为文档，它支持多种格式的文档输出,包括html、pdf等，我们上文提到odl 的docs目录就需要此工具进行帮助html文档的输出。

2.1 Sphinx安装

#安装pip3
sudo apt install python3-pip
#pip3　安装　Sphinx
pip3 install Sphinx

2.2 Sphinx生成文档

sphinx-build -b html <srcDir> <dstDir>
sphinx-build -b html docs/ doc_build/

2.3 Sphinx项目创建

mkdir yourdir
cd yourdir
sphinx-quickstart

生成默认目录如图所示:

- yourdir/ # 刚才新建的目录
    - source/ # 存放Sphinx工程源码
    - build/ # 存放生成的文档
    Makefile

2.4 Sphinx生成目录简介

source/目录里有两个文件，分别是conf.py和index.rst，下面对它们进行进一步的介绍：

index.rst

.rst是reStructuredText，和Markdown一样是一种标记语言，，index.rst实际上被转换为build/html/index.html，而实际上在rst文档内你可以写任何东西，最后这些都会被转换到输出文档中。

conf.py

这是运行sphinx生成文档时会加载的配置，你可以通过对它进行修改来改变生成文档的行为。

3 学习链接

中文指引学习：

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

官网：

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

4 总结

这里并没有完整的梳理ｒｓｔ标记语言的总体结构，如果以后有机会再加以整理，知识的整理本就是不断学习和不断进步的过程，因为最近的重点是ｏｄｌ就不再过多打岔了，够用就行。希望这里的指引能真的给予ｏｄｌ的学习一定帮助，我也坚信如此。工欲善其事必先利其器，希望未来自己总结更多这要的小方便，帮助自己也帮助更多人！