首页 > 代码库 > sphinx使用笔记
sphinx使用笔记
一.sphinx简介
Sphinx 是用 Python 编写的,并且最初是为 Python 语言文档而创建,默认情况下,Sphinx 会为 Python 突出显示代码,但它还允许定义其他编程语言,比如 C 和 Ruby。
有很多开源工程都采用sphinx作为文档生成系统,最有名的就是 python官方文档 。 在 sphinx官方 网站 上也列出使用sphinx的项目,有将近90个左右,其中不乏大名鼎鼎的开源项目。
一些中文的翻译项目也采用了sphinx,如 pymotwcn 。
二.sphinx的安装和配置
1. 安装python
- python2.5或者 2.6,2.7都可以。
- 如果是windows平台,推荐下载 ActivePython
- 其他平台可以直接下载 python官方版本
2. 要确认已经安装了setuptools
- 如果已经安装,你在python安装路径下的Scripts文件夹下会找到一个easy_install.exe。
- setuptools下载
3. 在命令行输入easy_install sphinx
- easy_install可以自动下载并安装sphinx以及它所依赖的其他模块。
- easy_install -U Sphinx
建议使用sphinx自带的配置工具sphinx-quickstart。 - 建立一个工程目录,比如D\:Note。 - 在该目录启动命令行,输入sphinx-quickstart
D:\Note>sphinx-quickstart
程序会提示输入一些选项,如输入根目录等。大部分使用默认选项,直接按回车即可。
- 需要指定的选项有:
分离source和build目录,方便管理
> Separate source and build directories (y/N) [n]: y指定工程名、作者名、版本号
The project name will occur in several places in the built documentation.
> Project name: Note
> Author name(s): LK
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]:* autodoc: automatically insert docstrings from modules (y/N) [n]: y
* viewcode: include links to the source code of documented Python objects (y/N) [n]:y
4. Be sure to create a makefile. It makes life simple.
- 完成后,可以看到Note目录下有以下目录和文件
- build目录 运行make命令后,生成的文件都在这个目录里面
- source目录 放置文档的源文件
- make.bat 批处理命令
- makefile
基本完成了,使用make html命令就可以生成html形式的文档了。如果make html不行,可以使用这个命令:sphinx-build -b html source build
文档标题
=====================
--------
子标题
--------
章节标题
========
http://sphinx-doc-zh.readthedocs.org/en/latest/rest.html rst入门中文介绍
http://www.osseye.com/?p=239 sphinx实时索引架构现实
http://codinn.com/projects/sphinx/view/contents.htmlphinx使用手册
http://wowubuntu.com/restructuredtext-sphinx.html 文档与笔记利器 reStructuredText 和 Sphinx
http://www.cnblogs.com/Lvkun/archive/2010/04/01/1702245.html使用sphinx记笔记
http://notes.yeshiwei.com/sphinx.html
http://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/使用 sphinx 制作简洁而又美观的文档
http://www.oschina.net/p/sphinx-doc
http://www.cosdiv.com/page/M0/S225/225320.html使用sphinx记笔记
sphinx使用笔记