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

GY123456

<td>sphinx简介sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。更多详细特性请参考spinx官方文档，本篇博客主要介绍如何快速为你的Python注释生成API文档。sphinx官网链接:https://zh-sphinx-doc.readthedocs.io/en/latest/intro.html环境需要安装python安装sphinxpip install sphinx实例新建一个项目目录结构如上图所示，doc目录使用来存放API文档，src目录是用来存放项目的源码。src目录下的源码#coding=UTF-8class Demo1(): """类的功能说明""" def add(self,a,b):   """两个数字相加，并返回结果"""   return a+b def google_style(arg1, arg2):   """函数功能.   函数功能说明.   Args:     arg1 (int): arg1的参数说明     arg2 (str): arg2的参数说明   Returns:     bool: 返回值说明   """   return True def numpy_style(arg1, arg2):   """函数功能.   函数功能说明.   Parameters   ----------   arg1 : int     arg1的参数说明   arg2 : str     arg2的参数说明   Returns   -------   bool     返回值说明   """   return Truedemo1文件，主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明，使用google style显得更为简洁，而对于比较复杂详细的文档说明numpy style更为流行。#coding=UTF-8def my_function(a, b): """函数功能说明  &gt;&gt;&gt; my_function(2, 3)  6  &gt;&gt;&gt; my_function('a', 3)  'aaa' """ return a * bdemo2文件的注释看起来像Python命令行输入的文档字符串，主要是用来检查命令输出是否匹配下行的内容，它允许开发人员在源码中嵌入真实的示例和函数的用法，还能确保代码被测试和工作。使用sphinx建立API文档项目进入到doc目录下cd 项目路径/doc输入sphinx-quickstart命令，会输出选项&gt; Root path for the documentation [.]: sphinx_demo&gt; Separate source and build directories (y/n) [n]: y&gt; Name prefix for templates and static dir [_]:&gt; Project name: sphinx_demo&gt; Author name(s): sphinx demo&gt; Project version []: 1.0&gt; Project release [1.0]:&gt; Project language [en]: zh_CN&gt; Source file suffix [.rst]:&gt; Name of your master document (without suffix) [index]:&gt; Do you want to use the epub builder (y/n) [n]:&gt; autodoc: automatically insert docstrings from modules (y/n) [n]: y&gt; doctest: automatically test code snippets in doctest blocks (y/n) [n]: y&gt; intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y&gt; todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y&gt; coverage: checks for documentation coverage (y/n) [n]: y&gt; imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y&gt; mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y&gt; ifconfig: conditional inclusion of content based on config values (y/n) [n]:&gt; viewcode: include links to the source code of documented Python objects (y/n) [n]:&gt; githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:&gt; Create Makefile? (y/n) [y]:&gt; Create Windows command file? (y/n) [y]:因为我们需要从Python代码的注释中自动导出API文档，所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘记设置，可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。选项后面没有输入的，直接按回车键使用默认设置。选项后面有输入的，按照我的设置即可，如果不使用中文文档，可以在language配置中使用默认设置。设置完成之后，可以看到如下的目录结构后面如果需要修改配置，选项在source/conf.py文件中修改即可。extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax']通过设置conf.py中的extensions，可以为sphinx添加额外的扩展，如果想要将html文档转换为PDF，只需要先安装扩展，然后再此处添加即可使用。由于我们的注释代码主要同时支持google style和numpy style，所以我们需要添加一个扩展来支持。sphinx.ext.napoleon为源码生成html文件修改source/conf.py文件的19-21行import osimport syssys.path.insert(0, os.path.abspath('../../../src'))#指向src目录将命令行切换到doc目录下，执行以下命令sphinx-apidoc -o sphinx_demo/source ../src/&gt;Creating file sphinx_demo/source\demo1.rst.&gt;Creating file sphinx_demo/source\demo2.rst.&gt;Creating file sphinx_demo/source\modules.rst.清理文件cd sphinx_demomake clean&gt;Removing everything under 'build'...生成html文件make html请确保这一步没有输出error和exception打开build/html/index.html修改API的主题打开source/conf.py文件，找到html_theme = 'alabaster'，修改即可，sphinx官方提供了几种主题可以进行选择，sphinx主题设置：http://www.sphinx-doc.org/en/master/theming.html相关错误解决办法SyntaxError：Non-ASCII character '\xba' in file .....py在*.py文件的第一行添加#coding=UTF-8Encoding error：'utf8' codec can't decode byte 0xc0 in position 44：invalid start byte确保*.py文件的编码格式为utf-8，通过notepad++可以进行查看，如果不是请修改为utf-8格式添加sphinx.ext.napoleon后报Exception occurred ....return translator['sphinx'].ugettext(message) KeyError：'sphinx'Sphinx1.3，napoleon扩展使用sphinx.ext.napoleon，Sphinx &lt;= 1.2使用sphinxcontrib.napoleon</td>
了解更多干货，可以关注小程序八斗问答