使用sphinx快速为你python注释生成API（html）文档

sphinx简介

sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。更多详细特性请参考sphinx官方文档本篇博客主要介绍如何快速为你的Python注释生成API文档。
环境

ubuntu 16.04
python 3.7

pip3 install sphinx
#pip3是给python3安装，如果是python2　pip安装即可。

实例

1. 新建一个项目
项目路径：

即：

目录结构如上图所示，doc目录使用来存放API(html)文档，src目录是用来存放项目的源码。

2. src目录下的源码
demo1.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time    : 2/4/20 5:51 PM
# @Author  : Jing Bai
# @File    : demo1.py
# @Software: PyCharm
#coding=UTF-8
class Demo1():"""类的功能说明"""def add(self,a,b):"""两个数字相加，并返回结果"""return a+bdef google_style(arg1, arg2):"""函数功能.函数功能说明.Args:arg1 (int): arg1的参数说明arg2 (str): arg2的参数说明Returns:bool: 返回值说明"""return Truedef numpy_style(arg1, arg2):"""函数功能.函数功能说明.Parameters----------arg1 : intarg1的参数说明arg2 : strarg2的参数说明Returns-------bool返回值说明"""return True

demo1文件，主要使用了两种不同的Python注释分格。
对于简单的例子和简单的函数以及文档说明，使用google style显得更为简洁。
demo2,而对于比较复杂详细的文档说明numpy style更为流行,。

demo2.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time    : 2/4/20 5:51 PM
# @Author  : Jing Bai
# @File    : demo2.py
# @Software: PyCharm
#coding=UTF-8def my_function(a, b):"""函数功能说明>>> my_function(2, 3)6>>> my_function('a', 3)'aaa'"""return a * b

demo2文件的注释看起来像Python命令行输入的文档字符串，
主要是用来检查命令输出是否匹配下行的内容，
它允许开发人员在源码中嵌入真实的示例和函数的用法，
还能确保代码被测试和工作。

３. 使用sphinx建立API文档项目

cd 项目路径/doc
sphinx-quickstart

或者在doc文件夹下打开终端，
再输入sphinx-quickstart
如下图：

按照下图将提示补充完整

说明：

Project name: BaiJing　＃这里可以写项目的名字

Author name(s): BaiJing　＃项目的开发人员
Project release []: 1.1.0　＃项目更新的第几个版本
Project language [en]: zh_CN　＃生成API文档的语言，这里写的是zh_CN代表中文。

此时项目目录如下：

需要修改配置，选项在source/conf.py文件中修改即可。
将extensions = [ ]改为

extensions = ['sphinx.ext.autodoc','sphinx.ext.doctest','sphinx.ext.intersphinx','sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.mathjax']

４. 为源码生成html文件

修改source/conf.py文件的19-21行

import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))#指向src目录

修改后的source/conf.py如下：

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html# -- Path setup --------------------------------------------------------------# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))# -- Project information -----------------------------------------------------project = 'BaiJing'
copyright = '2020, BaiJing'
author = 'BaiJing'# The full version, including alpha/beta/rc tags
release = '1.1.0'# -- General configuration ---------------------------------------------------# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc','sphinx.ext.doctest','sphinx.ext.intersphinx','sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.mathjax']# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'zh_CN'# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []# -- Options for HTML output -------------------------------------------------# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

sphinx-apidoc -o ./source ../src/

**5. 设置目录树：**主要是将doc/source/modules.rst 文件添加到 index.rst中,同时maxdepth把index.html页中目录的标题显示深度限制设为10。
修改后index.rst的内容为：

.. BaiJing documentation master file, created bysphinx-quickstart on Tue Feb  4 22:13:49 2020.You can adapt this file completely to your liking, but it should at leastcontain the root `toctree` directive.Welcome to BaiJing's documentation!
===================================.. toctree:::maxdepth: 10:caption: Contents:modules.rstIndices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

６. 生成html注释文档：在doc目录下执行以下两个命令
make clean (删除doc/build下面的所有内容）和make html(生成html文件）
已经生成注释文档后，如果配置文件或项目源码注释有改动，需要先执行make clean，再执行make html
效果如下：

７. 注释文档效果展示

主界面：

模块界面

使用sphinx快速为你python注释生成API（html）文档相关推荐

使用sphinx快速为你python注释生成API文档
sphinx简介 sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的 ...
开发日记-20190328 关键词利用eolinker一键快速生成API接口文档
今天感觉效率真的很低= =各个层面的,apk发布到现场发现出现了问题,所以一个下午都在忙着解决现场出现的问题,领导一直打电话询问进度,午觉也没有睡所以今天预计的很多计划都处于停滞状态,像昨天规划的今天 ...
python生成api文档_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
python api接口生成_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
apidoc 自动化生成 api接口文档
手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理要用组件那就必须先安装 apidoc,做一下全局安装 npm install apidoc -g 新建配置文件apidoc. ...
Laravel使用swagger PHP生成api接口文档
Laravel使用swagger PHP生成api接口文档 Swagger集接口文档和测试于一体,就类比将postman和showdoc的结合体首先要先安装基于laravel5的swagger包地 ...
如何自动生成 API 接口文档 - 一份详细指南
本篇文章详细教你如何使用 Apifox 的 IDEA 插件实现自动生成接口代码.好处简单总结有以下几点: 自动生成接口文档: 不用手写,一键点击就可以自动生成文档,当有更新时,点击一下就可以自动同步接 ...
Laravel使用Apidoc注解自动生成Api接口文档
本教程从零开始搭建laravel项目,并安装Apidoc扩展及使用注解生成Api接口文档的教程,该扩展支持多应用/版本.Markdown文档.在线接口调试.接口生成器.代码模板生成器.Mock调试数 ...
vc 生成html,成功从VC++的XML注释生成静态html文档
GacUI的类库说明文档已经可以生成了!利用了之前的这篇博客描述的pdb信息抽取并和XML注释合并的技术,成功写了一系列工具来从这些信息里面生成静态html文档.现在的XML注释只写了1/3,所以生成 ...

使用sphinx快速为你python注释生成API（html）文档

sphinx简介

使用sphinx快速为你python注释生成API（html）文档相关推荐

最新文章

热门文章