概述

下文讲述使用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文档化的更多相关文章

  1. python文档生成工具:pydoc、sphinx;django如何使用sphinx?

    文档生成工具: 自带的pydoc,比较差 建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...

  2. 使用Sphinx编写文档

    操作系统 : Windows7_x64 Python 版本 : 2.7.10 Sphinx 版本 : 官方网址:http://sphinx-doc.org github地址: https://gith ...

  3. 基于 Python 官方 GitHub 构建 Python 文档

    最近在学 Python,所以总是在看 Python 的官方文档, https://docs.python.org/2/ 因为祖传基因的影响,我总是喜欢把这些文档保存到本地,不过 Python 的文档实 ...

  4. 利用Sphinx编写文档

    利用Sphinx编写文档 1.Sphinx简介和使用理由 ================= Sphinx是一个用Python语言编写而成的文档编写工具.用Sphinx编写文档的时候,用户只需要编写符 ...

  5. 使用Xcode HeaderDoc和Doxygen文档化你的Objective-C和Swift代码

    在一个应用的整个开发过程中涉及到了无数的步骤.其中一些是应用的说明,图片的创作,应用的实现,和实现过后的测试阶段.写代码可能组成了这个过程的绝大部分,因为正是它给了应用生命,但是这样还不够,与它同等重 ...

  6. 利用未文档化API:RtlAdjustPrivilege 提权实现自动关机

    这里主要是利用NTDLL.dll中未文档化的API: RtlAdjustPrivilege 来实现提权.自动关机的功能. RtlAdjustPrivilege定义如下: NTSTATUS RtlAdj ...

  7. 利用未文档化API:RtlGetNtVersionNumbers 获取系统版本号

    问题一:Windows SDK 8.1版本中的VersionHelper.h文件当中没有IsWindows10ORGreater,所以当你用IsWindows8Point1ORGreater判断出版本 ...

  8. Effective Java 第三版——74. 文档化每个方法抛出的所有异常

    Tips 书中的源代码地址:https://github.com/jbloch/effective-java-3e-source-code 注意,书中的有些代码里方法是基于Java 9 API中的,所 ...

  9. python 文档

    python 文档 https://docs.python.org/2/library/index.html

随机推荐

  1. iOS-Hello World

    尝试练习一些简单的app,能快速上手开发环境和开发流程.基础Start Developing iOS Apps (Swift)https://developer.apple.com/library/c ...

  2. winform构造函数和load事件

    有些地方,有些代码写在构造函数里面运行不成功: 但是加在load事件里面运行成功: 有时候,反则反之.

  3. JVM内存区域配置

    堆内存:新域+旧域 设置堆内存初始化大小 java -Xms128m 设置堆内存初始化大小128MB 设置堆内存最大大小 java -Xmx256m 设置堆内存最大256MB 通常将堆内存的初始化大小 ...

  4. 微服务日志监控与查询logstash + kafka + elasticsearch

    使用 logstash + kafka + elasticsearch 实现日志监控 https://blog.csdn.net/github_39939645/article/details/788 ...

  5. P3032 [USACO11NOV]二进制数独Binary Sudoku

    题目描述 Farmer John's cows like to play an interesting variant of the popular game of "Sudoku" ...

  6. 安装全局webpack

    npm ls webpack 和npm ls webpack -g 查看本地和全局版本 npm install webpack@1.15.0 -g 全局 然后到项目里面 npm install npm ...

  7. 安徽师大附中%你赛day4T1 金字塔 解题报告

    金字塔 题目背景: \(Zdrcl\)带着妹子们来到了胡夫金字塔周边旅游, 发现这里正在进行一个有关金字塔的游戏 题目描述: 游戏规则如下: 1. 这里的金字塔是一个 \(N\) 阶的二维金字塔. 2 ...

  8. 【BZOJ 2006】[NOI2010]超级钢琴 ST

    我们先把所有最左端对应的最优右端入堆,eg: z  在[l,r](由题目给出的L,R决定)之间的最优解 y,然后出堆以后,再入堆z,y-1,z,y+1,那么我们只需要用st找最大前缀和就好了(ST是一 ...

  9. 用JavaScript写一个类似PHP print_r的函数

    PHP print_r的函数很好用,可以用来打印数组.对象等的结构与数据,可惜JavaScript并没有原生提供类似的函数.不过我们可以试着自己来实现这个函数,下面提供一些方法与思路. 方法一 fun ...

  10. SQLMap的前世今生(Part1)

    http://www.freebuf.com/sectool/77948.html 一.前言 谈到SQL注入,第一时间就会想到神器SQLMAP,SQLMap是一款用来检测与利用的SQL注入开源工具.那 ...