使用Sphinx构建Python程序文档
Last updated
Was this helpful?
Last updated
Was this helpful?
最初是作为Python代码文档自动生成工具,现在也开始支持C/C++,以及计划支持更多语言程序文档的创建。由于文档撰写格式优雅,逐渐作为技术文档的撰写平台使用。
Sphinx使用Python编写,并且支持Python 3.5+。
For Python 2:
For Python 3:
参考
For Python 2:
For Python 3:
在CentOS如果同时安装了python 2和python 3,则会有pip2
和pip3
,都可以安装各自的virtualenv
。不过,系统只有一个/usr/local/bin/virtualenv
,这个工具有一个参数-p PYTHON_EXE, --python=PYTHON_EXE
可以用来指定Python解析器,例如 --python=python3.5
。默认是使用/bin/python3.6
。
在macOS上安装了Python官方的macOS版本Python 3.7,则会在用户目录下~/.bash_profile
添加路径,确保首先调用Python3.7
此时执行virtualenv
则会执行/Library/Frameworks/Python.framework/Versions/3.7/bin/virtualenv
确保生成的是Python 3的虚拟环境
以下实践在Mac OS X上完成,基本方法和Linux类似
Mac OS X 已经自带了python,不过没有安装pip
,需要先通过easy_install
安装pip
,进而安装sphinx-doc
以下是macOS + Python 3.7 执行:(参考官方安装方法)
安装
sphinx
需要root权限,否则无法写入/Library/Python/2.7/site-packages
目录
在mac上安装遇到报错
跳过uninstall系统级别的site-packages:
保护系统文件目录的内容和文件权限
保护进程不被代码注入,运行时附加(类似debugging)和DTrace
拒绝没有签名的内核扩展
通过添加一个扩展的文件属性,或者通过将文件或目录加入到/System/Library/Security/rootless.conf
来设置保护属性。保护的目录包括 /System
, /bin
, /sbin
, /usr
。以及从/etc
, /tmp
, var
符号链接到/private/etc
, /private/tmp
和 /private/var
来实现保护。
系统完整性保护只有在系统分区之外才能整个或部分禁止。Apple在recovery system或从安装盘启动时候提供的终端窗口中,可以执行csrutil
命令行工具。安装macOS时候,installer将任何位于标记为系统目录中的组件移动到/Library/SystemMigration/History/Migration-[some UUID]/QuarantineRoot/
。通过保护系统目录,系统文件和目录只能在Apple软件更新的时候自动维护。所以,这种权限修复没有在Disk Utility和相应的diskutil操作中提供。
可以通过git方式下载源代码,并且从不同的tag获取对应版本的内核源代码(包括文档)
生成文档
输出的文档内容位于Documentation/output
目录下,可以通过浏览器浏览。
由于我对内核部分文档比较感兴趣,所以准备做一些选译,则采用如下方法复制出部分文档目录:
这样就可以使用如下命令来构建文档:
输出的文档位于 output
子目录,可以很方便做文档翻译。
在 项目
目录下创建一个文档目录,例如在源代码目录下创建一个 docs
目录
在文档目录 docs
下执行
在提示
separate the source and build directories
回答y
在提示
autodoc extension
回答y
完成上述初始化后目录结构类似
只需要修改 config.py
配置
通过 autodoc
可以告知 Sphinx 查看 docstrings 并生成项目的文档。
首先打开 docs/source/conf.py
文件修改配置
这里设置路径是
../..
表示从source/
目录开始往上2级才是代码程序项目目录
一个 mymodule.py
案例
然后执行
测试会自动生成
然后就可以根据自动生成的程序模块来构建html文档
使用浏览器打开 docs/build/html/index.html
阅读文档,也可以同步到web网站提供访问。
比上述使用autodoc
要简单一些,只要执行一次
参考
注意:如果直接通过下载安装 macOS 64-bit installer
,则会直接提供 pip
(当前已经不再推荐使用easy_install来安装pip了,因为高版本Python已经自带pip来取代easy_install)
这个报错在 有解释和解决方法:
报错原因是Mac OS X EI Capitan或更高版本已经安装了six 1.4.1,当通过pip
安装新版本时会尝试卸载旧版本。但是从 EI Capitan 版本开始,Mac OS X引入了一个称为系统完整性保护的功能。也称为rootless
,这是通过内核提供的一种机制,保护系统所属的文件目录不被没有特别授权的进程修改,甚至连root用户或root权限用户(sudo)都不能修改。Apple这样设计操作系统是是为了避免明显的系统机制的安全,特别是单个用户具备了administrator权限的环境。默认启用了系统完整性保护,提供了以下机制:
参考
Linux Kernel Documents使用了sphinx来构建,请参考指导文档
注意:一定要在内核源代码根目录下执行上述make htmldocs
命令。不要在Documentation
子目录下执行,否则会报错(参考 ):
注意:Linux Kernel Documentation使用了sphinx 1.4.9,其中有语法和最新版本不兼容。所以在部署到 网站时候,需要使用 Advanced Settings
,指定 Requirements files: sphinx/requirements.txt
,以及指定 Python configuration file: conf.py
,否则会导致编译错误。
可以选择 作为基础文档风格