【Python】Sphinx 文档生成器

目录

1. Sphinx 介绍

2. Sphinx 实战

2.1. 初始化 Sphinx 工程

2.2. 编译项目

2.3. Sphinx 主题

2.4. 增加 Sphinx 文档


1. Sphinx 介绍

Sphinx是一个Python文档生成器,它基于reStructuredText标记语言,可自动根据项目生成HTML,PDF等格式的文档。Sphinx可以令人轻松的撰写出清晰且优美的文档,除了天然支持Python项目以外,Sphinx对C/C++项目也有很好的支持,并在不断增加对其它开发语言的支持 。

如果您需要编写技术文档,可以用reStructuredText或Markdown格式编辑文件,然后使用Sphinx工具转换成html、PDF、ePub等格式,或者托管到GitHub并导入ReadtheDocs网站 。

2. Sphinx 实战

2.1. 初始化 Sphinx 工程

  • 创建项目目录
mkdir sphinx-doc
cd sphinx-doc
  • 初始化命令
sphinx-quickstart
  • 命令输出结果

【Python】Sphinx 文档生成器_第1张图片

  • 项目文件结构
│  make.bat
│  Makefile
├─build
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates

2.2. 编译项目

  • 编译为本地文件
make html

build 目录下生成如下文件

│  make.bat
│  Makefile
├─build
│  ├─doctrees
│  │      environment.pickle
│  │      index.doctree
│  └─html
│      │  .buildinfo
│      │  genindex.html
│      │  index.html  # 这个文件可直接用浏览器打开
│      │  objects.inv
│      │  search.html
│      │  searchindex.js
│      │
│      ├─_sources
│      │      index.rst.txt
│      │
│      └─_static
│              alabaster.css
│              basic.css
│              custom.css
│              doctools.js
│              documentation_options.js
│              file.png
│              jquery-3.5.1.js
│              jquery.js
│              language_data.js
│              minus.png
│              plus.png
│              pygments.css
│              searchtools.js
│              translations.js
│              underscore-1.13.1.js
│              underscore.js
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates

用浏览器打开 build\html\index.rst 可以看到

【Python】Sphinx 文档生成器_第2张图片

  • 编译为 HTTP 服务

make html 的编译方式需要打开 html 文件才能查看,使用如下命令则可以使用 HTTP 服务的形式来查看。

sphinx-autobuild source build/html

命令执行结果为

【Python】Sphinx 文档生成器_第3张图片

 可以通过 http://127.0.0.1:8000/ 查看。

2.3. Sphinx 主题

Sphinx 模型主题是 alabaster,可以通过 https://sphinx-themes.org/ 查看 sphinx 更多的主题。

【Python】Sphinx 文档生成器_第4张图片

 接下来切换一个比较明显的主题 groundwork-sphinx-theme,打开 source/conf.py 做如下修改

# html_theme = 'alabaster'
html_theme = 'groundwork'

2.4. 增加 Sphinx 文档

  • 新的项目文件结构如下
│  make.bat
│  Makefile
└─source
    │  conf.py
    │  index.rst
    ├─_static
    ├─_templates
    └─文章
        │  index.rst
        ├─第一章
        │      index.rst
        └─第二章
                index.rst

预览结果如下:

【Python】Sphinx 文档生成器_第5张图片

3. 项目源码

https://gitee.com/hl0929/sphinx-doc.git

你可能感兴趣的:(Python,sphinx,全文检索,搜索引擎)