python如何读取公共盘的文档_如何使用Sphinx生成Python文档

参考链接：
使用sphinx快速生成Python API 文档
用sphinx生成python文档

Sphinx 是一个很好用的代码文档生成工具，它可以根据Python里的doc_string生成美观的文档，十分方便快捷，接下来将介绍其具体使用方法：

1、在python项目中新建doc文件夹

cd ./doc

2、在doc目录下运行

sphinx-quickstart

sphinx会提示你的项目的一些设置，生成项目的配置文件，推荐的配置如下：

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

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: MTCNN-PANEL-DETECT
> Author name(s): Charles
> Project release []: 

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

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]: n
> 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]: n
> coverage: checks for documentation coverage (y/n) [n]: n
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [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]: n
> Create Windows command file? (y/n) [y]: n

然后会提示：

Creating file ./source/conf.py.
Creating file ./source/index.rst.

3、指定python文件路径

修改source中的conf.py文件。目的是确保python源代码所在的包在系统路径中可以找到。我的项目.py文件都平铺在doc的上级文件上，所以我就直接修改为：

#sys.path.insert(0,os.path.abspath('.'))
改为,并去掉注释
sys.path.insert(0,os.path.abspath('..'))

4、建立源文件

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]

具体操作上，可以在doc文件夹下运行：

sphinx-apidoc -o ./source ../

第一个是outputdir，即生成的.rst源文件保存位置，第二个是python源代码位置，我直接放在doc的上级目录里。

具体输出结果如下：

Creating file ./doc/source/augmentations.rst.
Creating file ./doc/source/config.rst.
Creating file ./doc/source/create_dataset.rst.
Creating file ./doc/source/dataset.rst.
Creating file ./doc/source/detector.rst.
Creating file ./doc/source/focal_loss.rst.
Creating file ./doc/source/lr_scheduler.rst.
Creating file ./doc/source/model.rst.
Creating file ./doc/source/read_data.rst.
Creating file ./doc/source/test.rst.
Creating file ./doc/source/train.rst.
Creating file ./doc/source/util.rst.
Creating file ./doc/source/modules.rst.

sphinx-apidoc的参数：

• -o rst输出文件夹
• -f, –force 强制输出，已经生成的rst会被覆盖.
• -l, –follow-links 符号链接
• -n, –dry-run If given, apidoc does not create any files.
• -s Suffix for the source files generated, default is rst.
• -d Maximum depth for the generated table of contents file.
• -T, –no-toc Do not create a table of contents file.
• -F, –full If given, a full Sphinx project is generated (conf.py, Makefile etc.) using sphinx-quickstart.
• -e, –separate Put each module file in its own page.
• -E, –no-headings Don’t create headings for the modules/packages
• -P, –private
• -H Project name to put into the configuration.
• -A Author name(s) to put into the configuration.
• -V 工程版本
• -R 工程发布版本

5、生成html文档，在doc下，运行：

sphinx-build -b html ./source ./build

第一个./source是上步骤中生成的.rst文件所在地，第二个./build 是你希望生成的html输出的位置。打开build文件夹就可以看到生成的html了：

打开index，点击index：

大功告成！

PS：
广告时间啦~
理工生如何提高人文素养软实力？快关注微信公众号：

欢迎扫码关注~