.. _invocation:

使用 sphinx-build
==========================

:program:`sphinx-build` 脚本用以进行 Sphinx 文档的构筑.
如下使用::

     $ sphinx-build [options] sourcedir builddir [filenames]

*sourcedir* 指向 :term:`source directory`, 
而 *builddir* 是指构筑出的文档你想放置的目标路径.
多数情况,你用不到 *filenames*.

:program:`sphinx-build` 脚本支持一系列参数:

.. option:: -b buildername

   其中最重要的是: 指明使用什么构筑器.  
   常见的有:

   **html**
      构筑为 HTML 页面,这是默认构筑器.

   **dirhtml**
      构筑为 HTML 页面,不过输出到单一目录中,并为web发布制作为美化URL(不是 ``.html``).

   **singlehtml**
      构筑为包含所有内容的单页HTML .

   **htmlhelp**, **qthelp**, **devhelp**, **epub**
      构筑为HTML 文件,并配合附加信息,打包成以上格式中指定的一种.

   **latex**
      构筑为 LaTeX 源码,以便使用 :program:`pdflatex` 编译成 PDF 文档.

   **man**
      构筑为手册页面,使用UNIX系统中的 groff 格式.

   **text**
      构筑为纯文本文件.

   **gettext**
      构筑为 ``gettext-style`` 消息索引 (``.pot`` 文档).

   **doctest**
      如果 :mod:`~sphinx.ext.doctest` 扩展已激活,执行所有文档中的 doctests .

   **linkcheck**
      检查所有外部链接的完整性

   参考 :ref:`builders` 列出所有Sphinx 内置的构筑器.
   扩展可以拥有自个儿的构筑器.

.. option:: -a

   一但设置,总是输出所有文件.
   默认是只输出有更新的. (这一选项不是所有构筑器都支持)

.. option:: -E

   不使用保存的 :term:`environment` (缓存了所有交叉索引),而是重建一切.
   默认是只读取和处置相对前次构筑有变化的文件.

.. option:: -t tag

    定义标签 *tag*.  这是有关 :rst:dir:`only` 指令的,
    将仅处理指定标签目录中的内容.

   .. versionadded:: 0.6

.. option:: -d path

   因为 Sphinx 在输出前将尽力读取和处理所有源文件,
   处理中的源文件将缓存在 "doctree pickles",通常会在构筑目录的 :file:`.doctrees` 文件夹里.
   这个参数可以由你选择缓存目录( :file:`.doctrees` 文件夹可以为所有构筑器共享)

.. option:: -c path

   不用到源文件目录找 :file:`conf.py` ,
   使用指定的配置文件.
   注意在配置文件中提及的路径都是相对配置文件所在目录的,
   所以,他们也应该在同一路径中.

   .. versionadded:: 0.3

.. option:: -C

   不寻找配置文件,使用参数 ``-D`` 给出的.

   .. versionadded:: 0.5

.. option:: -D setting=value

   覆盖配置文件 :file:`conf.py` 中的设置.
   该设置必须是一个字符串或字典值.
   对于后者,可以这样来设置键值: ``- D latex_elements.docclass= scrartcl``
   对于布尔值用 ``0`` 或 ``1`` .
   
   .. versionchanged:: 0.6
      现在可以使用字典值了.

.. option:: -A name=value

   对HTML 模板中的 *name* 绑定 *value* .

   .. versionadded:: 0.5

.. option:: -n

   以挑剔模式运行.目前,这将产生所有引用丢失的警告.

.. option:: -N

   不要产生颜色输出
   (在Windows,这不是个选项,因为根本没有)

.. option:: -q

   不要输出任何信息.仅将报警和错误输出到标准错误.

.. option:: -Q

   不要输出任何信息,包括控制警报.仅将报警和错误输出到标准错误.

.. option:: -w file

   将警告(和错误)写入给定的文件,代替标准错误的输出.

.. option:: -W

   将警告变为错误,这意味着只要遇到警告就会终止构筑, ``sphinx-build`` 的退出状态将是 1.

.. option:: -P

   (仅在调试时有用)  在构筑文档时,发生未处理的异常就运行Python 调试器, :mod:`pdb`



你也可以在命令行中给定一个或多个文件名,以及构筑目录,
Sphinx 将尝试只对给出的文件(以及它们依赖的)进行构筑.

.. You can also give one or more filenames on the command line after the source and build directories.  Sphinx will then try to build only these output files (and their dependencies).


Makefile 配置
----------------

:file:`Makefile` 和 :file:`make.bat` 是由 :program:`sphinx-quickstart` 创建的,
通常我们使用只有 :option:`-b` 和 :option:`-d` 选项的 program:`sphinx-build` 来完成文档构筑.
然而,他们支持以下自定义行为的选项:

.. describe:: PAPER

   配置项 :confval:`latex_paper_size` 的值

.. describe:: SPHINXBUILD

   替代 ``sphinx-build`` 的命令

.. describe:: BUILDDIR

   替代在 :program:`sphinx-quickstart` 中指定的构筑目录.

.. describe:: SPHINXOPTS

   :program:`sphinx-build` 的附加选项.