sphinx 基本使用

安装

pip install sphinx

文件完整的结构目录如下：

image.png

在自己的项目目录下建立两个文件夹src和doc
在src下新建一个文件demo1.py，内容如下：

# 使用类和实例
class Car():
    """一次模拟汽车的简单尝试"""
    def __init__(self, make, model, year):
        """初始化描述汽车的属性"""
        self.make = make
        self.model = model
        self.year = year

        # 给属性指定默认值
        self.odometer_reading = 0

    def get_descriptive_name(self):
        """ 返回整洁的描述性信息 """
        long_name = str(self.year) + ' ' + self.make + ' ' + self.model
        return long_name.title()

    def read_odometer(self):
        """ 打印一条指出汽车里程的消息 """
        print('This car has ' + str(self.odometer_reading) + ' miles on it.')

    def update_odometer(self, mileage):
        """ 修改里程的值 """
        if mileage >= self.odometer_reading:
            self.odometer_reading = mileage
        else:
            print("You can't roll back an odometer!")

    def increment_odometer(self, miles):
        """ 将里程表读数增加指定的量 """
        self.odometer_reading += miles

接着执行以下命令

cd doc
sphinx-quickstart

打开doc/source/conf.py文件，取消13-15行的注释
第15行sys.path.insert(0, os.path.abspath('.')) 改为sys.path.insert(0, os.path.abspath('../../src'))

在doc目录下执行

sphinx-apidoc -o source ../src

• source参数是doc文件夹下的source文件夹
• ../src 参数是和doc文件夹同级的放Python文件的文件夹

执行后会生成如下文件

image.png

如在编译时遇到错误 Sphinx error: master file [..]/checkouts/latest/contents.rst not found
可以在doc/source/conf.py 中添加master_doc = 'index'

执行make html生成 html 格式的文档，在build/html文件夹下会生成相应的文档
点击index.html页面查看效果：

image.png

再往index.rst里添加好模块的名称

image.png

再去执行make html，刚刚添加的内容就会在首页的导航里出现了

image.png

点击链接后跳转如下：

image.png