sphinx-python文档化
概述
下文讲述使用sphinx自动生成reStructuredText python API文档的简单过程。
配置流程
安装依赖
$ pip install sphinx blurb python-docs-theme
创建项目
$ mkdir demo
$ cd demo
# 自动生成配置文件
demo $ sphinx-quickstart
项目相关文件说明(以默认配置为例)
项目结构:
# demo/
conf.py
Makefile
make.bat
_build/
|--doctrees/
|--environment.pickle
|--index.doctree
|--html/
|--_sources/
|--_static/
index.html
...
_static/
_templates/
index.rst
其中index.rst是入口文件,sphinx生成文档的实质是根据配置遍历路径内文件并提取docstring进行渲染的过程,过程大致可划分为两步:第一步是根据conf.py配置启动文件,第二步是根据index.rst的指令渲染html文件。
假设项目的python源代码放置在app/目录下:
demo $ mkdir app
demo $ mkdir app/__init__.py
实现文件功能:
# demo/app/__init__.py
def run(host, port):
"""
run server on given host:port
:type host: str
:param host: server host
:type port: int
:param port: server port
:return app
"""
print('running on :{}:{}'.format(host, port))
return 0
配置文件
此时还sphinx还不知道原代码文档写在哪里,需要在index.rst文件中配置:
Welcome to sphinx-demo's documentation!
=======================================
.. toctree::
:maxdepth: 2
:caption: Contents:
API
====
.. automodule:: app
:members:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
配置的信息是API部分内容,这相当于告诉sphinx要生成该模块docstring的对应文档。
除了配置index.rst文档,还需要在conf.py中修改两个地方:添加导入路径和添加插件,这是由于sphinx默认只会从sys.path路径中执行导入操作,要让sphinx知道上述模块的路径,需要执行如下更改:
# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
...
extensions = [
'sphinx.ext.autodoc'
]
做到这一步,就可以执行文档生成操作:
demo $ make html .
# 或
demo $ sphinx-build . _build/
命令执行完毕就会在 _build/html下生成html文件,其中入口就是index.html。
总结
这就是python自动生成文档的步骤,更加深入的知识可以参考一下内容:
reStructureText文档
conf.py配置文件说明
sphinx-build命令
python文档化
sphinx-python文档化的更多相关文章
- python文档生成工具:pydoc、sphinx;django如何使用sphinx?
文档生成工具: 自带的pydoc,比较差 建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
- 使用Sphinx编写文档
操作系统 : Windows7_x64 Python 版本 : 2.7.10 Sphinx 版本 : 官方网址:http://sphinx-doc.org github地址: https://gith ...
- 基于 Python 官方 GitHub 构建 Python 文档
最近在学 Python,所以总是在看 Python 的官方文档, https://docs.python.org/2/ 因为祖传基因的影响,我总是喜欢把这些文档保存到本地,不过 Python 的文档实 ...
- 利用Sphinx编写文档
利用Sphinx编写文档 1.Sphinx简介和使用理由 ================= Sphinx是一个用Python语言编写而成的文档编写工具.用Sphinx编写文档的时候,用户只需要编写符 ...
- 使用Xcode HeaderDoc和Doxygen文档化你的Objective-C和Swift代码
在一个应用的整个开发过程中涉及到了无数的步骤.其中一些是应用的说明,图片的创作,应用的实现,和实现过后的测试阶段.写代码可能组成了这个过程的绝大部分,因为正是它给了应用生命,但是这样还不够,与它同等重 ...
- 利用未文档化API:RtlAdjustPrivilege 提权实现自动关机
这里主要是利用NTDLL.dll中未文档化的API: RtlAdjustPrivilege 来实现提权.自动关机的功能. RtlAdjustPrivilege定义如下: NTSTATUS RtlAdj ...
- 利用未文档化API:RtlGetNtVersionNumbers 获取系统版本号
问题一:Windows SDK 8.1版本中的VersionHelper.h文件当中没有IsWindows10ORGreater,所以当你用IsWindows8Point1ORGreater判断出版本 ...
- Effective Java 第三版——74. 文档化每个方法抛出的所有异常
Tips 书中的源代码地址:https://github.com/jbloch/effective-java-3e-source-code 注意,书中的有些代码里方法是基于Java 9 API中的,所 ...
- python 文档
python 文档 https://docs.python.org/2/library/index.html
随机推荐
- iOS-Hello World
尝试练习一些简单的app,能快速上手开发环境和开发流程.基础Start Developing iOS Apps (Swift)https://developer.apple.com/library/c ...
- winform构造函数和load事件
有些地方,有些代码写在构造函数里面运行不成功: 但是加在load事件里面运行成功: 有时候,反则反之.
- JVM内存区域配置
堆内存:新域+旧域 设置堆内存初始化大小 java -Xms128m 设置堆内存初始化大小128MB 设置堆内存最大大小 java -Xmx256m 设置堆内存最大256MB 通常将堆内存的初始化大小 ...
- 微服务日志监控与查询logstash + kafka + elasticsearch
使用 logstash + kafka + elasticsearch 实现日志监控 https://blog.csdn.net/github_39939645/article/details/788 ...
- P3032 [USACO11NOV]二进制数独Binary Sudoku
题目描述 Farmer John's cows like to play an interesting variant of the popular game of "Sudoku" ...
- 安装全局webpack
npm ls webpack 和npm ls webpack -g 查看本地和全局版本 npm install webpack@1.15.0 -g 全局 然后到项目里面 npm install npm ...
- 安徽师大附中%你赛day4T1 金字塔 解题报告
金字塔 题目背景: \(Zdrcl\)带着妹子们来到了胡夫金字塔周边旅游, 发现这里正在进行一个有关金字塔的游戏 题目描述: 游戏规则如下: 1. 这里的金字塔是一个 \(N\) 阶的二维金字塔. 2 ...
- 【BZOJ 2006】[NOI2010]超级钢琴 ST
我们先把所有最左端对应的最优右端入堆,eg: z 在[l,r](由题目给出的L,R决定)之间的最优解 y,然后出堆以后,再入堆z,y-1,z,y+1,那么我们只需要用st找最大前缀和就好了(ST是一 ...
- 用JavaScript写一个类似PHP print_r的函数
PHP print_r的函数很好用,可以用来打印数组.对象等的结构与数据,可惜JavaScript并没有原生提供类似的函数.不过我们可以试着自己来实现这个函数,下面提供一些方法与思路. 方法一 fun ...
- SQLMap的前世今生(Part1)
http://www.freebuf.com/sectool/77948.html 一.前言 谈到SQL注入,第一时间就会想到神器SQLMAP,SQLMap是一款用来检测与利用的SQL注入开源工具.那 ...