概述

下文讲述使用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. postgres(pl/pgsql)

    复制后期看 https://www.cnblogs.com/stephen-liu74/archive/2012/06/06/2312759.html https://www.cnblogs.com/ ...

  2. 【iOS开发】创建单例的两种方法

    创建一个单例很多办法.我先列举一个苹果官方文档中的写法. [cpp] view plaincopy   static AccountManager *DefaultManager = nil; + ( ...

  3. [转] UnityVS(Visual Studio Tools For Unity)的安装与使用

    一些废话 Unity 的开发者们,尤其是微软系的Unity开发者们,用Mono是不是烦死了?你是不是跟我一样,用vs来写代码,用Mono来跟踪调试?好麻烦啊好麻烦. 也许你会说,傻逼你不会用Unity ...

  4. 【SSH】——两种添加jar包方式的比较

    [前言] 在开发过程中,我们对Eclipse或MyEclipse等IDE越来越熟悉了.在使用的过程中,小编了解到两种添加jar包的方式,今天给大家说下这两种方式的差别. 方法一: 将所需要的jar包拷 ...

  5. thymeleaf支持java8的日期实例

    一.实体 @Entity public class Customer { @Id @GenericGenerator(name="generator",strategy = &qu ...

  6. BZOJ 3224 Tyvj 1728 普通平衡树 | Splay 板子+SPlay详细讲解

    下面给出Splay的实现方法(复杂度证明什么的知道是 nlogn 就可以啦) 首先对于一颗可爱的二叉查找树,是不能保证最坏nlogn的复杂度(可以想象把一个升序序列插入) (二叉查找树保证左子树元素大 ...

  7. 容器(vector)、数组、new创建的动态数组,你到底用哪一个(执行效率分析)

    1.问题的提出 在没有了解vector之前,动态数组一般都是又new创建的.在了解vector后发现vector竟是那样方便好用,但方便的同时却是以牺牲执行效率为代价的.网上对vector和array ...

  8. ng4转义html

    https://stackoverflow.com/questions/31548311/angular-html-binding <div [innerHTML]="content& ...

  9. bzoj 4836 [Lydsy1704月赛]二元运算 分治FFT+生成函数

    [Lydsy1704月赛]二元运算 Time Limit: 8 Sec  Memory Limit: 128 MBSubmit: 577  Solved: 201[Submit][Status][Di ...

  10. scrapy 为每个pipeline配置spider

    在settings.py里面配置pipeline,这里的配置的pipeline会作用于所有的spider,我们可以为每一个spider配置不同的pipeline, 设置 Spider 的 custom ...