使用sphinx快速生成Python API 文档

Posted 珠峰上吹泡泡

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了使用sphinx快速生成Python API 文档相关的知识,希望对你有一定的参考价值。

一  简单介绍

不管是开源还是闭源,文档都是很重要的。当然理论上说,最好的文档就是代码本身,但是要让所有人都能读懂你的代码这太难了。所以我们要写文档。大部分情况,我们不希望维护一份代码再加上一份文档,这样做很容易造成文档和代码的不一致,程序员最讨厌更新文档了。所以最佳实践就是在程序员代码中加注释,然后通过构建脚本自通生成文档,包括html,latex,pdf等。

对应于Pyhon,有很多可供选择的工具:

  • sphinx 中文版介绍 Sphinx使用 reStructuredText作为标记语言(类似Markdown),可扩展,功能强大。要注意的是何有一个开源的搜索也叫Sphinx,斯芬克斯果然太受欢迎,开源的世界起个名字不容易呀。
  •  pdoc 是一个简单易用的命令行工具,可以生成Python的API文档
  •  Doxygen 是老牌的文档生成工具,可以针对各种语言生成文档,我们以前在C++的项目中曾经使用过
  •  其他还有诸如 pydoc pydoctor 等等

二 安装

  • 要安装Sphinx,不同的操作系统有不同的安装方式,Sphinx的源代码在这里
  • 你也可以自己构建。我推荐使用pip install sphinx !
  • 如果你安装了Anaconda,Sphinx已经包含在内了!

三 创建一个sphinx项目

下面的命令会自动生成一个默认的Sphinx模板:

mkdir yourdir
cd yourdir
sphinx-quickstart

执行期间,它会一步步的询问对模板的设置,除了一些必须填写的选项,大部分填写默认值就行了,你会遇到这样一条叫autodoc的,需要选择yes!

autodoc: automatically insert docstrings from modules (y/n) [n]

然后默认的目录就生成了,大概是这个样子

- yourdir/ # 刚才新建的目录
    - source/ # 存放Sphinx工程源码
    - build/ # 存放生成的文档
    Makefile

现在执行如下指令,就会生成一份空文档,存放在/build/html里,点击index.html就可以打开一个空的网页,虽然没有内容,但是整体的结构还是在的!

sphinx-build -b html source build
make html

source/目录里有两个文件,分别是conf.pyindex.rst,下面对它们进行进一步的介绍

(1) index.rst

.rst是reStructuredText,和Markdown一样是一种标记语言,具体的语法可以看这里 reStructuredText Primer。实际上,我们在使用Sphinx的过程中最主要就是对这些rst文件进行修改,而Sphinx所做的事情就是读取这些rst文件,并转换为特定格式的文档,在前面的步骤中,index.rst实际上被转换为build/html/index.html,而实际上在rst文档内你可以写任何东西,最后这些都会被转换到输出文档中。
打开index.rst,可以看到这样的内容,这是rst的一个语法,它使用了一个toctree节点,并设置了一些参数,而这个toctree节点是必须的。

.. toctree::
   :maxdepth: 2
   :caption: Contents:

(2) conf.py

这是运行sphinx生成文档时会加载的配置,你可以通过对它进行修改来改变生成文档的行为。

四 一个具体的例子

假设现在我们有一个叫run.py的文件,如下

# run.py
def run(name):
    """
    this is how we run

    :param name name of people who runs
    """
    printname, \'is running\'

那么需要如何生成文档呢?下面一步步带你完成

  1. 创建一个文件夹demo/,并将run.py放到里面
  2. 在demo里创建一个docs目录,进入docs/目录,当然这里你可以随意选定文件夹,只是这样更规范一些
  3. 生成Sphinx默认模板,设置项目名为demo,并开启autodoc(运行sphinx-quickstart
  4. 进入source目录,打开index.rst
  5. 将index.rst 修改为如下,实际上这里面可以写任何满足rst规范的内容
Welcome to demo\'s API Documentation
====================================== 
.. toctree::
:maxdepth:2
:caption: Contents:

Introduction
============

This is the introduction of demo。

API
===

.. automodule:: run
:members:

Indices and tables ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

 这个是用于自动从模块读取docstring的语句,可以自动从run模块读取文档

.. automodule:: run
   :members:

但是现在还差一步,如果你现在直接生成文档,会告诉你找不到run模块,因为Sphinx默认只会从sys.path里加载模块,所以需要将demo目录加入sys.path,所以现在打开conf.py,添加如下内容

import os
import sys
sys.path.insert(0, os.path.abspath(\'../..\'))

运行Sphinx生成html文档

cd ..
sphinx-build -b html source build
make html

现在,打开build/html/index.html就可以看到如下界面了

注:格式进一步优化

上面的例子涵盖了大多数常用操作,但是通常文档都不是扁平的,而是层次化的,那么要如何将文档层次化的分门别类。实际上在rst文档中是可以以链接的形式引用其他rst文档的,也就是说我们可以自由的对文档结构进行组织使其更易读。下面我们把run的文档移动到一个单独的页面,只在index.rst里保留跳转链接。在source目录下创建run.rst

API
===
.. automodule:: run
   :members:

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

然后将index.rst对应位置的内容删掉,并进行修改

Welcome to demo\'s API Documentation
=================================== 
.. toctree::
:maxdepth: 2
:caption: Contents:

Introduction
============
This is the introduction of demo。

API
===
:doc:\'Run API</run>\'

Indices and tables ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

:doc:\'Run API</run>\'表示对一个文档的引用,这里引用了当前目录的run.rst,现在重新生成html,就会看到页面显示上的变化了。

参考:使用Sphinx为你的python模块自动生成文档

以上是关于使用sphinx快速生成Python API 文档的主要内容,如果未能解决你的问题,请参考以下文章

利用sphinx为python项目生成API文档

如何使用 Sphinx 为 Python 属性设置器生成文档?

python文档生成工具:pydocsphinx;django如何使用sphinx?

使用sphinx生成python项目文档

python代码docstring生成文档之sphinx

最终用户将如何访问 Sphinx 为 Python 包生成的文档?