基于python注释使用sphinx自动化生成API文档

写在前面

我们平时在使用python包过程中，经常都能看到包对应的文档，拉到网页底部，往往能看到”Powered by Sphinx”，sphinx是一种基于Python的文档工具，当然对其他文档也有支持。本文就主要基于代码已有的注释，使用sphinx自动化生成API文档。

sphinx安装

1	pip install sphinx

版本：v3.0.2

这个版本和之前在网上教程看的好多例子不太一样。

一个简单的例子

新建一个项目

项目目录如下：

项目目录1

demo1.py代码如下：

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
desc

Date: 2020/4/22

"""


class Demo1():
    """类的功能说明"""

    def add(self, a, b):
        """两个数字相加，并返回结果"""
        return a+b

    def google_style(self, arg1, arg2):
        """函数功能.

        函数功能说明.

        Args:
            arg1 (int): arg1的参数说明
            arg2 (str): arg2的参数说明

        Returns:
            bool: 返回值说明

        """
        return True

这是一个简单的项目目录，作为第三方包来说，有时还包含子模块，但是已验证都是支持的。

在源代码同级目录下新建一个文档doc，现在目录结构如下：

项目目录2

sphinx-quickstart

在doc目录下，使用命令sphinx-quickstart，除了自己项目的配置，其他配置可以默认。

命令执行情况如下：

sphinx-quickstart

这个输出和网上现在很多教程不一样，没有一些扩展的设置，类似下面：

extensions

但是我们可以在source/conf.py中进行配置

conf.py配置

配置extensions，修改source/conf.py文件内容：

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

如果需要自动生成API文档，需要sphinx.ext.autodoc

配置项目路径：

取消13~15行的注释，修改为下面的内容：

1
2
3

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

这块路径使用../../是因为我们的demo是一个包，如果demo下面没有__init__.py文件，则可以路径为../../demo。

生成rst文件

使用sphinx-apidoc生成rst文件，-o 后面跟的是保存rst文件的路径，你的index.rst文件在哪个目录，就指定哪个目录，然后最后面是代码路径

在doc目录下，执行结果如下：
sphinx-apidoc

生成HTML

在doc目录下，使用make命令生成html文件

生成结果如下：

使用前，先清除一下之前的生成文件

1	make clean

生成html

make html

过程如图：

make html

这块有个红色的warning，我们后面再来解决这个问题，先暂且放着。

展示效果

现在我们用浏览器打开doc/build/html/index.html，显示如下：
展示效果1

这是不是和我们平时看到的python文档不太一样，那是因为我们的主题没有选对

改变sphinx主题

python sphinx的主题包很多，现在大多数用得多的是readthedoc风格的，主题名字叫sphinx_rtd_theme。

安装主题

1	pip install sphinx_rtd_theme

导入模块：修改source/conf.py文件

# 导入模块
import sphinx_rtd_theme

# html_theme = "alabaster"修改如下，加上html_theme_path
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

重新生成：在doc目录下

1 2	make clean make html

显示效果
显示效果2

现在看着是不是熟悉了很多

采坑

不知道大家有没有发现，上面生成的文档左边导航栏下面是没有内容CONTENTS的，本来应该是像下面这样的：
显示效果3
还记得上面提到的在make html时的那个Warning么，这就是那个导致的

那个warning的意思是说，modules.rst没有被包含，没有被什么包含呢，是没有在index.rst里面包含，毕竟我们显示是用的index.rst。

所以我们需要在index.rst里面加上modules，不知道是不是这个版本的问题，我在好多教程里面都没有提到这个，所以踩了个坑。

修改后如下(source/index.rst)：

.. demo documentation master file, created by
   sphinx-quickstart on Thu Apr 23 10:09:09 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to demo's documentation!
================================

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

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

之后，再运行make clean和make html，则warning消失，页面上会显示CONTENTS

make html 2

Nginx发布

安装nginx后，在配置文件(Linux一般在: /etc/nginx/nginx.conf)里面，在http下面增加如下配置：

server {
        listen       80 default_server;
        listen       [::]:80 default_server;
        server_name  localhost; 
        root         /data/www/html;  //将doc/build/html复制到/data/www/html

        include /etc/nginx/default.d/*.conf;

        location / {
        }

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
}