使⽤sphinx⾃动建⽴API⽂档（⼀）
1、使⽤ demo 的 python ⽂件
建⽴test_demo为根⽬录，下⾯分别建⽴doc和src⽂件夹。
doc：之后⽤来存储⽣成的 html ⽂件和相关配置
src：源 python ⽂件
src下⾯的 demo ⽂件分别有如下内容：
demo1:
class Demo1():
"""
English Demo1.
"""
def demo1(self, arg1):
python中文文档
"""
Some basic information.
:param str arg1: this is a arg.(has str type)
:return: some thing
"""
print('demo1')
def run(self):
"""
Automatically generate documents.
:return:
"""
print('run')
class Demo1_ch():
"""
中⽂ Demo1.
"""
def demo1_ch(self, arg1):
"""
⼀些基本信息
:param arg1: 这是⼀个参数(没有 str 字符类型)
:return: 信息
"""
print('demo1_ch')
def run(self):
"""
⾃动⽣成⽂档
:return:
"""
print('run')
demo2:
2、建⽴基本的 sphinx ⽂件
cd 到doc ⽬录下。 输⼊命令：sphinx-quickstart ，会弹出⼀些选项问题。上⾯是我的配置，这些之后都可以在doc/source/conf.py  ⽂件中修改。 注意：autodoc: automatically insert docstrings from modules (y/n) [n]: y
需要设置为y 。 def  demo2_func (arg1):
"""
This is a test of function.
:param str arg1: this is a arg.(has str type)
:return: some thing
"""
pass
def  demo2_func_ch (arg1):
"""
⼀些基本信息
:param arg1: 这是⼀个参数(没有 str 字符类型)
:return: 信息    """
pass
> Separate source and  build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: demo
> Author name(s): longgb246
> Project release []: 1.0
> 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]:
> 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 ]:
上⾯设置对应于doc/source/conf.py  中，相应的插件。
⽣成的⽂件结构如下：
3、⽣成 api 的 html ⽂件（1）修改doc/source/conf.py ⽂件，在其中加⼊，下⾯的路径是根据conf  与src 的相对路径决定的，如果是按照上⾯的⽂件结构，不需要修改下⾯代码：（2）在doc ⽬录下⾯，执⾏：
sphinx-apidoc的使⽤，⼤致：
OUTPUT_PATH：source ⽂件
MODULE_PATH：python 源⽂件
（3）执⾏ html ⽂件清理
（4）⽣成 html ⽂件说明：这⾥官⽅⽂档使⽤的是sphinx-build -b html sourcedir builddir ，但是会⽣成⽂件在 src 下⾯，建议使⽤sphinx-apidoc
import os
import sys
sys.path.insert(0, os.path.abspath('./../../src'))
sphinx -apidoc  -o  ./source ../src/
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH > <MODULE_PATH > [EXCLUDE_PATTERN, …]make clean
make html
（5）html 结果⽂件
运⾏上⾯的命令后，打开doc/build/html/index.html。
⽣成该⽹页。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。