用斯芬克斯写文档

http://sphinx.pocoo.org/_static/sphinx.png

huliuhe <huliuhe@gmail.com>
reply-to        python-cn@googlegroups.com
to      python-cn@googlegroups.com
date    Thu, Dec 18, 2008 at 11:08
subject [CPyUG:73991] 用sphinx写文档(1)

传说中的智慧生物~Sphinx 狮身人面兽,被行者们训服为文档工厂了!

所需软件

安装上述软件,把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_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 里面是一些设置。可以更改,暂时不用管它。

目录
==========

.. Toctree::
    :maxdepth: 2

    childdir/index.rst
    faq.rst

在src目录下新建faq.rst 文件,并保存为utf8格式。 在src目录下新建 childdir 目录。在气内见index.rst 和test.rst 文件。

==========================
FAQ
==========================



T1
=========

    * python 2.5
    * pywin32(与2.5 版本相匹配的)


T2
================================

ABC

11111
-----

child 目录
==========

.. Toctree::
    :maxdepth: 2

    test.rst

===========
test
===========

A1
=====

这个麻烦。
a1.1
------

测试1

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 就可以看到刚才写的文档了。下面是个截屏。

sphinx-c7ebf365c345d3edf736544b.jpg

体验


反馈

创建 by -- ZoomQuiet [2008-12-18 03:57:15]

DocumentUsageSphinx (last edited 2009-12-31 02:55:32 by ZoomQuiet)