python sphinx_Python Sphinx 生成简洁大方的文档

原标题:Python Sphinx 生成简洁大方的文档

安装 sphinx 库

简单示例( Spninx 使用 )

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

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

步骤三:生成项目文档

步骤四:展示出来

小小总结Sphinx 简介

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

程序员最讨厌的两件事:

自己写代码文档

别人的代码没文档

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

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

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

所以,对此我们有解决方案吗?

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

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

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

Sphinx 怎么用?

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

python sphinx_Python Sphinx 生成简洁大方的文档_第1张图片

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

安装 sphinx 库

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

pip install Sphinx

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

sphinx-apidoc

sphinx-autogen

sphinx-build

sphinx-quickstart

python sphinx_Python Sphinx 生成简洁大方的文档_第2张图片

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

build.py

make_mode.py

quickstart.py

python sphinx_Python Sphinx 生成简洁大方的文档_第3张图片

简单示例( 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 类文件:

python sphinx_Python Sphinx 生成简洁大方的文档_第4张图片

tools 函数文件:

python sphinx_Python Sphinx 生成简洁大方的文档_第5张图片

步骤一:Sphinx 创建出基础配置 执行 sphinx-quickstart

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

$ cd docs/ $ sphinx-quickstart

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

python sphinx_Python Sphinx 生成简洁大方的文档_第6张图片

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 修改的样子如下:

python sphinx_Python Sphinx 生成简洁大方的文档_第7张图片

python sphinx_Python Sphinx 生成简洁大方的文档_第8张图片

步骤二:配置项目入口 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 的文件。

python sphinx_Python Sphinx 生成简洁大方的文档_第9张图片

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

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

纯文本格式如下:

步骤四:展示出来

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

$ python3 -m http.server 9000

python sphinx_Python Sphinx 生成简洁大方的文档_第10张图片

显示效果:

python sphinx_Python Sphinx 生成简洁大方的文档_第11张图片

小小总结

希望大家写好代码,名字易读,注释规范,这样就自然有好的文档了。还有就是,这个 Sphinx 工具其实不仅适用于 Python,其他语言也能适用,大家可以探索。 关键思考:代码即文档。 返回搜狐,查看更多

责任编辑:

你可能感兴趣的:(python,sphinx)