用Sphinx编写技术文档

大家会发现,如果一个项目主要是用Python写的,其文档都很类似,比如:Python在线的HTML官方手册。这些项目的文档都来源于一个很不错的项目:Sphinx。这个Sphinx特指Sphinx doc这个项目(另一个也叫Sphinx的search的项目,虽然都叫一个名字)。

官网:http://sphinx-doc.org/

以下出现Sphinx的地方,都特指Sphinx doc这个项目

使用场景

  • 很多开源Python库项目的API手册都是用这个写的,可以看Sphinx官网给的链接:http://sphinx-doc.org/examples.html
  • 如果是用Python写的商业软件,也可以用这个来写技术文档,纯文本管理研发文档,保证功能代码、测试代码、相关文档同时更新
  • 直接拿来写在线书。比如,这个《软件构建实践系列》就是:https://github.com/akun/pm
  • 直接用来做slide等演示幻灯片,从一定程度上替代PowerPoint。比如,http://example.zhengkun.info/slide.html

功能

这里就列举个人关心的几个特性:

  • 文本是rst格式语法
  • 生成HTML、PDF、Slide(需要插件)等格式的文档
  • 支持文档、代码等引用
  • 支持自定义样式
  • 支持插件扩展
  • 直接看官网手册了解更多:http://sphinx-doc.org/contents.html

语法简介

就是rst的语法,这里就列举几个常用的:

标题等级

rst如下:

一级标题
========

二级标题
--------

三级标题
^^^^^^^^

效果如下:

