diff options
Diffstat (limited to 'doc/man/sphinx-build.rst')
| -rw-r--r-- | doc/man/sphinx-build.rst | 191 |
1 files changed, 107 insertions, 84 deletions
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index a1fb9be..8be2780 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -20,7 +20,7 @@ files, including ``conf.py``. format is selected by specifying the builder name on the command line; it defaults to HTML. Builders can also perform other tasks related to documentation processing. For a list of available builders, refer to -:option:`sphinx-build -b`. +:doc:`/usage/builders/index`. By default, everything that is outdated is built. Output only for selected files can be built by specifying individual filenames. @@ -30,107 +30,87 @@ Options .. program:: sphinx-build -.. option:: -b buildername - - The most important option: it selects a builder. The most common builders - are: - - **html** - Build HTML pages. This is the default builder. - - **dirhtml** - Build HTML pages, but with a single directory per document. Makes for - prettier URLs (no ``.html``) if served from a webserver. - - **singlehtml** - Build a single HTML with the whole content. - - **htmlhelp**, **qthelp**, **devhelp**, **epub** - Build HTML files with additional information for building a documentation - collection in one of these formats. - - **applehelp** - Build an Apple Help Book. Requires :program:`hiutil` and - :program:`codesign`, which are not Open Source and presently only - available on Mac OS X 10.6 and higher. - - **latex** - Build LaTeX sources that can be compiled to a PDF document using - :program:`pdflatex`. - - **man** - Build manual pages in groff format for UNIX systems. - - **texinfo** - Build Texinfo files that can be processed into Info files using - :program:`makeinfo`. - - **text** - Build plain text files. - - **gettext** - Build gettext-style message catalogs (``.pot`` files). - - **doctest** - Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest` - extension is enabled. - - **linkcheck** - Check the integrity of all external links. +.. _make_mode: - **xml** - Build Docutils-native XML files. +.. option:: -M buildername - **pseudoxml** - Build compact pretty-printed "pseudo-XML" files displaying the - internal structure of the intermediate document trees. + Select a builder, using the *make-mode*. + See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders. + Extensions can add their own builders. - See :doc:`/usage/builders/index` for a list of all builders shipped with - Sphinx. Extensions can add their own builders. + .. important:: + Sphinx only recognizes the ``-M`` option if it is used first, along with + the source and output directories, before any other options are passed. + For example:: -.. _make_mode: + sphinx-build -M html ./source ./build -W --keep-going -.. option:: -M buildername + The *make-mode* provides the same build functionality as + a default :ref:`Makefile or Make.bat <makefile_options>`, + and provides the following additional build pipelines: - Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module, - which provides the same build functionality as a default :ref:`Makefile or - Make.bat <makefile_options>`. In addition to all Sphinx - :doc:`/usage/builders/index`, the following build pipelines are available: - - **latexpdf** + *latexpdf* Build LaTeX files and run them through :program:`pdflatex`, or as per :confval:`latex_engine` setting. If :confval:`language` is set to ``'ja'``, will use automatically the :program:`platex/dvipdfmx` latex to PDF pipeline. - **info** + *info* Build Texinfo files and run them through :program:`makeinfo`. - .. important:: - Sphinx only recognizes the ``-M`` option if it is placed first. + .. note:: + + The default output directory locations when using *make-mode* + differ from the defaults when using :option:`-b`. + + * doctrees are saved to ``<outputdir>/doctrees`` + * output files are saved to ``<outputdir>/<builder name>`` .. versionadded:: 1.2.1 -.. option:: -a +.. option:: -b buildername, --builder buildername + + Selects a builder. + + See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders. + Extensions can add their own builders. + + .. versionchanged:: 7.3 + Add ``--builder`` long option. + +.. option:: -a, --write-all If given, always write all output files. The default is to only write output files for new and changed source files. (This may not apply to all builders.) -.. option:: -E + .. note:: This option does not re-read source files. + To read and re-process every file, + use :option:`--fresh-env` instead. + + .. versionchanged:: 7.3 + Add ``--write-all`` long option. + +.. option:: -E, --fresh-env Don't use a saved :term:`environment` (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. -.. option:: -t tag + .. versionchanged:: 7.3 + Add ``--fresh-env`` long option. + +.. option:: -t tag, --tag tag Define the tag *tag*. This is relevant for :rst:dir:`only` directives that only include their content if this tag is set. .. versionadded:: 0.6 -.. option:: -d path + .. versionchanged:: 7.3 + Add ``--tag`` long option. + +.. option:: -d path, --doctree-dir path Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as "doctree pickles". @@ -138,6 +118,9 @@ Options the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders). + .. versionchanged:: 7.3 + Add ``--doctree-dir`` long option. + .. option:: -j N, --jobs N Distribute the build over *N* processes in parallel, to make building on @@ -154,7 +137,7 @@ Options .. versionchanged:: 6.2 Add ``--jobs`` long option. -.. option:: -c path +.. option:: -c path, --config-dir path Don't look for the :file:`conf.py` in the source directory, but use the given configuration directory instead. Note that various other files and paths @@ -164,13 +147,19 @@ Options .. versionadded:: 0.3 -.. option:: -C + .. versionchanged:: 7.3 + Add ``--config-dir`` long option. - Don't look for a configuration file; only take options via the ``-D`` option. +.. option:: -C, --isolated + + Don't look for a configuration file; only take options via the :option:`--define` option. .. versionadded:: 0.5 -.. option:: -D setting=value + .. versionchanged:: 7.3 + Add ``--isolated`` long option. + +.. option:: -D setting=value, --define setting=value Override a configuration value set in the :file:`conf.py` file. The value must be a number, string, list or dictionary value. @@ -189,18 +178,27 @@ Options .. versionchanged:: 1.3 The value can now also be a list value. -.. option:: -A name=value + .. versionchanged:: 7.3 + Add ``--define`` long option. + +.. option:: -A name=value, --html-define name=value Make the *name* assigned to *value* in the HTML templates. .. versionadded:: 0.5 -.. option:: -n + .. versionchanged:: 7.3 + Add ``--html-define`` long option. + +.. option:: -n, --nitpicky Run in nit-picky mode. Currently, this generates warnings for all missing references. See the config value :confval:`nitpick_ignore` for a way to exclude some references as "known missing". + .. versionchanged:: 7.3 + Add ``--nitpicky`` long option. + .. option:: -N, --no-color Do not emit colored output. @@ -214,32 +212,51 @@ Options .. versionadded:: 1.6 -.. option:: -v +.. option:: -v, --verbose - Increase verbosity (loglevel). This option can be given up to three times + Increase verbosity (log-level). This option can be given up to three times to get more debug logging output. It implies :option:`-T`. .. versionadded:: 1.2 -.. option:: -q + .. versionchanged:: 7.3 + Add ``--verbose`` long option. + +.. option:: -q, --quiet Do not output anything on standard output, only write warnings and errors to standard error. -.. option:: -Q + .. versionchanged:: 7.3 + Add ``--quiet`` long option. + +.. option:: -Q, --silent Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. -.. option:: -w file + .. versionchanged:: 7.3 + Add ``--silent`` long option. + +.. option:: -w file, --warning-file file Write warnings (and errors) to the given file, in addition to standard error. -.. option:: -W + .. versionchanged:: 7.3 + + ANSI control sequences are stripped when writing to *file*. + + .. versionchanged:: 7.3 + Add ``--warning-file`` long option. + +.. option:: -W, --fail-on-warning Turn warnings into errors. This means that the build stops at the first warning and ``sphinx-build`` exits with exit status 1. + .. versionchanged:: 7.3 + Add ``--fail-on-warning`` long option. + .. option:: --keep-going With -W option, keep going processing when getting warnings to the end @@ -247,7 +264,7 @@ Options .. versionadded:: 1.8 -.. option:: -T +.. option:: -T, --show-traceback Display the full traceback when an unhandled exception occurs. Otherwise, only a summary is displayed and the traceback information is saved to a file @@ -255,11 +272,17 @@ Options .. versionadded:: 1.2 -.. option:: -P + .. versionchanged:: 7.3 + Add ``--show-traceback`` long option. + +.. option:: -P, --pdb (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. + .. versionchanged:: 7.3 + Add ``--pdb`` long option. + .. option:: -h, --help, --version Display usage summary or Sphinx version. |