使用Sphinx构建软件说明书(3):构建文档工具

使用Sphinx构建软件说明书（3）：构建文档工具

微信公众号：生信小知识
关注可了解更多的生物信息学教程及知识。问题或建议，请公众号留言;

目录

前言1. sphinx-build 用法2. Makefile选项后记

前言

我决定使用Sphinx对开发的软件包写一个说明书，这里记录我学习Sphinx的记录。

所有知识来源：

• https://www.osgeo.cn/sphinx-note/intro.html
• Sphinx 1.3.1 中文手册 (推荐查看)

已发布教程：

• 使用Sphinx构建软件说明书（1）
• 使用Sphinx构建软件说明书（2）

1. sphinx-build 用法

sphinx-build 是一个脚本，也是一个命令，它才是构建了一个Sphinx文档集的关键。

一般情况下可以借助 Make 系统进行文档构建，但也可以编写自己的脚本，直接使用 sphinx-build 工具实现更加灵活的应用。

这里我们记录下 sphinx-build 的用法：

$ sphinx-build --help

usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

positional arguments:
  SOURCE_DIR            文档源文件地址
  OUTPUT_DIR            输出地址
  filenames             （可选）指定具体的源文件名

general options:
  --builder, -b BUILDER
                        构建文件类型，默认为【html】
  --jobs, -j N          多线程，指定数目
  --write-all, -a       构建所有文件， 默认仅重构有改动的文件

path options:
  --doctree-dir, -d PATH
                        存放doctree以及环境文件的地址【OUTPUT_DIR/.doctrees】
  --conf-dir, -c PATH   存放配置文件conf.py的地址【SOURCE_DIR】

build configuration options:
  --isolated, -C        不使用配置文件，只使用-D 规定的参数
  --define, -D setting=value
                        设置参数，以“-D setting=value”形式
  --html-define, -A name=value
                        给HTML templates模板传递变量

console output options:
  --verbose, -v         增加代码过程中的输出信息
  --quiet, -q           不输出提醒，只对错误提示
  --silent, -Q          什么都不输出
  --color               对输出的字符进行标色
  --no-color, -N        对输出的字符不进行标色

warning control options:
  --warning-file, -w FILE
                        将警告及报错导出到指定文件
  --fail-on-warning, -W
                        将警告转为报错
  --exception-on-warning
                        如果警告就停止

• sphinx-build会根据 SOURCEDIR 中的文件生成文档，并将其放入 OUTPUTDIR。
• 它会在 SOURCEDIR 中查找 “conf.py”，以获取配置设置。

2. Makefile选项

我们用 sphinx-quickstart 帮我生成了下面几个文件：

• Makefile

• build目录：空白
• make.bat
• source 目录
• _static：用于存放图片之类的多媒体文件
• _templates：
• conf.py：配置文件

• index.rst：主页文件

Makefile 只是一种编译的辅助工具，并不是必需的。在说其他任何事之前，让我们先来看看这个 Makefile 文件内容：

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
#"make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Makefile 主要是我们在Linux系统中，使用 make 命令时会可以使用到该文件。这里不做过多解释。

后记

这里我们重点记录了一些构建文档网页时的工具 sphinx-build ，至此我们已经完整掌握了具体构建工具的使用，接下来我们则主要学习下将所有有关文档进行整理合并，制作成一个完整的项目~