sphinx文档生成器

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

概述

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

概念

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

使用

sphinx-quickstart

使用sphinx-quickstart脚手架生成源目录,并且生成一个conf.pyindex.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"

参考红帽的支持文档