Python有个自带的工具可以生成Python的项目文档叫pydoc,不过生成的 html 代码有一些丑陋不堪,看着有点杂乱,经常看到国外开源项目使用的 sphinx 文档很漂亮就在网上学习了一下生成方法,这里我们就讲一下python-Sphinx的使用。

Sphinx可以自动获取代码中的(''' ''' 注释),自动生成文档。

注意:此教程中,以工程根目录作为测试目录,实际使用中应该在文档目录中生成,请自行测试。

首先我们看一下生成效果 sphinx 效果图

首先 我们要安装 sphinx

pip install sphinx  

安装 sphinx 主题

pip install sphinx_rtd_theme  

在项目根目录运行 sphinx 生成指令:

(RST-test_venv) qinfeideiMac:RST-test qinfei$ sphinx-quickstart 
The project name will occur in several places in the built documentation.  
> Project name: RST-test
> Author name(s): qinfei
===========================
> Project version []: 1.0
> Project release [1.0]: 
===========================
> Project language [en]: zh_cn
===========================
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
===========================

上面是需要填写的地方,========代替的地方直接一路回车即可。

自此工程目录下面生成了一大堆东西,修改 conf.py:

把代码改成如下:

import os  
import sys  
# 手动添加下面一行
import sphinx_rtd_theme  
sys.path.insert(0, os.path.abspath('.'))  
# 请注意目录结构进行更改, 类的 rst 文件生成在上级目中,要添加下面一行
# 我在 python2.x 测试是这样的, python3.x 不用添加
sys.path.insert(0, os.path.abspath('..'))  

主题设定为:

html_theme = "sphinx_rtd_theme"  

注意不同版本目录结构不一样

然后运行(python 3.x):

sphinx-apidoc -o ./ ./  

请根据自己目录结构更改下面代码 source 代表目的目录

然后运行(python 2.x):

sphinx-apidoc -o ./source ./  

在 index.rst 中添加模块列表

.. toctree::
   :maxdepth: 2
   :caption: Contents:

改为:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules.rst

最后

make html  

即可在 根目录 > _build > html 生成 html 文件, 打开 index.html 即可看到整体文档。 sphinx 类视图

环境变量配置:

编程的时候,一些比较私密的信息我们会把它放在 环境变量里面,所以我们会在代码中用到类似:

SECRET_KEY = os.environ["SECRET_KEY"]  

的定义,这时候就要配置环境变量,pycharm 推荐设置方法: https://stackoverflow.com/a/22899916 ,我在使用中可能没有用好,设置好之后在命令行运行代码可以,但是在生成文档的时候并不太好用,所以我选择了设定 python venv 的环境变量,在 VENV_DIR/bin/activate 中设定。

编辑 VENV_DIR/bin/activate 添加变量:

export SECRET_KEY=#$%^YTUJHNGBFVDEW#$E%RYTUHRERT$%  

然后重启虚拟环境即可。

附件代码: RST-test.zip

生成 PDF 文档(这一段用的 python2.7环境):

修改 conf.py:

extensions = [  
    'sphinx.ext.autodoc',
    'rst2pdf.pdfbuilder',
]

pdf_documents = [('index', u'rst2pdf', u'项目名称', u'作者姓名'),]  

下面一段是 osx 的配置,不一定能用在 Linux 或者 Windows 上。

latex_elements = {  
'papersize': 'a4paper',  
'preamble': r'''  
\hypersetup{unicode=true}
\usepackage{CJKutf8}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\DeclareUnicodeCharacter{2203}{\ensuremath{\exists}}
\DeclareUnicodeCharacter{2286}{\ensuremath{\subseteq}}
\DeclareUnicodeCharacter{2713}{x}
\DeclareUnicodeCharacter{27FA}{\ensuremath{\Longleftrightarrow}}
\DeclareUnicodeCharacter{221A}{\ensuremath{\sqrt{}}}
\DeclareUnicodeCharacter{221B}{\ensuremath{\sqrt[3]{}}}
\DeclareUnicodeCharacter{2295}{\ensuremath{\oplus}}
\DeclareUnicodeCharacter{2297}{\ensuremath{\otimes}}
\begin{CJK}{UTF8}{gbsn}
\AtEndDocument{\end{CJK}}
'''  
}

添加如下配置:

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['a3', 'zh_CN']

# 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 = ['/Library/Fonts/']

# Language to be used for hyphenation support
pdf_language = "zh_CN"

# 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 = False

# If false, no modindex is generated.
pdf_use_modindex = False

# If false, no coverpage is generated.
# pdf_use_coverpage = True

# 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 = False

# How many levels deep should the table of contents be?
pdf_toc_depth = 2

# Add section number to section references
pdf_use_numbered_links = False

# Background images fitting mode
pdf_fit_background_mode = 'scale'  

安装需要安装的软件包:

sudo brew install texlive texlive-extras  
sudo brew install graphviz  

然后运行:

make latexpdf  

如果出现找不到 latexpdf 的情况,见:https://zhuanlan.zhihu.com/p/20257713?columnSlug=LaTeX

参考文档:

http://blog.csdn.net/xingwangc2014/article/details/52811177
http://seisman.info/chinese-support-for-sphinx.html
http://www.tongfamily.com/2013/04/installing-sphinx-on-mac-os/