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
随机推荐
- postgres(pl/pgsql)
复制后期看 https://www.cnblogs.com/stephen-liu74/archive/2012/06/06/2312759.html https://www.cnblogs.com/ ...
- 【iOS开发】创建单例的两种方法
创建一个单例很多办法.我先列举一个苹果官方文档中的写法. [cpp] view plaincopy static AccountManager *DefaultManager = nil; + ( ...
- [转] UnityVS(Visual Studio Tools For Unity)的安装与使用
一些废话 Unity 的开发者们,尤其是微软系的Unity开发者们,用Mono是不是烦死了?你是不是跟我一样,用vs来写代码,用Mono来跟踪调试?好麻烦啊好麻烦. 也许你会说,傻逼你不会用Unity ...
- 【SSH】——两种添加jar包方式的比较
[前言] 在开发过程中,我们对Eclipse或MyEclipse等IDE越来越熟悉了.在使用的过程中,小编了解到两种添加jar包的方式,今天给大家说下这两种方式的差别. 方法一: 将所需要的jar包拷 ...
- thymeleaf支持java8的日期实例
一.实体 @Entity public class Customer { @Id @GenericGenerator(name="generator",strategy = &qu ...
- BZOJ 3224 Tyvj 1728 普通平衡树 | Splay 板子+SPlay详细讲解
下面给出Splay的实现方法(复杂度证明什么的知道是 nlogn 就可以啦) 首先对于一颗可爱的二叉查找树,是不能保证最坏nlogn的复杂度(可以想象把一个升序序列插入) (二叉查找树保证左子树元素大 ...
- 容器(vector)、数组、new创建的动态数组,你到底用哪一个(执行效率分析)
1.问题的提出 在没有了解vector之前,动态数组一般都是又new创建的.在了解vector后发现vector竟是那样方便好用,但方便的同时却是以牺牲执行效率为代价的.网上对vector和array ...
- ng4转义html
https://stackoverflow.com/questions/31548311/angular-html-binding <div [innerHTML]="content& ...
- bzoj 4836 [Lydsy1704月赛]二元运算 分治FFT+生成函数
[Lydsy1704月赛]二元运算 Time Limit: 8 Sec Memory Limit: 128 MBSubmit: 577 Solved: 201[Submit][Status][Di ...
- scrapy 为每个pipeline配置spider
在settings.py里面配置pipeline,这里的配置的pipeline会作用于所有的spider,我们可以为每一个spider配置不同的pipeline, 设置 Spider 的 custom ...