sphinx 文档生成器

发表于 | 分类于 | 阅读次数

QEMU 使用Sphinx工具生成文档，简单入门一下Sphinx

概述

Sphinx是一个 python 项目，用于生成文档。

概念

  • 源目录：放置文档集合的根目录，在 QEMU 中就是/docs目录。通常包含Sphinx配置文件conf.py，在该配置文件中可设置读取源文件的读取方式以及如何生成文件等等；
  • conf.py：配置文件
  • index.rst：master file，主文件，包含了一个欢迎页面和一个树状内容表。

使用

sphinx-quickstart

使用sphinx-quickstart脚手架生成源目录，并且生成一个conf.py和index.rst文件

1
$ sphinx-quickstart

index.rst文件作为一个主文件，包含了一个树状内容表，使用reStructuredText的 toctree 指令指定了整个文档列表：

.. QEMU documentation master file, created by
   sphinx-quickstart on Thu Jan 31 16:40:14 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to QEMU's documentation!
================================

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

   system/index
   user/index
   tools/index
   interop/index
   specs/index
   devel/index

.. This is the top level page for the 'system' manual.


QEMU System Emulation User's Guide
==================================

This manual is the overall guide for users using QEMU
for full system emulation (as opposed to user-mode emulation).
This includes working with hypervisors such as KVM, Xen, Hax
or Hypervisor.Framework.

Contents:

.. toctree::
   :maxdepth: 3

   quickstart
   invocation
   keys
   mux-chardev
   monitor
   images
   net
   usb
   ivshmem
   linuxboot
   vnc-security
   tls
   gdb
   managed-startup
   targets
   security
   deprecated
   build-platforms
   license

sphinx-build

通过sphinx-build构建文档

1
$ sphinx-build -b html sourcedir builddir

或者使用生成的Makefile文件，该文件中描述了各种可以生成的文档格式。

当然你也可以在自己的 Makefile 文件中添加sphinx-build指令用于构建文档。

QEMU 中构建 docs

QEMU 在公网上提供了相关的文档 https://www.qemu.org/docs/master/，但是 developers Guide 目录没有暴露出来。可以看 Makefile 中 install-sphinxdocs 部分注释：

1
2
3
4
5
6
7
8
9
# Note that we deliberately do not install the "devel" manual: it is
# for QEMU developers, and not interesting to our users.
.PHONY: install-sphinxdocs
install-sphinxdocs: sphinxdocs
	$(call install-manual,interop)
	$(call install-manual,specs)
	$(call install-manual,system)
	$(call install-manual,tools)
	$(call install-manual,user)

如果开发者想要看到相关的文档，需要自己编译一下：

1
2
3
4
5
6
7
$ mkdir qemu-comp && cd qemu-comp
$ ../qemu/configure --prefix='/code/qemu-comp/install' --target-list="x86_64-softmmu"
$ make sphinxdocs -j8
# 将 docs 目录当作网站提供出来
$ python -m SimpleHTTPServer
# 你也可以使用 make install-sphinxdocs 安装，但是 devel 是不会被安装的。
$ make install-sphinxdocs

在浏览器中输入地址和默认端口 8000，就可以看到目录了，点击 devel，可以看到QEMU Developer's Guide。

在使用高版本 sphinx 生成 5.0 版本 QEMU 文档时，可能会出现错误

1
2
3
docs/qemu-option-trace.rst.inc:4:Malformed option description
  '[enable=]PATTERN', should look like "opt", "-opt args",
  "--opt args", "/opt args" or "+opt args"

参考红帽的支持文档。