diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/configuration.rst | 6 | ||||
| -rw-r--r-- | doc/usage/extensions/autodoc.rst | 38 | ||||
| -rw-r--r-- | doc/usage/extensions/coverage.rst | 2 | ||||
| -rw-r--r-- | doc/usage/installation.rst | 2 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst | 4 |
5 files changed, 48 insertions, 4 deletions
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 6acad51f7..b4682dd21 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2246,6 +2246,12 @@ These options influence manual page output. .. versionadded:: 1.1 +.. confval:: man_make_section_directory + + If true, make a section directory on build man page. Default is False. + + .. versionadded:: 3.3 + .. _texinfo-options: diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index a5d464d54..86df8a79f 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -515,6 +515,44 @@ There are also config values that you can set: New option ``'description'`` is added. +.. confval:: autodoc_type_aliases + + A dictionary for users defined `type aliases`__ that maps a type name to the + full-qualified object name. It is used to keep type aliases not evaluated in + the document. Defaults to empty (``{}``). + + The type aliases are only available if your program enables `Postponed + Evaluation of Annotations (PEP 563)`__ feature via ``from __future__ import + annotations``. + + For example, there is code using a type alias:: + + from __future__ import annotations + + AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + def f() -> AliasType: + ... + + If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up + from this code as following:: + + .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + ... + + If you set ``autodoc_type_aliases`` as + ``{'AliasType': 'your.module.TypeAlias'}``, it generates a following document + internally:: + + .. py:function:: f() -> your.module.AliasType: + + ... + + .. __: https://www.python.org/dev/peps/pep-0563/ + .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases + .. versionadded:: 3.3 + .. confval:: autodoc_warningiserror This value controls the behavior of :option:`sphinx-build -W` during diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index db989f38d..5e6b04feb 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -51,7 +51,7 @@ should check: .. versionadded:: 1.1 -.. confval:: coverage_show_missing_items +.. confval:: coverage_show_missing_items Print objects that are missing to standard output also. ``False`` by default. diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 432825295..0ea54b220 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -171,7 +171,7 @@ Docker images for Sphinx are published on the `Docker Hub <https://hub.docker.co - `sphinxdoc/sphinx <https://hub.docker.com/repository/docker/sphinxdoc/sphinx>`_ - `sphinxdoc/sphinx-latexpdf <https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>`_ -Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX. +Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX. Please choose one for your purpose. .. note:: diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index e94106148..92bf78489 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -665,7 +665,7 @@ __ http://pygments.org/docs/lexers .. note:: If you want to select only ``[second-section]`` of ini file like the - following, you can use ``:start-at: [second-section]`` and + following, you can use ``:start-at: [second-section]`` and ``:end-before: [third-section]``: .. code-block:: ini @@ -692,7 +692,7 @@ __ http://pygments.org/docs/lexers # [initialize] app.start(":8000") # [initialize] - + When lines have been selected in any of the ways described above, the line numbers in ``emphasize-lines`` refer to those selected lines, counted |