Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 802 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..3ce5b45
--- /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 :rst:dir:`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.
+
+.. 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.
+
+.. 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..cad22bf
--- /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 :rst:dir:`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 :rst:dir:`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..9bba4a5
--- /dev/null
+++ b/doc/man/sphinx-build.rst
@@ -0,0 +1,343 @@
+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
+
+   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.
+
+.. 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
+
+   Do not emit colored output.
+
+.. 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..01ec76e
--- /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 `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)`