用斯芬克斯写文档
huliuhe <[email protected]> reply-to [email protected] to [email protected] date Thu, Dec 18, 2008 at 11:08 subject [CPyUG:73991] 用sphinx写文档（1）
传说中的智慧生物~Sphinx 狮身人面兽，被行者们训服为文档工厂了！
所需软件
- python
- docutils
安装上述软件，把Python25/Scripts 的路径加到windows的path中。
demo示例
新建文件夹 sphinx_demo， 命令行下执行如下命令:
[f:\all_blog\sphix_about\sphinx_demo]sphinx-quickstart.exe Welcome to the Sphinx quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). > Root path for the documentation [.]: src
输入src 表示文档的源文件放在src目录，:
You have two options for placing the build directory for Sphinx output. Either, you use a directory ".build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/N) [n]:
直接回车，默认就好
Inside the root directory, two more directories will be created; ".templates" for custom HTML templates and ".static" for custom stylesheets and other static files. Since the leading dot may be inconvenient for Windows users, you can enter another prefix (such as "_") to replace the dot. > Name prefix for templates and static dir [.]:
直接回车，默认就好
The project name will occur in several places in the built documentation. > Project name: mydoc_demo
输入项目名称
> Author name(s): huliuhe
作者名称
Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version: 0.1
版本号
> Project release [0.1]:
直接回车
The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]:
文档源文件后缀名，根据个人喜好设置。这里直接回车
One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]:
直接回车 ,表示生成index文件。
Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/N) [n]:
直接回车
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
直接回车
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]
回车
If you are under Unix, a Makefile can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [n]:
不生成 makefile ，回车
If you are under Unix, a Makefile can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [n]:
ok 准备工作完成。
- 这个时候，你会发现[f:all_blogsphix_aboutsphinx_demo] 目录下生成 src 目录 。
[f:\all_blog\sphix_about\sphinx_demo]cd src
[f:\all_blog\sphix_about\sphinx_demo\src]dir
Volume in drive F is STUDY Serial number is 71BF:9DA7
Directory of F:\all_blog\sphix_about\sphinx_demo\src\*
2008-12-18 10:25 <DIR> .
2008-12-18 10:25 <DIR> ..
2008-12-18 10:25 <DIR> .build
2008-12-18 10:25 <DIR> .static
2008-12-18 10:25 <DIR> .templates
2008-12-18 10:25 6,101 conf.py
2008-12-18 10:25 449 index.rst
6,550 bytes in 2 files and 5 dirs 16,384 bytes allocated
1,816,387,584 bytes free
其中conf.py 里面是一些设置。可以更改，暂时不用管它。
- 打开index.rst 输入一下内容
目录
==========
.. Toctree::
:maxdepth: 2
childdir/index.rst
faq.rst
在src目录下新建faq.rst 文件，并保存为utf8格式。 在src目录下新建 childdir 目录。在气内见index.rst 和test.rst 文件。
- faq.rst 输入一下内容
==========================
FAQ
==========================
T1
=========
* python 2.5
* pywin32(与2.5 版本相匹配的)
T2
================================
ABC
11111
-----
- 在 childdir/index.rst 内输入一下内容
child 目录
==========
.. Toctree::
:maxdepth: 2
test.rst
- 在 childdir/test.rst 内输入如下内容
=========== test =========== A1 ===== 这个麻烦。 a1.1 ------ 测试1
- 在sphinx_demo目录下新建build.bat 文件。内容如下
sphinx-build -b html src output
执行命令:
[f:\all_blog\sphix_about\sphinx_demo]build sphinx-build -b html src output Making output directory... Sphinx v0.5, building html loading pickled environment... not found building [html]: targets for 4 source files that are out of date updating environment: 4 added, 0 changed, 0 removed reading sources... childdir/index childdir/test faq index pickling environment... done checking consistency... done preparing documents... done writing output... childdir/index childdir/test faq index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded.
ok 这个时候打开output的index.html 就可以看到刚才写的文档了。下面是个截屏。
体验
- reST不支持多个文档连接，或者把一个文档输出多个文件。
- Sphinx自定义了指令，用于表示组成文档的多个文件间的关系。
- 其中目录 指令 toctree 是关键。 上述只是简单输入 html文档，还可以输出多种格式。pdf，tex等。
反馈
创建 by -- ZoomQuiet [2008-12-18 03:57:15]