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 |
|
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 |
|
或者使用生成的Makefile
文件,该文件中描述了各种可以生成的文档格式。
当然你也可以在自己的 Makefile 文件中添加sphinx-build
指令用于构建文档。
QEMU 中构建 docs
QEMU 在公网上提供了相关的文档 https://www.qemu.org/docs/master/,但是 developers Guide 目录没有暴露出来。可以看 Makefile 中 install-sphinxdocs 部分注释:
1 |
|
如果开发者想要看到相关的文档,需要自己编译一下:
1 |
|
在浏览器中输入地址和默认端口 8000,就可以看到目录了,点击 devel,可以看到QEMU Developer's Guide
。
在使用高版本 sphinx 生成 5.0 版本 QEMU 文档时,可能会出现错误
1
2
3docs/qemu-option-trace.rst.inc:4:Malformed option description '[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"
参考红帽的支持文档。