目录

前言：

项目层级

安装sphinx

创建sphinx文档项目

配置conf.py文件

编译代码为api文档

编译文档（windows）

异常处理

异常1：无法生成rst文件

异常2：WARNING: autodoc: failed to import module xxx;WARNING: autodoc: failed to import module 'xxx'; the following exception was raised:No module named 'xxx'

异常3：Encoding error：'utf8' codec can't decode byte 0xc0 in position 44：invalid start byte

---

前言：

最近需要把项目生成API文档，在网上找了下发现sphinx这个框架用的比较多，研究了一下，发现还是挺赞的，只不过纸上得来终觉浅，绝知此事要躬行，别人的项目结构啥的和自己不一样，网上基本都是单目录的层级，但是实际项目往往都会有比较深的层级关系，所以还是踩了不少坑，在此结合自己的项目总结一下。

项目层级

一般情况真实项目都是会存在多种层级关系的，这是小编做的一个项目的层级结构： 

po_pattern/
├── __init__.py
├── config/
│ ├── env_const.py
├── pages/
│ ├── __init__.py
│ ├── APage.py
│ ├── BPage.py
└── testcase/
├── __init__.py
├── conftest.py
├── scenario_part1_test.py
├── scenario_part2_test.py

Ps:po上面还有一级项目目录，跟源码目录同级创建doc目录然后切换到doc目录创建文档项目
创建文档项目

安装sphinx

第一步安装sphinx，直接pip安装就行了：

pip install  sphinx

 安装完后就是创建一个sphinx文档项目了，直接在项目根目录下创建一个doc目录，然后切换到doc目录执行命令：sphinx-quickstart，执行后会创建一个sphinx文档项目。

创建sphinx文档项目

pycharm切换到终端，执行命令sphinx-quickstart，会提示设置结构分离、项目名、作者名、版本号、语言（配置后面可修改）：

sphinx-quickstart

输出：

Welcome to the Sphinx 7.2.6 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
You have two options for placing the build directory for Sphinx output.
The project name will occur in several places in the built documentation.
> Project name: test
> Author name(s): test
> Project release []: 1.0
If the documents are to be written in a language other than English,
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN

配置conf.py文件

这个文件主要设置文档项目路径、文档主题、源码api文档字符串收集等配置

conf.py

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# sys.path.insert(0, os.path.abspath(".."))
# a = os.path.abspath("..")
# print('a:%s' % a)
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
for v in sys.path:
print(v)
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'test'
copyright = '2023, test'
author = 'C'mon'
release = '1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode' 
]
templates_path = ['_templates']
exclude_patterns = []
language = 'zh_CN'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'alabaster'
html_static_path = ['_static']

编译代码为api文档

用法:
sphinx-apidoc [选项] -o <输出路径> <模块路径> [排除模式…]

这个输出路径一般就是文档中的source，然后接要生成源码的模块路径如下：

sphinx-apidoc -o ./source ../po_pattern

执行后输出如下：
(dmg_bi_auto_test) PS D:\dmg_bi_auto_test\doc> sphinx-apidoc -o ./source ../po_pattern

执行完后会在source目录下生成模块的rst 文件，没生成是有问题的。

编译文档（windows）

.\make html 

正常输出：
(dmg_bi_auto_test) PS D:\dmg_bi_auto_test\doc> .\make html 
Running Sphinx v7.2.6
D:\dmg_bi_auto_test 
D:\dmg_bi_auto_test\po_pattern\pages 
D:\dmg_bi_auto_test\po_pattern\testcase 
D:\工作\dmg_bi_auto_test\Scripts\sphinx-build.exe
C:\Program Files\Python\python311.zip
C:\Program Files\Python\DLLs
C:\Program Files\Python\Lib
highlighting module code... [100%] po_pattern.testcase.self_analysis_scenario_testcase_test
writing additional pages... search done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in build\html.

以上是执行成功的之后打开build目录下的index.html文件就可以查看api文档了。

异常处理

异常1：无法生成rst文件

原因：不能递归目录，存在子目录情况下需要指定到最深层级的目录Python模块查找

异常2：WARNING: autodoc: failed to import module xxx;
WARNING: autodoc: failed to import module 'xxx'; the following exception was raised:
No module named 'xxx'

原因：未识别到包下的模块
异常1和2属于同类问题：

解决办法：
1、不符合规范的目录改为python包目录
Python 模块路径搜索：https://docs.python.org/zh-cn/3/tutorial/modules.html
模块搜索路径
当导入一个名为 spam 的模块时，解释器首先会搜索具有该名称的内置模块。 这些模块的名称在 sys.builtin_module_names 中列出。 如果未找到，它将在变量 sys.path 所给出的目录列表中搜索名为 spam.py 的文件。 sys.path 是从这些位置初始化的:

• 被命令行直接运行的脚本所在的目录（或未指定文件时的当前目录）。
• PYTHONPATH （目录列表，与 shell 变量 PATH 的语法一样）。
• 依赖于安装的默认值（按照惯例包括一个 site-packages 目录，由 site 模块处理）。

更多细节请参阅 sys.path 模块搜索路径的初始化。

导入包时，Python 搜索 sys.path 里的目录，查找包的子目录。
必须要有 __init__.py 文件才能让 Python 将包含该文件的目录当作包来处理。 
因此新建的目录如果不符合包的规范的话是查找不到包里面的模块的。

异常3：Encoding error：'utf8' codec can't decode byte 0xc0 in position 44：invalid start byte

保证所有python 模块（.py文件）的编码格式为utf-8在*.py文件的第一行添加# -*- coding:utf-8 -*-

参考：

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon

https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

https://docs.python.org/zh-cn/3/library/sys_path_init.html#sys-path-init