sphinx使用笔记

一.sphinx简介

 

Sphinx简单来说，是一个文档生成工具。用于把reStructuredText 格式的源文件生成诸如HTML, PDF, LaTex一类的格式。编辑者无须亲自处理文本的格式, 程序会自动根据源文件里的设置产生格式, 以及自动生成章节链接等工作。

 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自带的配置工具sphinx-quickstart。 - 建立一个工程目录，比如D\:Note。 - 在该目录启动命令行，输入sphinx-quickstart

D:\Note>sphinx-quickstart

• 程序会提示输入一些选项，如输入根目录等。大部分使用默认选项，直接按回车即可。

• 需要指定的选项有：

  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.  *  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://docutils.sourceforge.net/docs/user/rst/quickref.html

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

 

 

1.标题

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

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

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

 

 

2.段落

1）空一行可以分段

2）同一段落的内容，需要左对齐（即同级缩进）

 

3.换行且在每行前加一个小圆点，且缩进

减号空格文字即 - 文字

 

4. 超链接

1链接主要包括以下几种

独立链接 ， reStructured^Text 会自动将网址转换为链接。

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

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

 

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

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

例如 Ubuntu

Ubuntu_

 

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

如果链接名中出现空格和标点符号，可以使用 ` 将链接名包裹起来

`Ubuntu cn`_

 

.. _`Ubuntu cn`: http://www.ubuntu.org.cn/

 

无名链接 ，不使用链接名的链接

主要用于将大段文字转换为链接。如果将这部分文字作为链接名，链接名也将被写进注释中……

`主要用于将大段文字转换为链接。如果将这部分文字作为链接名，

链接名也将被写进注释中……`__

 

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

 

无名链接经常与命名链接一起使用

`这里是一大段文字………………`__

 

__ 一个命名链接_

可以在任意位置定义这个命名链接

.. _一个命名链接:

 

锚点 ，链接的目标地址留空，可以在当前位置标记锚点。

跳转到 锚点_

 

.. _锚点:

 

<页面位置>

点击锚点名称跳转到锚点标记处。

 

标题链接 ，跳转到文章内部的标题

reStructured^Text定义标题的同时，还定义了一个标题链接，在正文中使用 标题名称_ 可以跳转相应标题

标题名称

========

 

跳转到 标题名称_

 

嵌入式链接 ，链接目标嵌入到链接中。(reStructured^Text 中没有通过，不建议使用)

`Ubuntu <http://www.ubuntu.org.cn>`_

 

 

 

参考网站：

 

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记笔记