Python Sphinx 生成简洁大方的文档

2022-05-11 00:00:00 文档代码项目生成配置

安装 sphinx 库
简单示例（ Spninx 使用）

步骤一：Sphinx 创建出基础配置
步骤二：配置项目入口 index.rst
步骤三：生成项目文档
步骤四：展示出来

小小总结

Sphinx 简介

Sphinx 是一种工具，是一个有趣 python 的第三方库，它允许程序员以纯文本格式编写文档，Spninx 可以轻松生成各种格式的输出，比如 html，pfd，等等。纯文本的文档方便使用版本管理工具进行跟踪。纯文本文档对不同系统之间的协作者也非常有用，纯文本是当前可以采用的便捷的格式之一，不然 markdown 格式咋那么火呢，不是没有道理的。

程序员讨厌的两件事：

自己写代码文档
别人的代码没文档

正经写文档确实麻烦，为啥麻烦呢？因为很长时间程序员写代码和写文档是完全独立分开的，这说起来就是两份工作量，不能忍受的还是变化带来的负担，代码是可能经常变动的，代码变动之后，含义自然就可能不一样，或者新加了了功能，文档如果还要手动跟进的话，喜欢偷懒的程序员自然就不愿了。

我们回归本源，程序员这讨厌的两件事说明了什么？

心有余而力不足。心里还是想写文档的，就是太累了。

所以，对此我们有解决方案吗？

有，核心的就是代码即文档，根据代码来生成文档。

这个 golang 在语言工具包里就整合了 go doc
这样的工具，能够根据代码和代码里的注释生成一个漂亮的文档。

Python 也有自己的方案，解决文档就是 Sphinx ，Python3.x 官方的文档就是用这个生成的。所以，如果你的也是 Python 项目，那么可以生成一个和官方文档同款的文档项目，非常实用和拉风。

Sphinx 怎么用？

先给大家看一张我本地生成文档项目的图，提提兴趣：

使用这个小工具，你就不用专门写文档项目了，只需要写好代码就好，代码即文档。

安装 sphinx 库

安装非常方便，就是一个简单的 Python 三方库，用 pip 安装就行了：

pip install Sphinx

安装完之后呢，应该有四个二进制文件：

sphinx-apidoc
sphinx-autogen
sphinx-build
sphinx-quickstart

如果呢，你没有找到这四个二进制文件，那么可以直接去找对应的 python 文件：

build.py
make_mode.py
quickstart.py

简单示例（ Spninx 使用）

搞了一个简单的示例，项目根目录是 ~/qiya/python-tools/
，下面都是以此目录为基础，下面的是我自己创建的目录，搞了几个简单的目录，common
，misc
是项目的代码目录，docs
是我预定的专门放文档的目录。

root@ubuntu:~/qiya/python-tools# tree 
.
├── common
│   ├── demo.py
│   └── __init__.py
├── docs
│   └── __init__.py
├── misc
│   └── __init__.py
│   └── tools.py
└── README.md

我先准备好演示用的代码项目：

demo 类文件：

tools 函数文件：

步骤一：Sphinx 创建出基础配置

执行 `sphinx-quickstart`

使用sphinx-quickstart
可以直接做初始化，能够完成简单的配置，生成一些基础的配置文件。

$ cd docs/
$ sphinx-quickstart

执行完这个命令，需要配置一些操作，信息如下：

sphinx-quickstart
命令执行完成之后，下面全都是自动生成的文件：

root@ubuntu:~/qiya/python-tools/docs# tree 
.
├── build
├── __init__.py
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

特意说下，重要的就是两个文件：

source/conf.py
：这个是 Sphinx 的配置，包括主题的设置，文档的生成形式，都可以在这里配置；
source/index.rst
：这个是项目的主页文件，rst 语法，类似于 markdown，都是一种标记类文档语言；

sphinx-quickstart
执行完之后呢，基础的东西是给你准备好了，接下来就是要根据自身的情况来配置。首先要看的就是 conf.py
这个配置文件，我们的目录是：

root@ubuntu:~/qiya/python-tools# tree 
.
├── common
│   ├── demo.py
│   └── __init__.py
├── docs
│   ├── build
│   ├── __init__.py
│   ├── make.bat
│   ├── Makefile
│   └── source
│       ├── conf.py
│       ├── index.rst
│       ├── _static
│       └── _templates
├── misc
│   ├── __init__.py
│   └── tools.py
└── README.md

配置 conf.py 文件

所以呢，我们要让 conf.py 找到代码，那么就要添加好路径，在开头修改，如下：

import sys
from os.path import abspath, dirname


# 为什么是上三层目录呢？conf.py 这个文件和根目录不就隔着三层目录嘛
sys.path.insert(0, dirname(dirname(dirname(abspath(__file__)))))

这样 Sphinx 就能找到你想要自动生成文档的代码了。下一步，添加 extensions ，说明咱们的文档可以自动生成：

# 指明用 autodoc 的形式生成
extensions = [
        'sphinx.ext.autodoc'
]


# 指明用 sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'

sphinx_rtd_theme
这个主题不是默认的，这个是一个比较好看的主题，这个可以直接用 pip 安装即可：

$ pip install sphinx_rtd_theme

conf.py
修改的样子如下：

步骤二：配置项目入口 index.rst

这个 index.rst 文件是入口，项目文档怎么生成，生成什么格式，就是这个文件里配置的（这里的配置是要和 conf 对应着来）。

************
Demo
************


common 公共库
=================


.. automodule:: common.demo
   :members:


misc 库
=================


.. automodule:: misc.tools
   :members:

解释下，这里的 common.demo
和 misc.tools
模块对应了 py 文件。这个怎么才能找到这两个模块，这个就跟你配置 conf.py 里面的 path 配置有关。

步骤三：生成项目文档

执行命令：

$ cd docs/
$ sphinx-build source/ build/

执行这个命令，就会自动去搜索代码，生成文档项目，默认生成的是 html 的文件。

这里顺带提一下，如果你想生成其他格式的项目文档，比如纯文本格式，那么可以执行：

$ cd docs/
$ sphinx-build -b text source/ build/

纯文本格式如下：

步骤四：展示出来

怎么看到效果呢？演示的话，开一个静态服务器就行，给大家演示一个 python 3 一键起一个静态服务器的命令：

$ python3 -m http.server 9000

显示效果：

来源 https://www.modb.pro/db/88849

相关文章