diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 18434754650..c78f1a2a730 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -16,7 +16,6 @@ body: label: How to Reproduce description: Please provide steps to reproduce this bug. value: | - ``` $ git clone https://github.com/.../some_project $ cd some_project diff --git a/CHANGES b/CHANGES index 5658cc43f1f..ba6b8e85b6b 100644 --- a/CHANGES +++ b/CHANGES @@ -13,13 +13,30 @@ Deprecated Features added -------------- +* #9445: autodoc: Support class properties +* #9479: autodoc: Emit a warning if target is a mocked object +* #9447: html theme: Expose the version of Sphinx in the form of tuple as a + template variable ``sphinx_version_tuple`` +* #9445: py domain: ``:py:property:`` directive supports ``:classmethod:`` + option to describe the class property + Bugs fixed ---------- +* #9487: autodoc: typehint for cached_property is not shown +* #9509: autodoc: AttributeError is raised on failed resolving typehints +* #9518: autodoc: autodoc_docstring_signature does not effect to ``__init__()`` + and ``__new__()`` +* #9481: autosummary: some warnings contain non-existing filenames +* #9481: c domain: some warnings contain non-existing filenames +* #9481: cpp domain: some warnings contain non-existing filenames +* #9456: html search: abbreation marks are inserted to the search result if + failed to fetch the content of the page + Testing -------- -Release 4.1.2 (in development) +Release 4.1.3 (in development) ============================== Dependencies @@ -37,9 +54,31 @@ Features added Bugs fixed ---------- +* #9512: sphinx-build: crashed with the HEAD of Python 3.10 + Testing -------- +Release 4.1.2 (released Jul 27, 2021) +===================================== + +Incompatible changes +-------------------- + +* #9435: linkcheck: Disable checking automatically generated anchors on + github.com (ex. anchors in reST/Markdown documents) + +Bugs fixed +---------- + +* #9489: autodoc: Custom types using ``typing.NewType`` are not displayed well + with the HEAD of 3.10 +* #9490: autodoc: Some objects under ``typing`` module are not displayed well + with the HEAD of 3.10 +* #9436, #9471: autodoc: crashed if ``autodoc_class_signature = "separated"`` +* #9456: html search: html_copy_source can't control the search summaries +* #9435: linkcheck: Failed to check anchors in github.com + Release 4.1.1 (released Jul 15, 2021) ===================================== diff --git a/doc/latex.rst b/doc/latex.rst index f6d2987e206..f0b5a4aa8ac 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1151,6 +1151,20 @@ Miscellany Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. +- Docutils :dudir:`container` directives are supported in LaTeX output: to + let a container class with name ``foo`` influence the final PDF via LaTeX, + it is only needed to define in the preamble an environment + ``sphinxclassfoo``. A simple example would be: + + .. code-block:: latex + + \newenvironment{sphinxclassred}{\color{red}}{} + + Currently the class names must contain only ascii characters and avoid + characters special to LaTeX such as ``\``. + + .. versionadded:: 4.1.0 + .. hint:: As an experimental feature, Sphinx can use user-defined template file for diff --git a/doc/templating.rst b/doc/templating.rst index b253723198f..3d80edd6009 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -372,7 +372,16 @@ in the future. .. data:: sphinx_version - The version of Sphinx used to build. + The version of Sphinx used to build represented as a string for example "3.5.1". + +.. data:: sphinx_version_tuple + + The version of Sphinx used to build represented as a tuple of five elements. + For Sphinx version 3.5.1 beta 3 this would be `(3, 5, 1, 'beta', 3)``. + The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``. + ``final`` always has 0 as the last element. + + .. versionadded:: 4.2 .. data:: style diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 6ff26869516..51409a6b069 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -233,7 +233,7 @@ Sweet! .. note:: Generating a PDF using Sphinx can be done running ``make latexpdf``, - provided that the system has a working :math:`\LaTeX` installation, + provided that the system has a working LaTeX installation, as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`. Although this is perfectly feasible, such installations are often big, and in general LaTeX requires careful configuration in some cases, diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index c5347f36a7b..51a77bbbb3e 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -353,6 +353,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, autodata automethod autoattribute + autoproperty These work exactly like :rst:dir:`autoclass` etc., but do not offer the options used for automatic member documentation. @@ -422,6 +423,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, option. .. versionchanged:: 2.0 :rst:dir:`autodecorator` added. + .. versionchanged:: 2.1 + :rst:dir:`autoproperty` added. .. versionchanged:: 3.4 :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` option. diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 23844886e11..abece421318 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/doc/usage/restructuredtext/domains.rst @@ -329,6 +329,13 @@ The following directives are provided for module and class contents: Indicate the property is abstract. + .. rst:directive:option:: classmethod + :type: no value + + Indicate the property is a classmethod. + + .. versionaddedd: 4.2 + .. rst:directive:option:: type: type of the property :type: text diff --git a/sphinx/application.py b/sphinx/application.py index 5342730fd14..b55eb76c1a9 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -197,7 +197,7 @@ def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: # notice for parallel build on macOS and py38+ if sys.version_info > (3, 8) and platform.system() == 'Darwin' and parallel > 1: - logger.info(bold(__("For security reason, parallel mode is disabled on macOS and " + logger.info(bold(__("For security reasons, parallel mode is disabled on macOS and " "python3.8 and above. For more details, please read " "https://github.com/sphinx-doc/sphinx/issues/6803"))) @@ -415,7 +415,7 @@ def connect(self, event: str, callback: Callable, priority: int = 500) -> int: :param event: The name of target event :param callback: Callback function for the event :param priority: The priority of the callback. The callbacks will be invoked - in the order of *priority* in asending. + in order of *priority* (ascending). :return: A listener ID. It can be used for :meth:`disconnect`. .. versionchanged:: 3.0 @@ -493,7 +493,7 @@ def add_config_value(self, name: str, default: Any, rebuild: Union[bool, str], values accordingly. - :param name: The name of configuration value. It is recommended to be prefixed + :param name: The name of the configuration value. It is recommended to be prefixed with the extension name (ex. ``html_logo``, ``epub_title``) :param default: The default value of the configuration. :param rebuild: The condition of rebuild. It must be one of those values: @@ -539,10 +539,10 @@ def set_translator(self, name: str, translator_class: Type[nodes.NodeVisitor], """Register or override a Docutils translator class. This is used to register a custom output translator or to replace a - builtin translator. This allows extensions to use custom translator + builtin translator. This allows extensions to use a custom translator and define custom nodes for the translator (see :meth:`add_node`). - :param name: The name of builder for the translator + :param name: The name of the builder for the translator :param translator_class: A translator class :param override: If true, install the translator forcedly even if another translator is already installed as the same name @@ -606,11 +606,11 @@ def add_enumerable_node(self, node: Type[Element], figtype: str, using :rst:role:`numref`. :param node: A node class - :param figtype: The type of enumerable nodes. Each figtypes have individual numbering - sequences. As a system figtypes, ``figure``, ``table`` and - ``code-block`` are defined. It is able to add custom nodes to these - default figtypes. It is also able to define new custom figtype if new - figtype is given. + :param figtype: The type of enumerable nodes. Each figtype has individual numbering + sequences. As system figtypes, ``figure``, ``table`` and + ``code-block`` are defined. It is possible to add custom nodes to + these default figtypes. It is also possible to define new custom + figtype if a new figtype is given. :param title_getter: A getter function to obtain the title of node. It takes an instance of the enumerable node, and it must return its title as string. The title is used to the default title of references for @@ -629,7 +629,7 @@ def add_enumerable_node(self, node: Type[Element], figtype: str, def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None: """Register a Docutils directive. - :param name: The name of directive + :param name: The name of the directive :param cls: A directive class :param override: If true, install the directive forcedly even if another directive is already installed as the same name @@ -755,9 +755,9 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X Like :meth:`add_role`, but the role is added to the domain named *domain*. - :param domain: The name of target domain - :param name: A name of role - :param role: A role function + :param domain: The name of the target domain + :param name: The name of the role + :param role: The role function :param override: If true, install the role forcedly even if another role is already installed as the same name @@ -773,8 +773,8 @@ def add_index_to_domain(self, domain: str, index: Type[Index], override: bool = Add a custom *index* class to the domain named *domain*. - :param domain: The name of target domain - :param index: A index class + :param domain: The name of the target domain + :param index: The index class :param override: If true, install the index forcedly even if another index is already installed as the same name @@ -942,8 +942,8 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None Add *filename* to the list of JavaScript files that the default HTML template will include in order of *priority* (ascending). The filename must be relative to the HTML static path , or a full URI with scheme. - If the priority of JavaScript file is the same as others, the JavaScript - files will be included in order of the registration. If the keyword + If the priority of the JavaScript file is the same as others, the JavaScript + files will be included in order of registration. If the keyword argument ``body`` is given, its value will be added between the ``