sphinx：python项目文档自动生成

时间：2023-12-13 10:41:50

Sphinx:

发音：

DJ音标发音： [sfiŋks] KK音标发音： [sfɪŋks]

单词本身释义：

an ancient imaginary creature with a lion's body and a woman's head

  1. Mythology A figure in Egyptian myth having the body of a lion and the head of a man, ram, or hawk.

    【古埃及神话】 斯芬克斯：古代埃及神话中人面、公羊头或鹰头的狮身像
  2. Greek Mythology A winged creature having the head of a woman and the body of a lion, noted for killing those who could not answer its riddle.

    【希腊神话】 斯芬克斯：古代希腊神话中带翼的狮身女面怪物，专杀那些猜不出其谜语的人

Sphinx在此处是一个可自动生成python项目api的工具，使用起来也比较简单，只需要在项目上进行简单的配置，即可生成项目的api文档（如下图）

sphinx：python项目文档自动生成

步骤：

1. 安装sphinx

pip install sphinx

2. 在项目的开发过程中

2.1注意在注释中说清楚函数的用途描述，参数意义以及返回了什么，例如：(在pycharm中，在函数名的下一行输入3个引号后回车会自动生成函数描述的模板

sphinx：python项目文档自动生成

2.2 在pycharm中设置文件头及函数注释的模板

2.2.1

  • 文件头模板设置

    ** File->settings->Editor->File and Code Templates->Python Script

    sphinx：python项目文档自动生成

  • 函数知识模板设置

    ** File->Settings->Tools->Python integrated Tools->Docstring format，把该框选为Google或nunpy等

    因numpy对于多个returns的支持较好，所以选用了numpy

    sphinx：python项目文档自动生成

3. 配置sphinx

3.1 在项目文档下新建一个文件夹，可命名为doc （路径 your_project_path/doc）

3.2 进入doc文件夹下的命令行窗口，输入sphinx-quickstart进行配置 (文中一下的命令行，如无特殊说明，皆是在doc路径下执行)

配置你的项目名，版本，等

在此处的选项中，除了autodoc使用非默认的选项，选了y，其他的，皆使用默认项。配置项选错了也没关系，最后都可以在conf.py中更改

sphinx-quickstart
Welcome to the Sphinx 1.8.3 quickstart utility.

Please enter values for the following settings (just press Enter to

accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.

Either, you use a directory "_build" within the root path, or you separate

"source" and "build" directories within the root path.

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

Inside the root directory, two more directories will be created; "_templates"

for custom HTML templates and "_static" for custom stylesheets and other static

files. You can enter another prefix (such as ".") to replace the underscore.

> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.

> Project name: test_sphinx

> Author name(s): testname

> Project release []: 0

If the documents are to be written in a language other than English,

you can select a language here by its language code. Sphinx will then

translate text that it generates into that language.

For a list of supported codes, see

http://sphinx-doc.org/config.html#confval-language.

> Project language [en]: 

The file name suffix for source files. Commonly, this is either ".txt"

or ".rst". Only files with this suffix are considered documents.

> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the

"contents tree", that is, it is the root of the hierarchical structure

of the documents. Normally, this is "index", but if your "index"

document is a custom template, you can also set this to another filename.

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

Indicate which of the following Sphinx extensions should be enabled:

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

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

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

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

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

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

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

> 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]: 

A Makefile and a Windows command file can be generated for you so that you

only have to run e.g. `make html' instead of invoking sphinx-build

directly.

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

> Create Windows command file? (y/n) [y]: 

Creating file .\conf.py.

Creating file .\index.rst.

Creating file .\Makefile.

Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\index.rst and create other documentation

source files. Use the Makefile to build the docs, like so:

   make builder

where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

在doc文件夹下得到如下

sphinx：python项目文档自动生成

3.3 配置生成各个py文件的rst文件，在doc下生成一个rst文件夹

sphinx-apidoc -o [生成rst的位置] [项目代码的位置] -f(强制重新覆盖写，否则会检测，如果有同名文件存在，会跳过不更新)

sphinx-apidoc -o rst ../src

sphinx：python项目文档自动生成

3.4 修改conf.py文件

3.4.1 将conf.py中第15-17行的注释取消，并讲第17行的路径改为源代码的所在路径
import os

import sys

sys.path.insert(0, os.path.abspath('../src'))
3.4.2 如果源代码中引入了pandas，numpy等比较大的包，需要在conf.py中做相应的设置，否则会有import errpr之类的报错
autodoc_mock_imports = ["pandas","pyecharts"]
3.4.3 为了google的docstring换行的展示，更改
extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon']

3.5 生成html

make html

在doc下的子文件夹中会生成若干html，打开index.html即可查阅相关的函数API

sphinx：python项目文档自动生成

相关文章