summaryrefslogtreecommitdiffstats
path: root/doc/man
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/man
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--doc/man/index.rst22
-rw-r--r--doc/man/sphinx-apidoc.rst171
-rw-r--r--doc/man/sphinx-autogen.rst97
-rw-r--r--doc/man/sphinx-build.rst355
-rw-r--r--doc/man/sphinx-quickstart.rst169
5 files changed, 814 insertions, 0 deletions
diff --git a/doc/man/index.rst b/doc/man/index.rst
new file mode 100644
index 0000000..1468022
--- /dev/null
+++ b/doc/man/index.rst
@@ -0,0 +1,22 @@
+Command-Line Tools
+==================
+
+These are the applications provided as part of Sphinx.
+
+Core Applications
+-----------------
+
+.. toctree::
+ :maxdepth: 3
+
+ sphinx-quickstart
+ sphinx-build
+
+Additional Applications
+-----------------------
+
+.. toctree::
+ :maxdepth: 3
+
+ sphinx-apidoc
+ sphinx-autogen
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
new file mode 100644
index 0000000..efc8230
--- /dev/null
+++ b/doc/man/sphinx-apidoc.rst
@@ -0,0 +1,171 @@
+sphinx-apidoc
+=============
+
+Synopsis
+--------
+
+**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*>
+[*EXCLUDE_PATTERN* ...]
+
+Description
+-----------
+
+:program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole
+package in the style of other automatic API documentation tools.
+
+*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
+the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s
+given are `fnmatch-style`_ file and/or directory patterns that will be excluded
+from generation.
+
+.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html
+
+.. warning::
+
+ ``sphinx-apidoc`` generates source files that use :mod:`sphinx.ext.autodoc`
+ to document all found modules. If any modules have side effects on import,
+ these will be executed by ``autodoc`` when ``sphinx-build`` is run.
+
+ If you document scripts (as opposed to library modules), make sure their main
+ routine is protected by a ``if __name__ == '__main__'`` condition.
+
+Options
+-------
+
+.. program:: sphinx-apidoc
+
+.. option:: -o <OUTPUT_PATH>
+
+ Directory to place the output files. If it does not exist, it is created.
+
+.. option:: -q
+
+ Do not output anything on standard output, only write warnings and errors to
+ standard error.
+
+.. option:: -f, --force
+
+ Force overwriting of any existing generated files.
+
+.. option:: -l, --follow-links
+
+ Follow symbolic links. Defaults to ``False``.
+
+.. option:: -n, --dry-run
+
+ Do not create any files.
+
+.. option:: -s <suffix>
+
+ Suffix for the source files generated. Defaults to ``rst``.
+
+.. option:: -d <MAXDEPTH>
+
+ Maximum depth for the generated table of contents file. Defaults to ``4``.
+
+.. option:: --tocfile
+
+ Filename for a table of contents file. Defaults to ``modules``.
+
+.. option:: -T, --no-toc
+
+ Do not create a table of contents file. Ignored when :option:`--full` is
+ provided.
+
+.. option:: -F, --full
+
+ Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using
+ the same mechanism as :program:`sphinx-quickstart`.
+
+.. option:: -e, --separate
+
+ Put documentation for each module on its own page.
+
+ .. versionadded:: 1.2
+
+.. option:: -E, --no-headings
+
+ Do not create headings for the modules/packages. This is useful, for
+ example, when docstrings already contain headings.
+
+.. option:: -P, --private
+
+ Include "_private" modules.
+
+ .. versionadded:: 1.2
+
+.. option:: --implicit-namespaces
+
+ By default sphinx-apidoc processes sys.path searching for modules only.
+ Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
+ structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+ (notice that ``bar`` and ``foo`` are namespaces, not modules).
+
+ Interpret paths recursively according to PEP-0420.
+
+.. option:: -M, --module-first
+
+ Put module documentation before submodule documentation.
+
+These options are used when :option:`--full` is specified:
+
+.. option:: -a
+
+ Append module_path to sys.path.
+
+.. option:: -H <project>
+
+ Sets the project name to put in generated files (see :confval:`project`).
+
+.. option:: -A <author>
+
+ Sets the author name(s) to put in generated files (see
+ :confval:`copyright`).
+
+.. option:: -V <version>
+
+ Sets the project version to put in generated files (see :confval:`version`).
+
+.. option:: -R <release>
+
+ Sets the project release to put in generated files (see :confval:`release`).
+
+.. rubric:: Project templating
+
+.. versionadded:: 2.2
+ Project templating options for sphinx-apidoc
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+ Template directory for template files. You can modify the templates of
+ sphinx project files generated by apidoc. Following Jinja2 template
+ files are allowed:
+
+ * ``module.rst_t``
+ * ``package.rst_t``
+ * ``toc.rst_t``
+ * ``root_doc.rst_t``
+ * ``conf.py_t``
+ * ``Makefile_t``
+ * ``Makefile.new_t``
+ * ``make.bat_t``
+ * ``make.bat.new_t``
+
+ In detail, please refer the system template files Sphinx provides.
+ (``sphinx/templates/apidoc`` and ``sphinx/templates/quickstart``)
+
+Environment
+-----------
+
+.. envvar:: SPHINX_APIDOC_OPTIONS
+
+ A comma-separated list of option to append to generated ``automodule``
+ directives. Defaults to ``members,undoc-members,show-inheritance``.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)`
+
+.. _fnmatch: https://docs.python.org/3/library/fnmatch.html
diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst
new file mode 100644
index 0000000..caeb44b
--- /dev/null
+++ b/doc/man/sphinx-autogen.rst
@@ -0,0 +1,97 @@
+sphinx-autogen
+==============
+
+Synopsis
+--------
+
+**sphinx-autogen** [*options*] <sourcefile> ...
+
+Description
+-----------
+
+:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
+in :rst:dir:`autosummary` listing(s).
+
+*sourcefile* is the path to one or more reStructuredText documents containing
+:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
+can be an :py:mod:`fnmatch`-style pattern.
+
+Options
+-------
+
+.. program:: sphinx-autogen
+
+.. option:: -o <outputdir>
+
+ Directory to place the output file. If it does not exist, it is created.
+ Defaults to the value passed to the ``:toctree:`` option.
+
+.. option:: -s <suffix>, --suffix <suffix>
+
+ Default suffix to use for generated files. Defaults to ``rst``.
+
+.. option:: -t <templates>, --templates <templates>
+
+ Custom template directory. Defaults to ``None``.
+
+.. option:: -i, --imported-members
+
+ Document imported members.
+
+.. option:: -a, --respect-module-all
+
+ Document exactly the members in a module's ``__all__`` attribute.
+
+Example
+-------
+
+Given the following directory structure::
+
+ docs
+ ├── index.rst
+ └── ...
+ foobar
+ ├── foo
+ │ └── __init__.py
+ └── bar
+ ├── __init__.py
+ └── baz
+ └── __init__.py
+
+and assuming ``docs/index.rst`` contained the following:
+
+.. code-block:: rst
+
+ Modules
+ =======
+
+ .. autosummary::
+ :toctree: modules
+
+ foobar.foo
+ foobar.bar
+ foobar.bar.baz
+
+If you run the following:
+
+.. code-block:: console
+
+ $ PYTHONPATH=. sphinx-autogen docs/index.rst
+
+then the following stub files will be created in ``docs``::
+
+ docs
+ ├── index.rst
+ └── modules
+ ├── foobar.bar.rst
+ ├── foobar.bar.baz.rst
+ └── foobar.foo.rst
+
+and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
+and some other information.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
new file mode 100644
index 0000000..a1fb9be
--- /dev/null
+++ b/doc/man/sphinx-build.rst
@@ -0,0 +1,355 @@
+sphinx-build
+============
+
+Synopsis
+--------
+
+**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
+
+Description
+-----------
+
+:program:`sphinx-build` generates documentation from the files in
+``<sourcedir>`` and places it in the ``<outputdir>``.
+
+:program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
+settings. :manpage:`sphinx-quickstart(1)` may be used to generate template
+files, including ``conf.py``.
+
+:program:`sphinx-build` can create documentation in different formats. A
+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`.
+
+By default, everything that is outdated is built. Output only for selected
+files can be built by specifying individual filenames.
+
+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.
+
+ **xml**
+ Build Docutils-native XML files.
+
+ **pseudoxml**
+ Build compact pretty-printed "pseudo-XML" files displaying the
+ internal structure of the intermediate document trees.
+
+ See :doc:`/usage/builders/index` for a list of all builders shipped with
+ Sphinx. Extensions can add their own builders.
+
+.. _make_mode:
+
+.. option:: -M buildername
+
+ 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**
+ 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**
+ Build Texinfo files and run them through :program:`makeinfo`.
+
+ .. important::
+ Sphinx only recognizes the ``-M`` option if it is placed first.
+
+ .. versionadded:: 1.2.1
+
+.. option:: -a
+
+ 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
+
+ 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
+
+ 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
+
+ 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".
+ Normally, these files are put in a directory called :file:`.doctrees` under
+ the build directory; with this option you can select a different cache
+ directory (the doctrees can be shared between all builders).
+
+.. option:: -j N, --jobs N
+
+ Distribute the build over *N* processes in parallel, to make building on
+ multiprocessor machines more effective. Note that not all parts and not all
+ builders of Sphinx can be parallelized. If ``auto`` argument is given,
+ Sphinx uses the number of CPUs as *N*.
+
+ .. versionadded:: 1.2
+ This option should be considered *experimental*.
+
+ .. versionchanged:: 1.7
+ Support ``auto`` argument.
+
+ .. versionchanged:: 6.2
+ Add ``--jobs`` long option.
+
+.. option:: -c 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
+ given by configuration values are expected to be relative to the
+ configuration directory, so they will have to be present at this location
+ too.
+
+ .. versionadded:: 0.3
+
+.. option:: -C
+
+ Don't look for a configuration file; only take options via the ``-D`` option.
+
+ .. versionadded:: 0.5
+
+.. option:: -D setting=value
+
+ Override a configuration value set in the :file:`conf.py` file. The value
+ must be a number, string, list or dictionary value.
+
+ For lists, you can separate elements with a comma like this: ``-D
+ html_theme_path=path1,path2``.
+
+ For dictionary values, supply the setting name and key like this:
+ ``-D latex_elements.docclass=scrartcl``.
+
+ For boolean values, use ``0`` or ``1`` as the value.
+
+ .. versionchanged:: 0.6
+ The value can now be a dictionary value.
+
+ .. versionchanged:: 1.3
+ The value can now also be a list value.
+
+.. option:: -A name=value
+
+ Make the *name* assigned to *value* in the HTML templates.
+
+ .. versionadded:: 0.5
+
+.. option:: -n
+
+ 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".
+
+.. option:: -N, --no-color
+
+ Do not emit colored output.
+
+ .. versionchanged:: 1.6
+ Add ``--no-color`` long option.
+
+.. option:: --color
+
+ Emit colored output. Auto-detected by default.
+
+ .. versionadded:: 1.6
+
+.. option:: -v
+
+ Increase verbosity (loglevel). This option can be given up to three times
+ to get more debug logging output. It implies :option:`-T`.
+
+ .. versionadded:: 1.2
+
+.. option:: -q
+
+ Do not output anything on standard output, only write warnings and errors to
+ standard error.
+
+.. option:: -Q
+
+ Do not output anything on standard output, also suppress warnings. Only
+ errors are written to standard error.
+
+.. option:: -w file
+
+ Write warnings (and errors) to the given file, in addition to standard error.
+
+.. option:: -W
+
+ Turn warnings into errors. This means that the build stops at the first
+ warning and ``sphinx-build`` exits with exit status 1.
+
+.. option:: --keep-going
+
+ With -W option, keep going processing when getting warnings to the end
+ of build, and ``sphinx-build`` exits with exit status 1.
+
+ .. versionadded:: 1.8
+
+.. option:: -T
+
+ Display the full traceback when an unhandled exception occurs. Otherwise,
+ only a summary is displayed and the traceback information is saved to a file
+ for further analysis.
+
+ .. versionadded:: 1.2
+
+.. option:: -P
+
+ (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an
+ unhandled exception occurs while building.
+
+.. option:: -h, --help, --version
+
+ Display usage summary or Sphinx version.
+
+ .. versionadded:: 1.2
+
+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).
+
+Environment Variables
+---------------------
+
+The :program:`sphinx-build` refers following environment variables:
+
+.. describe:: MAKE
+
+ A path to make command. A command name is also allowed.
+ :program:`sphinx-build` uses it to invoke sub-build process on make-mode.
+
+.. _makefile_options:
+
+.. rubric:: Makefile Options
+
+The :file:`Makefile` and :file:`make.bat` files created by
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options. However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+ This sets the ``'papersize'`` key of :confval:`latex_elements`:
+ i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to
+ ``'letterpaper'``.
+
+ .. note::
+
+ Usage of this environment variable got broken at Sphinx 1.5 as
+ ``a4`` or ``letter`` ended up as option to LaTeX document in
+ place of the needed ``a4paper``, resp. ``letterpaper``. Fixed at
+ 1.7.7.
+
+.. describe:: SPHINXBUILD
+
+ The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+ The build directory to use instead of the one chosen in
+ :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+ Additional options for :program:`sphinx-build`. These options can
+ also be set via the shortcut variable **O** (capital 'o').
+
+.. describe:: NO_COLOR
+
+ When set (regardless of value), :program:`sphinx-build` will not use color
+ in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. See
+ `no-color.org <https://no-color.org/>`__ for other libraries supporting this
+ community standard.
+
+ .. versionadded:: 4.5.0
+
+.. describe:: FORCE_COLOR
+
+ When set (regardless of value), :program:`sphinx-build` will use color in
+ terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``.
+
+ .. versionadded:: 4.5.0
+
+.. _when-deprecation-warnings-are-displayed:
+
+Deprecation Warnings
+--------------------
+
+If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed
+when building a user's document, some Sphinx extension is using deprecated
+features. In that case, please report it to author of the extension.
+
+To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment
+variable to your environment. For example:
+
+* ``PYTHONWARNINGS= make html`` (Linux/Mac)
+* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
+* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
+* modify your Makefile/make.bat and set the environment variable
+
+See also
+--------
+
+:manpage:`sphinx-quickstart(1)`
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
new file mode 100644
index 0000000..d050a29
--- /dev/null
+++ b/doc/man/sphinx-quickstart.rst
@@ -0,0 +1,169 @@
+sphinx-quickstart
+=================
+
+Synopsis
+--------
+
+**sphinx-quickstart**
+
+Description
+-----------
+
+:program:`sphinx-quickstart` is an interactive tool that asks some questions
+about your project and then generates a complete documentation directory and
+sample Makefile to be used with :manpage:`sphinx-build(1)`.
+
+Options
+-------
+
+.. program:: sphinx-quickstart
+
+.. option:: -q, --quiet
+
+ Quiet mode that skips the interactive wizard for specifying options.
+ This option requires `-p`, `-a` and `-v` options.
+
+.. option:: -h, --help, --version
+
+ Display usage summary or Sphinx version.
+
+.. rubric:: Structure Options
+
+.. option:: --sep
+
+ If specified, separate source and build directories.
+
+.. option:: --no-sep
+
+ If specified, create build directory under source directory.
+
+.. option:: --dot=DOT
+
+ Inside the root directory, two more directories will be created;
+ "_templates" for custom HTML templates and "_static" for custom stylesheets
+ and other static files. You can enter another prefix (such as ".") to
+ replace the underscore.
+
+.. rubric:: Project Basic Options
+
+.. option:: -p PROJECT, --project=PROJECT
+
+ Project name will be set. (see :confval:`project`).
+
+.. option:: -a AUTHOR, --author=AUTHOR
+
+ Author names. (see :confval:`copyright`).
+
+.. option:: -v VERSION
+
+ Version of project. (see :confval:`version`).
+
+.. option:: -r RELEASE, --release=RELEASE
+
+ Release of project. (see :confval:`release`).
+
+.. option:: -l LANGUAGE, --language=LANGUAGE
+
+ Document language. (see :confval:`language`).
+
+.. option:: --suffix=SUFFIX
+
+ Source file suffix. (see :confval:`source_suffix`).
+
+.. option:: --master=MASTER
+
+ Master document name. (see :confval:`root_doc`).
+
+.. rubric:: Extension Options
+
+.. option:: --ext-autodoc
+
+ Enable :py:mod:`sphinx.ext.autodoc` extension.
+
+.. option:: --ext-doctest
+
+ Enable `sphinx.ext.doctest` extension.
+
+.. option:: --ext-intersphinx
+
+ Enable `sphinx.ext.intersphinx` extension.
+
+.. option:: --ext-todo
+
+ Enable `sphinx.ext.todo` extension.
+
+.. option:: --ext-coverage
+
+ Enable `sphinx.ext.coverage` extension.
+
+.. option:: --ext-imgmath
+
+ Enable `sphinx.ext.imgmath` extension.
+
+.. option:: --ext-mathjax
+
+ Enable `sphinx.ext.mathjax` extension.
+
+.. option:: --ext-ifconfig
+
+ Enable `sphinx.ext.ifconfig` extension.
+
+.. option:: --ext-viewcode
+
+ Enable `sphinx.ext.viewcode` extension.
+
+.. option:: --ext-githubpages
+
+ Enable `sphinx.ext.githubpages` extension.
+
+.. option:: --extensions=EXTENSIONS
+
+ Enable arbitrary extensions.
+
+.. rubric:: Makefile and Batchfile Creation Options
+
+.. option:: --use-make-mode (-m), --no-use-make-mode (-M)
+
+ :file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode <make_mode>`.
+ Default is ``use``, which generates a more concise :file:`Makefile/make.bat`.
+
+ .. versionchanged:: 1.5
+ make-mode is default.
+
+.. option:: --makefile, --no-makefile
+
+ Create (or not create) makefile.
+
+.. option:: --batchfile, --no-batchfile
+
+ Create (or not create) batchfile
+
+.. rubric:: Project templating
+
+.. versionadded:: 1.5
+ Project templating options for sphinx-quickstart
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+ Template directory for template files. You can modify the templates of
+ sphinx project files generated by quickstart. Following Jinja2 template
+ files are allowed:
+
+ * ``root_doc.rst_t``
+ * ``conf.py_t``
+ * ``Makefile_t``
+ * ``Makefile.new_t``
+ * ``make.bat_t``
+ * ``make.bat.new_t``
+
+ In detail, please refer the system template files Sphinx provides.
+ (``sphinx/templates/quickstart``)
+
+.. option:: -d NAME=VALUE
+
+ Define a template variable
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`