ubuntu下使用时sphinx制作python项目API文档

一.安装

Ubuntu 安装sphinx 使用命令行: 

sudo pip3 install sphinx

创建一个项目,将python文件放在src下,如下图所示:

在终端进入doc 目录

输入 sphinx-quickstart 命令，会输出选项完成一下选项选择

cd python/shpinx_demo/doc
python/shpinx_demo/doc$ sphinx-quickstart

> 独立的源文件和构建目录（y/n） [n]: y

> 项目名称: sphinx_demo
> 作者名称: zhong
> 项目发行版本 []: 1.0


> 项目语种 [en]: zh_CN

创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

新的目录文件如下:

后面需要修改一些配置, 打开 sorce/conf.py 文件

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.napoleon']

修改网页风格

#html_theme = ‘default’
#html_theme = ‘alabaster’
html_theme = ‘sphinxdoc’

default风格长这样：

alabaster风格，界面长这样：

sphinx风格，界面长这样：

修改source/conf.py文件的19-21行,将注释取消.

import os 
import sys 
sys.path.insert(0, os.path.abspath('python/shpinx_demo/src'))#指向src目录

在终端输入:

python/shpinx_demo/doc$ sphinx-apidoc -o source ../src/
创建文件 source/Example1.rst。
创建文件 source/Example2.rst。
创建文件 source/modules.rst。

现在项目目录中显示如此:

打开 source/index.rst 文件, 在文件中添加以下代码 :

Introduction
============
This is the introduction of demo。

API
===

.. toctree::
   :maxdepth: 4

   modules

文件内容如下图所示: 

清理文件,在终端中输入: make clear

python/shpinx_demo/doc$ make clean
Removing everything under 'build'…

生成 html ,在终端中输入: make html

python/shpinx_demo/doc$ make html
正在运行 Sphinx v2.3.1
正在加载翻译 [zh_CN]... 完成
制作输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 4 个源文件的目标文件已过期
更新环境: [新配置] 已添加 4，0 已更改，0 已移除
阅读源... [ 25%] Example1                                                       
阅读源... [ 50%] Example2                                                       
阅读源... [ 75%] index                                                          
阅读源... [100%] modules                                                         
查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [ 25%] Example1                                                     
写入输出... [ 50%] Example2                                                     
写入输出... [ 75%] index                                                        
写入输出... [100%] modules                                                          
generating indices...  genindex py-modindex完成
writing additional pages...  search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.

HTML 页面保存在 build/html 目录。

当没有出现任何错误和提醒时,则已经成功了.

打开build/html/index.html