diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/index.rst | 22 | ||||
| -rw-r--r-- | doc/man/sphinx-apidoc.rst | 171 | ||||
| -rw-r--r-- | doc/man/sphinx-autogen.rst | 97 | ||||
| -rw-r--r-- | doc/man/sphinx-build.rst | 343 | ||||
| -rw-r--r-- | doc/man/sphinx-quickstart.rst | 169 |
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)` |