生成python帮助文档_sphinx(一)

说明

• 环境说明

python：3.6
Red Hat：7.6
sphinx：4.2.0

• 本文主要内容说明

• sphinx创建python文档

• sphinx对文档进行修改

sphinx基本介绍

1. 安装对应库

yum install python-sphinx # 可以不要哈
pip install sphinx
sphinx-build --version

2. 快速开始

• Sphinx 附带一个名为sphinx-quickstart的脚本，该脚本设置源目录并创建默认的conf.py，根据交互设置一些关键信息即可。

sphinx-quickstart

3. 文档的结构

# 1、假设我们已经quickstart了，另外已经创建了包含conf.py和主文档index.rst的source文件了
# index.rst中的main函数是为了构建欢迎页面的（包含目录树）

4. 运行build脚本

sphinx-build -b singlehtml sourcedir builddir- sourcedir 源码所在的文件夹,- builddir 你希望存储文档的文件夹. -b 通常用来选择builder，比如singlehtml

demo

• 使用方法及演示：

1. 创建文件夹doc：mkdir doc；cd doc；执行sphinx-quickstart，进入引导，根据需要选择yes或者no

2. 执行sphinx-quickstart引导程序只会生成一个index.rst

3. 在doc目录下执行sphinx-apidoc -o source  file_directory，其中file_directory是指你需要文档化的目录，这样如果有多个模块，就会生成多个.rst文件

4. 在doc目录下执行make html，就会生成html文档，打开html文档，就可以了

1、源码嘞

# 1、mkdir project_test; cd project_test；mkdir src
%%writefile ./src/demo1.py
#coding=UTF-8
class Demo1():
    """类的功能说明"""

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

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

        函数功能说明.

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

        Returns:
            bool: 返回值说明

        """
        return True

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

        函数功能说明.

        Parameters
        ----------
        arg1 : int
            arg1的参数说明
        arg2 : str
            arg2的参数说明

        Returns
        -------
        bool
            返回值说明

        """
        return True

%%writefile ./src/demo2.py
#coding=UTF-8

def my_function(a, b):
    """函数功能说明

     >>> my_function(2, 3)
     6
     >>> my_function('a', 3)
     'aaa'

    """
    return a * b

mkdir tests
%%writefile ./src12/demo3.py
#coding=UTF-8

def test(a, b):
    """设置

     >>> my_function(2, 3)
     6
     >>> my_function('a', 3)
     'aaa'

    """
    return a * b

2、使用sphinx建立API文档项目

• mkdir 项目路径/doc

• cd 项目路径/doc

• sphinx-quickstart

• 因为我们需要从Python代码的注释中自动导出API文档，所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y

• 如果忘记设置，可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。

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

• 可以看到相关的参数还是非常多的，但不需要担心；

• 项目基本参数这部分可以通过交互式方式设置；

• 扩展程序选项这部分内容可以在source/conf.py设置

• 使用方法介绍：usage: sphinx-quickstart [OPTIONS]

3、syspath设置

• 报找不到module的时候，一般就需要添加path

# 修改source/conf.py文件
import os
import sys
sys.path.insert(, os.path.abspath('../../../'))#指向src目录
sys.path.insert(, os.path.abspath('../../../carHealth'))

4、执行apidoc命令

cd .. # 切换到doc上一级目录下sphinx-apidoc -o ./doc/source ./project_test/ EXCLUDE_PATTERN=docsMODULE_PATH 是要记录的Python包的路径；目录不要用*号；OUTPUT_PATH 是生成的document所在的目录。EXCLUDE_PATTERNs 是 fnmatch-style 文件和/或将从生成中排除的目录模式。

• 使用方法介绍

  usage: sphinx-apidoc [OPTIONS] -o   [EXCLUDE_PATTERN, …]

• 在<MODULE_PATH>中递归查找 Python 模块和包，

• 然后在<OUTPUT_PATH> 中为每个使用了 automodule 指令的包创建一个 reST 文件。

• <EXCLUDE_PATTERN>可以排除生成符合规则的文件/目录的文档。

5、清理文件

• cd doc

• make clean

6、生成html文件

• make html

7、修改API的主题

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

8、演示结果

netstat -plntu |grep "5001|5101|5102|5103|5201|8890"
cd buildpython3 -m http.server 8890 --cgi

9、通过其他文件引用

• 下面我们把run的文档移动到一个单独的页面，只在index.rst里保留跳转链接。在source目录下创建run.rst

• 在source目录下建立demo1.rst

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

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
# 然后将index.rst对应位置的内容删掉，并进行修改
API
===
:doc:`Run API</demo1>`

10、更改source/index.rst文件

.. toctree::
   :maxdepth: 3

   ./src.rst
   ./src12.rst

API
===
:doc:`src API</src1>`
   src source description.

:doc:`main API</src12>`
   main sources description.
   funs 基本函数

11、重新编译

cd ..sphinx-build -b singlehtml source buildmake html使用方法介绍usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES…]