sphinx简介

sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。

新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。

更多详细特性请参考spinx官方文档

sphinx安装

需要安装python
pip install sphinx

示例

新建一个项目

目录结构如下，

doc目录使用来存放API文档，

src目录是用来存放项目的源码

src目录下的源码

demo1文件

主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明，

使用google style显得更为简洁，

而对于比较复杂详细的文档说明numpy style更为流行。

coding=UTF-8

class 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 True

```

* demo2文件

```

注释看起来像Python命令行输入的文档字符串，

主要是用来检查命令输出是否匹配下行的内容，

它允许开发人员在源码中嵌入真实的示例和函数的用法，还能确保代码被测试和工作。

```

```python

coding=UTF-8

def my_function(a, b):

"""函数功能说明

 >>> my_function(2, 3)

 6

 >>> my_function('a', 3)

 'aaa'

"""

return a * b

```

使用sphinx建立API文档项目
1. 进入到doc目录下
cd 项目路径/doc
1. 输入sphinx-quickstart命令，会输出选项

Root path for the documentation [.]: sphinx_demo

Separate source and build directories (y/n) [n]: y

Name prefix for templates and static dir [_]:

Project name: sphinx_demo

Author name(s): sphinx demo

Project version []: 1.0

Project release [1.0]:

Project language [en]: zh_CN

Source file suffix [.rst]:

Name of your master document (without suffix) [index]:

Do you want to use the epub builder (y/n) [n]:

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

doctest: automatically test code snippets in doctest blocks (y/n) [n]: y

intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y

todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y

coverage: checks for documentation coverage (y/n) [n]: y

imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y

mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y

ifconfig: conditional inclusion of content based on config values (y/n) [n]:

viewcode: include links to the source code of documented Python objects (y/n) [n]:

githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

Create Makefile? (y/n) [y]:

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配置中使用默认设置。

设置完成之后，可以看到如下的目录结构

```

![](https://img2018.cnblogs.com/blog/885885/201910/885885-20191022174906524-83463060.png)  

* 后面如果需要修改配置，在选项source/conf.py文件中修改即可

```python

extensions = ['sphinx.ext.autodoc',

'sphinx.ext.doctest',

'sphinx.ext.intersphinx',

'sphinx.ext.todo',

'sphinx.ext.coverage',

'sphinx.ext.mathjax']

```

* 额外的扩展

```text

通过设置conf.py中的extensions，可以为sphinx添加额外的扩展，

如果想要将html文档转换为PDF，只需要先安装扩展，然后再此处添加即可使用。

由于我们的注释代码主要同时支持google style和numpy style，所以我们需要添加一个扩展来支持。

```

```

sphinx.ext.napoleon

```

为源码生成html文件
- 修改source/conf.py文件的19-21行

import os

import sys

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

```

* 将命令行切换到doc目录下，执行以下命令

```

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

>Creating file sphinx_demo/source\demo1.rst.

>Creating file sphinx_demo/source\demo2.rst.

>Creating file sphinx_demo/source\modules.rst.

```

清理文件

cd sphinx_demo

make clean

>Removing everything under 'build'...

生成html文件

make html

// 请确保这一步没有输出error和exception

打开build/html/index.html
修改API的主题

打开source/conf.py文件，找到html_theme = 'alabaster'，修改即可，sphinx官方提供了几种主题可以进行选择，sphinx主题设置

巴特西

使用sphinx为python注释生成docAPI文档

sphinx简介

sphinx安装

示例

coding=UTF-8

coding=UTF-8

相关错误解决办法

最新文章

热门文章