Sphinx写笔记¶

Sphinx写笔记体现在两个方面

能生成python项目里面代码的API文档，使用 sphinx-apidoc
能将手工编写的*.rst文件转换成html网页， make html

Sphinx配置¶

安装 Sphinx，使用 $ pip3 install Sphinx

为项目生成文档，使用 sphinx-quickstart ，本文中以 d:/project/pyDemo/doc 作为根目录这里生成的时候要注意，向导要求指定的根目录我喜欢在项目目录下建一个doc文档，专门放sphinx的相关文件。向导运行完毕后，我建立的文档结构如下

修改 doc/conf.py sys.path.insert(0, os.path.abspath('..'))

doc目录下的index.rst作为主页文件，人工按需要修改，修改成自己需要的样子，把各个*.rst串起来，形成一本笔记

在项目路径下执行（此处是 d:/project/pyDemo/ ) sphinx-apidoc -o ./doc . 生成api文档（rst格式）,不要遗忘最后的点，表示当前项目目录下寻找代码模块并生成API文档如果不需要生成API文档，此步可以跳过

将rst文件转换生成html网页文件，在项目路的文档径下执行如下命令（此处是 d:/project/pyDemo/doc) make html

Sphinx语法参考¶

http://pm.readthedocs.org/doc/sphinx.html#id11

http://sphinx-doc-zh.readthedocs.org/en/latest/contents.html

http://jwch.sdut.edu.cn/book/tool/UseSphinx.html

http://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs

http://ju.outofmemory.cn/entry/64265