用Sphinx记笔记

Sphinx简介

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

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

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

安装

建立sphinx工程

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

D:\Note>sphinx-quickstart

配置(conf.py)

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

分为三部分:

下面是一些常用的选项:

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

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

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

常用的文档格式符号

下面只是列出了一些常用的格式符号,以供大家参考,详细的教程可以参照《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就太好了。

参考教程

A ReStructuredText Primer