习惯上,可以用以下字符:“= - ` : ‘ ” ~ ^ _ * + # < >”。最好能约定个依次标题等级。

列表

rst如下:

* 列表1
* 列表2
* 列表3

效果如下:

  • 列表1
  • 列表2
  • 列表3

列表写法除了用“*”,还可以用:“-”,“+”,最后效果一样。

上面说的是无序列表,如果想用有序列表,可以用“#.”。

rst如下:

#. 列表1
#. 列表2
#. 列表3

效果如下:

  1. 列表1
  2. 列表2
  3. 列表3

表格

rst如下:

=====  =====  =====
第1列  第2列  第3列
=====  =====  =====
8      1      6
3      5      7
4      9      2
=====  =====  =====

效果如下:

第1列 第2列 第3列
8 1 6
3 5 7
4 9 2

插入图片

rst如下:

.. image:: images/ball1.gif

效果如下:

../_images/ball1.gif

插入代码

展示代码示例,经常会用到:

默认

rst如下:

::

   print 'Hello World!'

效果如下:

print 'Hello World!'

自定义

rst如下:

.. code-block:: python
   :linenos:

   print 'Hello World!'

效果如下:

1
print 'Hello World!'

引用代码文件

rst如下:

.. literalinclude:: code/example.js
   :language: javascript
   :linenos:

效果如下:

1
2
3
$(document).ready(function () {
  console.log('ok!');
});

提供下载文件链接

直接下载该RST本身。

rst如下:

:download:`sphinx.rst <sphinx.rst>`

效果如下:

sphinx.rst

目录索引

example1对应sphinx.rst所在目录下的example1.rst文件,example2类似。

rst如下:

.. toctree::
   :maxdepth: 2

   example1
   example2

效果如下:

引用

可以用于跨rst文档间的内容互相引用。这里以本文档内为例。

rst如下:

.. _my-reference-label:

用Sphinx编写技术文档
====================

很长的文字内容

点击回到顶部, :ref:`my-reference-label`.

效果如下:

点击回到顶部, 用Sphinx编写技术文档.

文字效果

斜体

rst如下:

*斜体*

效果如下:

斜体

粗体

rst如下:

**粗体**

效果如下:

粗体

下标

斜杠是为了空格转义,最后显示无空格。

rst如下:

H\ :sub:`2`\ O

效果如下:

H2O

上标

rst如下:

E = mc\ :sup:`2`

效果如下:

E = mc2

参见

Hello World

根据上面的介绍,其实常用的语法不多,现在直接用下,自己感受下吧!

安装 & 初始化

常用Python安装方式,创建个文件夹,执行命令,按提示自己选择即可。

pip install Sphinx
mkdir docs
cd docs
sphinx-quickstart

根据提示输入相应参数即可,可以一路默认。

尝试编辑

编辑index.rst,只写入以下内容

用Sphinx编写技术文档
====================

使用场景
--------

生成HTML

很简单,默认支持就很好。

make html
python -m SimpleHTTPServer 9527

直接浏览器访问9527端口,就可以看到类似Python官方文档的效果。

生成PDF

麻烦些,需要依赖库,且需要简单修改下配置。

  1. 安装依赖库
pip install rst2pdf
  1. 编辑conf.py,增加或修改如下配置:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
extensions = ['rst2pdf.pdfbuilder']

# -- Options for PDF output --------------------------------------------------
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
#  dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.
pdf_documents = [
    ('index', u'WebSOC', u'WebSOC Documentation', u'WebSOC Team Knownsec'),
]
# A comma-separated list of custom stylesheets. Example:
#pdf_stylesheets = ['sphinx','kerning','a4']
pdf_stylesheets = ['chinese','a4']
# A list of folders to search for stylesheets. Example:
pdf_style_path = ['.', '_styles']
# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False
# A colon-separated list of folders to search for fonts. Example:
# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']
# Language to be used for hyphenation support
#pdf_language = "en_US"
# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
#pdf_fit_mode = "shrink"
# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 0
# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'
# Insert footnotes where they are defined instead of
# at the end.
#pdf_inline_footnotes = True
# verbosity level. 0 1 or 2
#pdf_verbosity = 0
# If false, no index is generated.
#pdf_use_index = True
# If false, no modindex is generated.
#pdf_use_modindex = True
# If false, no coverpage is generated.
#pdf_use_coverpage = True
# Name of the cover page template to use
#pdf_cover_template = 'sphinxcover.tmpl'
# Documents to append as an appendix to all manuals.
#pdf_appendices = []
# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False
# Set the default DPI for images
#pdf_default_dpi = 72
# Enable rst2pdf extension modules (default is only vectorpdf)
# you need vectorpdf if you want to use sphinx's graphviz support
#pdf_extensions = ['vectorpdf']
# Page template name for "regular" pages
#pdf_page_template = 'cutePage'
# Show Table Of Contents at the beginning?
#pdf_use_toc = True
# How many levels deep should the table of contents be?
pdf_toc_depth = 9999
# Add section number to section references
pdf_use_numbered_links = False
# Background images fitting mode
pdf_fit_background_mode = 'scale'
  1. 编辑Makefile,增加如下代码:

Linux下的Makefie:

1
2
3
4
pdf:
	$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) _build/pdf
	@echo
	@echo "Build finished. The PDF files are in _build/pdf."

Windows下的批处理:

1
2
3
4
5
6
if "%1" == "pdf" (
	%SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
	echo.
echo.Build finished. The PDF files are in %BUILDDIR%/pdf
	goto end
)
  1. 执行生成PDF
make pdf
python -m SimpleHTTPServer 9527

参见

有关PDF的更多配置,可以阅读这个文档:http://ralsina.me/static/manual.pdf

生成Slide

Slide就是我们常说的演示文档,如:Windows下的PowerPoint(PPT);Mac下Keynote等等。这里用Sphinx生成在线的HTML5形式的Slide,操作也相对简单,也是需要依赖库和简单修改下配置。

  1. 安装依赖库
pip install hieroglyph
  1. 编辑conf.py,修改如下配置:
1
extensions = ['hieroglyph']
  1. 编辑Makefile,增加如下代码:

Linux下的Makefie:

1
2
3
4
slides:
	$(SPHINXBUILD) -b slides $(ALLSPHINXOPTS) $(BUILDDIR)/slides
	@echo
	@echo "Build finished. The slides are in $(BUILDDIR)/slides."
  1. 执行生成Slides
make slides
python -m SimpleHTTPServer 9527

参见

有关Slide的更多信息,可以直接查看这个项目:https://github.com/nyergler/hieroglyph

自定义样式

直接拿来主义,直接用别人写的Trac的样式

  1. 复制样式文件到静态资源目录,比如,这里是:
cp tracsphinx.css _static/
  1. 编辑conf.py,增加或修改如下配置:
1
2
3
4
5
html_style = 'tracsphinx.css'

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'sphinxdoc'
  1. 执行生成HTML
make html
python -m SimpleHTTPServer 9527

直接浏览器访问9527端口,就可以看到类似Trac的官方样式效果。

汇总到一块

可以直接看Python项目模板:https://github.com/akun/aproject/只看docs目录即可。

这里提到的几个核心文件示例如下:

另外推荐一个服务:https://readthedocs.org/

如果你的项目研发文档用Sphinx写的,可以用来做文档的持续集成,相当方便。

这个《软件构建实践系列》就是用的这个服务。

最后

这是一篇很简单的项目推广文章,在自己的Python项目中把Sphinx用起来吧!

当然Sphinx不仅支持Python源码的Domain,而且支持C、C++、JavaScript等Domain,即使没有你所用的语言的Domain,它本身还支持写插件扩展,所以其它类型语言的项目也不妨用一下。