summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--CHANGES5
-rw-r--r--doc/extdev/deprecated.rst6
-rw-r--r--doc/usage/extensions/intersphinx.rst17
-rw-r--r--sphinx/domains/c.py5
-rw-r--r--sphinx/domains/cpp.py4
-rw-r--r--sphinx/ext/autodoc/__init__.py36
-rw-r--r--sphinx/setup_command.py16
-rw-r--r--tests/test_ext_autodoc.py5
8 files changed, 52 insertions, 42 deletions
diff --git a/CHANGES b/CHANGES
index dd32ab91e..c6a38a701 100644
--- a/CHANGES
+++ b/CHANGES
@@ -14,6 +14,8 @@ Deprecated
----------
* The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
+* The ``no_docstring`` argument of
+ ``sphinx.ext.autodoc.Documenter.add_content()``
* ``sphinx.ext.autodoc.Documenter.get_object_members()``
* ``sphinx.ext.autodoc.DataDeclarationDocumenter``
* ``sphinx.ext.autodoc.GenericAliasDocumenter``
@@ -68,6 +70,7 @@ Bugs fixed
* #8460: autodoc: autodata and autoattribute directives do not display type
information of TypeVars
* #8493: autodoc: references to builtins not working in class aliases
+* #8522: autodoc: ``__bool__`` method could be called
* #8477: autosummary: non utf-8 reST files are generated when template contains
multibyte characters
* #8501: autosummary: summary extraction splits text after "el at." unexpectedly
@@ -100,6 +103,8 @@ Features added
Bugs fixed
----------
+* #8520: C, fix copying of AliasNode.
+
Testing
--------
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 068bf899b..cbdf31350 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -31,6 +31,12 @@ The following is a list of deprecated interfaces.
- 5.0
- N/A
+ * - The ``no_docstring`` argument of
+ ``sphinx.ext.autodoc.Documenter.add_content()``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.Documenter.get_doc()``
+
* - ``sphinx.ext.autodoc.Documenter.get_object_members()``
- 3.4
- 6.0
diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
index 619ec8c20..178655cae 100644
--- a/doc/usage/extensions/intersphinx.rst
+++ b/doc/usage/extensions/intersphinx.rst
@@ -75,8 +75,9 @@ linking:
A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
Each ``target`` is the base URI of a foreign Sphinx documentation set and can
be a local path or an HTTP URI. The ``inventory`` indicates where the
- inventory file can be found: it can be ``None`` (at the same location as
- the base URI) or another local or HTTP URI.
+ inventory file can be found: it can be ``None`` (an :file:`objects.inv` file
+ at the same location as the base URI) or another local file path or a full
+ HTTP URI to an inventory file.
The unique identifier can be used to prefix cross-reference targets, so that
it is clear which intersphinx set the target belongs to. A link like
@@ -106,7 +107,7 @@ linking:
``https://docs.python.org/3``. It is up to you to update the inventory file
as new objects are added to the Python documentation.
- **Multiple target for the inventory**
+ **Multiple targets for the inventory**
.. versionadded:: 1.3
@@ -120,6 +121,16 @@ linking:
intersphinx_mapping = {'python': ('https://docs.python.org/3',
(None, 'python-inv.txt'))}
+ For a set of books edited and tested locally and then published
+ together, it could be helpful to try a local inventory file first,
+ to check references before publication::
+
+ intersphinx_mapping = {
+ 'otherbook':
+ ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
+ ('../../otherbook/build/html/objects.inv', None)),
+ }
+
.. confval:: intersphinx_cache_limit
The maximum number of days to cache remote inventories. The default is
diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
index d18094217..38b81e3fa 100644
--- a/sphinx/domains/c.py
+++ b/sphinx/domains/c.py
@@ -3451,8 +3451,9 @@ class AliasNode(nodes.Element):
assert parentKey is not None
self.parentKey = parentKey
- def copy(self: T) -> T:
- return self.__class__(self.sig, env=None, parentKey=self.parentKey) # type: ignore
+ def copy(self) -> 'AliasNode':
+ return self.__class__(self.sig, self.maxdepth, self.document,
+ env=None, parentKey=self.parentKey)
class AliasTransform(SphinxTransform):
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index a69510179..cb0ee89e8 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -7050,8 +7050,8 @@ class AliasNode(nodes.Element):
assert parentKey is not None
self.parentKey = parentKey
- def copy(self: T) -> T:
- return self.__class__(self.sig, env=None, parentKey=self.parentKey) # type: ignore
+ def copy(self) -> 'AliasNode':
+ return self.__class__(self.sig, env=None, parentKey=self.parentKey)
class AliasTransform(SphinxTransform):
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index ea2818800..6f8ec21cb 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -584,6 +584,11 @@ class Documenter:
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
"""Add content from docstrings, attribute documentation and user."""
+ if no_docstring:
+ warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated."
+ % self.__class__.__name__,
+ RemovedInSphinx50Warning, stacklevel=2)
+
# set sourcename and add content from attribute documentation
sourcename = self.get_sourcename()
if self.analyzer:
@@ -716,7 +721,7 @@ class Documenter:
isprivate = membername.startswith('_')
keep = False
- if safe_getattr(member, '__sphinx_mock__', False):
+ if safe_getattr(member, '__sphinx_mock__', None) is not None:
# mocked module or object
pass
elif self.options.exclude_members and membername in self.options.exclude_members:
@@ -1595,6 +1600,10 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__,
RemovedInSphinx40Warning, stacklevel=2)
+ if self.doc_as_attr:
+ # Don't show the docstring of the class when it is an alias.
+ return []
+
lines = getattr(self, '_new_docstrings', None)
if lines is not None:
return lines
@@ -1641,10 +1650,9 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
if self.doc_as_attr:
- content = StringList([_('alias of %s') % restify(self.object)], source='')
- super().add_content(content, no_docstring=True)
- else:
- super().add_content(more_content)
+ more_content = StringList([_('alias of %s') % restify(self.object)], source='')
+
+ super().add_content(more_content)
def document_members(self, all_members: bool = False) -> None:
if self.doc_as_attr:
@@ -1811,13 +1819,11 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
return (self.object == UNINITIALIZED_ATTR or
super().should_suppress_value_header())
- def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
- ) -> None:
+ def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
if self.object is UNINITIALIZED_ATTR:
- # suppress docstring of the value
- super().add_content(more_content, no_docstring=True) # type: ignore
+ return []
else:
- super().add_content(more_content, no_docstring=no_docstring) # type: ignore
+ return super().get_doc(encoding, ignore) # type: ignore
class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
@@ -2220,6 +2226,11 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
pass
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
+ if not self._datadescriptor:
+ # if it's not a data descriptor, its docstring is very probably the
+ # wrong thing to display
+ return []
+
try:
# Disable `autodoc_inherit_docstring` temporarily to avoid to obtain
# a docstring from the value which descriptor returns unexpectedly.
@@ -2232,11 +2243,6 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None:
- if not self._datadescriptor:
- # if it's not a data descriptor, its docstring is very probably the
- # wrong thing to display
- no_docstring = True
-
if more_content is None:
more_content = StringList()
self.update_content(more_content)
diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py
index 3422f3d4c..0c32db5dd 100644
--- a/sphinx/setup_command.py
+++ b/sphinx/setup_command.py
@@ -14,7 +14,7 @@
import os
import sys
from distutils.cmd import Command
-from distutils.errors import DistutilsExecError, DistutilsOptionError
+from distutils.errors import DistutilsExecError
from io import StringIO
from sphinx.application import Sphinx
@@ -121,20 +121,6 @@ class BuildDoc(Command):
return root
return os.curdir
- # Overriding distutils' Command._ensure_stringlike which doesn't support
- # unicode, causing finalize_options to fail if invoked again. Workaround
- # for https://bugs.python.org/issue19570
- def _ensure_stringlike(self, option, what, default=None):
- # type: (str, str, Any) -> Any
- val = getattr(self, option)
- if val is None:
- setattr(self, option, default)
- return default
- elif not isinstance(val, str):
- raise DistutilsOptionError("'%s' must be a %s (got `%s`)"
- % (option, what, val))
- return val
-
def finalize_options(self):
# type: () -> None
self.ensure_string_list('builder')
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index 02ffae549..1577f32e6 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -367,11 +367,6 @@ def test_get_doc(app):
"""Döcstring"""
assert getdocl('function', f) == ['Döcstring']
- # already-unicode docstrings must be taken literally
- def f():
- """Döcstring"""
- assert getdocl('function', f) == ['Döcstring']
-
# verify that method docstrings get extracted in both normal case
# and in case of bound method posing as a function
class J: # NOQA
View Lorry Controller Status