代码改变世界

使用sphinx记笔记

2010-04-01 15:33  lvkun  阅读(9885)  评论(7)  编辑  收藏  举报

sphinx简介

简单来说，这是一个基于ReStructuredText的文档生成工具。方便易用，功能强大。

有很多开源工程都采用sphinx作为文档生成系统，最有名的就是 python官方文档 。 在 sphinx官方 网站 上也列出使用sphinx的项目，有将近90个左右，其中不乏大名鼎鼎的开源项目。

一些中文的翻译项目也采用了sphinx，如 pymotwcn 。

 

安装

1. 安装python

2. 要确认已经安装了setuptools

  • 如果已经安装，你在python安装路径下的Scripts文件夹下会找到一个easy_install.exe。
  • setuptools下载

3. 在命令行输入easy_install sphinx

  • easy_install可以自动下载并安装sphinx以及它所依赖的其他模块。

 

建立sphinx工程

建议使用sphinx自带的配置工具sphinx-quickstart。 - 建立一个工程目录，比如D\:Note。 - 在该目录启动命令行，输入sphinx-quickstart

D:\Note>sphinx-quickstart

  • 程序会提示输入一些选项，如输入根目录

    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).

    Enter the root path     for documentation.
    > Root path for the documentation [.]:
    大部分使用默认选项，直接按回车即可。
  • 需要指定的选项

    1. 分离source和build目录，方便管理

      > Separate source and build directories (y/N) [n]: y

    2. 指定工程名、作者名、版本号

      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]:


    3. 文档文件的后缀名，默认是.rst，个人认为用.txt更方便些。

      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]: .txt


  • 完成后，可以看到Note目录下有以下目录和文件
    • build目录 运行make命令后，生成的文件都在这个目录里面
    • source目录 放置文档的源文件
    • make.bat 批处理命令
    • makefile

  • 基本完成了，使用make html命令就可以生成html形式的文档了。

配置（conf.py）

conf.py文件包含了sphinx工程的所有配置选项，包括一些无法在sphinx-quickstart中进行设置的。

分为三部分：
  • General configuration（一般选项）
  • Options for HTML output（HTML输出选项）
  • Options for LaTeX output（Latex输出选项）

下面是一些常用的选项：

  • language （语言）

    对应于sphinx的locale目录下的文件夹，里面是本地化配置。

    官方版本只支持繁体中文（zh_TW）,可以下载 sphinx简体中文包 （javaEye topman制作）

    下载后放到locale目录下，然后language选项修改为zh_CN即可

  • html_theme （输出html的主题）:

    # The theme to use for HTML and HTML Help pages.  Major themes that come with
    #     Sphinx are currently 'default' and 'sphinxdoc'.
    html_theme = 'sphinxdoc'


常用的文档格式符号

下面只是列出了一些常用的格式符号，以供大家参考，详细的教程可以参照《reStructuredText 简明教程》 （以下基本上是从该教程直接引用过来的）。

标题

ReStructuredText会根据下划线读取文档的标题，并且可以自动组织索引

=====================
文档标题
=====================

--------
子标题
--------

章节标题
========

...

列表

列表中，相同的层级使用相同的缩进。

列表中同一层级不需要空行分隔。不同层级起始处必须有空行。

列表：
  - 条目
  - 条目

      - 条目
      - 条目
  - 条目

超链接

 

独立链接 ，自动将网址转换为链接。

例如 http://www.ubuntu.org.cn/

 

http://www.ubuntu.org.cn/ 

 

命名链接 ，为链接命名，有助记忆和减少空间占用。

在正文中使用 <链接名>_ ，注释中使用 _<链接名>: [链接目标]

例如 Ubuntu
Ubuntu_

.. _Ubuntu:  http://www.ubuntu.org.cn/

 

代码

sphinx对嵌入程序代码的支持很好（本来就是为了编写python文档而开发的工具）。

在段落的结尾添加符号 :: ，则表明下面的段落为代码段落。代码段落相对之前的段落要缩进一次。

文本

只要没有空行，不管换多少次行，都会处理为一行。 建议您将每行的内容控制在50个汉字或者100个字母之内， 尽量在标点符号处手动换行，以增加源文件的可读性。

其他

暂时没有发现支持ReStructuredText的Blog，不知道大家有没有知道的。如果能直接用ReStructuredText写Blog 就太好了。