Sphinx文档生成器

技术交流
1

Sphinx文档生成器是一款将纯文本转换为各种格式文件的工具软件。

  • 配置文件：conf.py

启动

安装

安装方式见这里，开始文档见这里。

 Debian: sudo apt-get install python3-sphinx
 Windows: pip install -U sphinx

虚拟环境

建议在虚拟环境中安装相关包，使其和系统默认包分开。

python -m venv .venv

创建源目录 

makedir myproject
cd myproject

创建一个项目

sphinx-quickstart

定义文档结构

在index.rst中加入目录树指令块以显示目录，见示例：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test
   ...

编写文档

撰写Markdown文档…

编译

Windows: makebat.exe html
Debian: make html

在_build/html中生成系统HTML文件。

主题

Sphinx Themes Gallery、Sphinx Themes提供了丰富的主题包，在conf.py中设定主题，示例：

html_theme='sphinx_book_theme'

插件

MyST

MyST解析器插件将Markdown文档转换为HTML文件。

  • 安装：
    pip install myst-parser
  • 配置
    extensions = ["myst_parser"]
    完成配置后，在整个项目编译时会将所有.md文件统一编译为HTML。

sphinxcontrib-video

将视频插入到网页之中。

  • 安装：
    pip install sphinxcontrib-video
  • 配置
    extensions = ['sphinxcontrib.video']
  • 示例
    .. video:: path/to/video.mp4
   :width: 500
   :height: 300
   :autoplay:
   :nocontrols: