IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '3.x' into master_with_merged_3.x

Browse Source
This commit is contained in:
jfbu 2021-02-02 18:01:55 +01:00
commit fbafb308b8
23 changed files with 363 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
CHANGES
View File

@ -119,6 +119,7 @@ Features added
info-field-list
* #8514: autodoc: Default values of overloaded functions are taken from actual
implementation if they're ellipsis
* #8775: autodoc: Support type union operator (PEP-604) in Python 3.10 or above
* #8619: html: kbd role generates customizable HTML tags for compound keys
* #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
@ -135,6 +136,7 @@ Features added
* #8004: napoleon: Type definitions in Google style docstrings are rendered as
references when :confval:`napoleon_preprocess_types` enabled
* #6241: mathjax: Include mathjax.js only on the document using equations
* #8775: py domain: Support type union operator (PEP-604)
* #8651: std domain: cross-reference for a rubric having inline item is broken
* #7642: std domain: Optimize case-insensitive match of term
* #8681: viewcode: Support incremental build
@ -158,6 +160,8 @@ Bugs fixed
contains invalid type comments
* #8693: autodoc: Default values for overloaded functions are rendered as string
* #8134: autodoc: crashes when mocked decorator takes arguments
* #8800: autodoc: Uninitialized attributes in superclass are recognized as
undocumented
* #8306: autosummary: mocked modules are documented as empty page when using
:recursive: option
* #8232: graphviz: Image node is not rendered if graph file is in subdirectory
@ -168,13 +172,16 @@ Bugs fixed
* #8123: html search: fix searching for terms containing + (Requires a custom
search language that does not split on +)
* #8665: html theme: Could not override globaltoc_maxdepth in theme.conf
* #8446: html: consecutive spaces are displayed as single space
* #8745: i18n: crashes with KeyError when translation message adds a new auto
footnote reference
* #4304: linkcheck: Fix race condition that could lead to checking the
availability of the same URL twice
* #8791: linkcheck: The docname for each hyperlink is not displayed
* #7118: sphinx-quickstart: questionare got Mojibake if libreadline unavailable
* #8094: texinfo: image files on the different directory with document are not
copied
* #8782: todo: Cross references in todolist get broken
* #8720: viewcode: module pages are generated for epub on incremental build
* #8704: viewcode: anchors are generated in incremental build after singlehtml
* #8756: viewcode: highlighted code is generated even if not referenced
@ -194,6 +201,8 @@ Bugs fixed
:confval:`numfig` is not True
* #8442: LaTeX: some indexed terms are ignored when using xelatex engine
(or pdflatex and :confval:`latex_use_xindy` set to True) with memoir class
* #8750: LaTeX: URLs as footnotes fail to show in PDF if originating from
inside function type signatures
* #8780: LaTeX: long words in narrow columns may not be hyphenated
* #8788: LaTeX: ``\titleformat`` last argument in sphinx.sty should be
bracketed, not braced (and is anyhow not needed)
@ -222,6 +231,8 @@ Bugs fixed
* #8655: autodoc: Failed to generate document if target module contains an
object that raises an exception on ``hasattr()``
* C, ``expr`` role should start symbol lookup in the current scope.
* #8796: LaTeX: potentially critical low level TeX coding mistake has gone
unnoticed so far
Testing
--------

7
doc/usage/configuration.rst
View File

@ -70,13 +70,14 @@ Project information
The author name(s) of the document. The default value is ``'unknown'``.
.. confval:: copyright
.. confval:: project_copyright
A copyright statement in the style ``'2008, Author Name'``.
.. versionchanged:: 3.5
.. confval:: project_copyright
As an alias, ``project_copyright`` is also allowed.
An alias of :confval:`copyright`.
.. versionadded:: 3.5
.. confval:: version

32
sphinx/builders/linkcheck.py
View File

@ -108,11 +108,11 @@ class CheckExternalLinksBuilder(DummyBuilder):
def init(self) -> None:
self.hyperlinks = {} # type: Dict[str, Hyperlink]
self.to_ignore = [re.compile(x) for x in self.app.config.linkcheck_ignore]
self.to_ignore = [re.compile(x) for x in self.config.linkcheck_ignore]
self.anchors_ignore = [re.compile(x)
for x in self.app.config.linkcheck_anchors_ignore]
for x in self.config.linkcheck_anchors_ignore]
self.auth = [(re.compile(pattern), auth_info) for pattern, auth_info
in self.app.config.linkcheck_auth]
in self.config.linkcheck_auth]
self._good = set() # type: Set[str]
self._broken = {} # type: Dict[str, str]
self._redirected = {} # type: Dict[str, Tuple[str, int]]
@ -124,13 +124,13 @@ class CheckExternalLinksBuilder(DummyBuilder):
self.wqueue = queue.PriorityQueue() # type: queue.PriorityQueue
self.rqueue = queue.Queue() # type: queue.Queue
self.workers = [] # type: List[threading.Thread]
for i in range(self.app.config.linkcheck_workers):
for i in range(self.config.linkcheck_workers):
thread = threading.Thread(target=self.check_thread, daemon=True)
thread.start()
self.workers.append(thread)
@property
def good(self):
def good(self) -> Set[str]:
warnings.warn(
"%s.%s is deprecated." % (self.__class__.__name__, "good"),
RemovedInSphinx50Warning,
@ -139,7 +139,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
return self._good
@property
def broken(self):
def broken(self) -> Dict[str, str]:
warnings.warn(
"%s.%s is deprecated." % (self.__class__.__name__, "broken"),
RemovedInSphinx50Warning,
@ -148,7 +148,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
return self._broken
@property
def redirected(self):
def redirected(self) -> Dict[str, Tuple[str, int]]:
warnings.warn(
"%s.%s is deprecated." % (self.__class__.__name__, "redirected"),
RemovedInSphinx50Warning,
@ -158,8 +158,8 @@ class CheckExternalLinksBuilder(DummyBuilder):
def check_thread(self) -> None:
kwargs = {}
if self.app.config.linkcheck_timeout:
kwargs['timeout'] = self.app.config.linkcheck_timeout
if self.config.linkcheck_timeout:
kwargs['timeout'] = self.config.linkcheck_timeout
def get_request_headers() -> Dict:
url = urlparse(uri)
@ -205,9 +205,9 @@ class CheckExternalLinksBuilder(DummyBuilder):
kwargs['headers'] = get_request_headers()
try:
if anchor and self.app.config.linkcheck_anchors:
if anchor and self.config.linkcheck_anchors:
# Read the whole document and see if #anchor exists
response = requests.get(req_url, stream=True, config=self.app.config,
response = requests.get(req_url, stream=True, config=self.config,
auth=auth_info, **kwargs)
response.raise_for_status()
found = check_anchor(response, unquote(anchor))
@ -219,7 +219,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
# try a HEAD request first, which should be easier on
# the server and the network
response = requests.head(req_url, allow_redirects=True,
config=self.app.config, auth=auth_info,
config=self.config, auth=auth_info,
**kwargs)
response.raise_for_status()
except (HTTPError, TooManyRedirects) as err:
@ -228,7 +228,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
# retry with GET request if that fails, some servers
# don't like HEAD requests.
response = requests.get(req_url, stream=True,
config=self.app.config,
config=self.config,
auth=auth_info, **kwargs)
response.raise_for_status()
except HTTPError as err:
@ -297,7 +297,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
return 'ignored', '', 0
# need to actually check the URI
for _ in range(self.app.config.linkcheck_retries):
for _ in range(self.config.linkcheck_retries):
status, info, code = check_uri()
if status != "broken":
break
@ -360,7 +360,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
next_check = time.time() + delay
netloc = urlparse(response.url).netloc
if next_check is None:
max_delay = self.app.config.linkcheck_rate_limit_timeout
max_delay = self.config.linkcheck_rate_limit_timeout
try:
rate_limit = self.rate_limits[netloc]
except KeyError:
@ -390,7 +390,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
self.write_linkstat(linkstat)
return
if lineno:
logger.info('(line %4d) ', lineno, nonl=True)
logger.info('(%16s: line %4d) ', docname, lineno, nonl=True)
if status == 'ignored':
if info:
logger.info(darkgray('-ignored- ') + uri + ': ' + info)

16
sphinx/domains/python.py
View File

@ -101,17 +101,19 @@ def _parse_annotation(annotation: str, env: BuildEnvironment = None) -> List[Nod
def unparse(node: ast.AST) -> List[Node]:
if isinstance(node, ast.Attribute):
return [nodes.Text("%s.%s" % (unparse(node.value)[0], node.attr))]
elif isinstance(node, ast.Constant): # type: ignore
if node.value is Ellipsis:
return [addnodes.desc_sig_punctuation('', "...")]
else:
return [nodes.Text(node.value)]
elif isinstance(node, ast.BinOp):
result = unparse(node.left) # type: List[Node]
result.extend(unparse(node.op))
result.extend(unparse(node.right))
return result
elif isinstance(node, ast.BitOr):
return [nodes.Text(' '), addnodes.desc_sig_punctuation('', '|'), nodes.Text(' ')]
elif isinstance(node, ast.Expr):
return unparse(node.value)
elif isinstance(node, ast.Index):
return unparse(node.value)
elif isinstance(node, ast.List):
result = [addnodes.desc_sig_punctuation('', '[')] # type: List[Node]
result = [addnodes.desc_sig_punctuation('', '[')]
for elem in node.elts:
result.extend(unparse(elem))
result.append(addnodes.desc_sig_punctuation('', ', '))
@ -157,7 +159,7 @@ def _parse_annotation(annotation: str, env: BuildEnvironment = None) -> List[Nod
tree = ast_parse(annotation)
result = unparse(tree)
for i, node in enumerate(result):
if isinstance(node, nodes.Text):
if isinstance(node, nodes.Text) and node.strip():
result[i] = type_to_xref(str(node), env)
return result
except SyntaxError:

58
sphinx/ext/autodoc/__init__.py
View File

@ -1012,10 +1012,6 @@ class ModuleDocumenter(Documenter):
try:
if not self.options.ignore_module_all:
self.__all__ = inspect.getall(self.object)
except AttributeError as exc:
# __all__ raises an error.
logger.warning(__('%s.__all__ raises an error. Ignored: %r'),
(self.fullname, exc), type='autodoc')
except ValueError as exc:
# invalid __all__ found.
logger.warning(__('__all__ should be a list of strings, not %r '
@ -1056,14 +1052,11 @@ class ModuleDocumenter(Documenter):
continue
# annotation only member (ex. attr: int)
try:
for name in inspect.getannotations(self.object):
if name not in members:
docstring = attr_docs.get(('', name), [])
members[name] = ObjectMember(name, INSTANCEATTR,
docstring="\n".join(docstring))
except AttributeError:
pass
for name in inspect.getannotations(self.object):
if name not in members:
docstring = attr_docs.get(('', name), [])
members[name] = ObjectMember(name, INSTANCEATTR,
docstring="\n".join(docstring))
return members
@ -1890,16 +1883,16 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
def update_annotations(self, parent: Any) -> None:
"""Update __annotations__ to support type_comment and so on."""
try:
annotations = dict(inspect.getannotations(parent))
parent.__annotations__ = annotations
annotations = dict(inspect.getannotations(parent))
parent.__annotations__ = annotations
try:
analyzer = ModuleAnalyzer.for_module(self.modname)
analyzer.analyze()
for (classname, attrname), annotation in analyzer.annotations.items():
if classname == '' and attrname not in annotations:
annotations[attrname] = annotation
except AttributeError:
except PycodeError:
pass
def import_object(self, raiseerror: bool = False) -> bool:
@ -2212,7 +2205,7 @@ class SlotsMixin(DataDocumenterMixinBase):
return True
else:
return False
except (AttributeError, ValueError, TypeError):
except (ValueError, TypeError):
return False
def import_object(self, raiseerror: bool = False) -> bool:
@ -2238,7 +2231,7 @@ class SlotsMixin(DataDocumenterMixinBase):
return [docstring]
else:
return []
except (AttributeError, ValueError) as exc:
except ValueError as exc:
logger.warning(__('Invalid __slots__ found on %s. Ignored.'),
(self.parent.__qualname__, exc), type='autodoc')
return []
@ -2429,8 +2422,6 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
annotations[attrname] = annotation
except (AttributeError, PycodeError):
pass
except AttributeError:
pass
except TypeError:
# Failed to set __annotations__ (built-in, extensions, etc.)
pass
@ -2484,22 +2475,19 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
pass
def get_attribute_comment(self, parent: Any, attrname: str) -> Optional[List[str]]:
try:
for cls in inspect.getmro(parent):
try:
module = safe_getattr(cls, '__module__')
qualname = safe_getattr(cls, '__qualname__')
for cls in inspect.getmro(parent):
try:
module = safe_getattr(cls, '__module__')
qualname = safe_getattr(cls, '__qualname__')
analyzer = ModuleAnalyzer.for_module(module)
analyzer.analyze()
if qualname and self.objpath:
key = (qualname, attrname)
if key in analyzer.attr_docs:
return list(analyzer.attr_docs[key])
except (AttributeError, PycodeError):
pass
except (AttributeError, PycodeError):
pass
analyzer = ModuleAnalyzer.for_module(module)
analyzer.analyze()
if qualname and self.objpath:
key = (qualname, attrname)
if key in analyzer.attr_docs:
return list(analyzer.attr_docs[key])
except (AttributeError, PycodeError):
pass
return None

56
sphinx/ext/autodoc/importer.py
View File

@ -156,12 +156,9 @@ def get_module_members(module: Any) -> List[Tuple[str, Any]]:
continue
# annotation only member (ex. attr: int)
try:
for name in getannotations(module):
if name not in members:
members[name] = (name, INSTANCEATTR)
except AttributeError:
pass
for name in getannotations(module):
if name not in members:
members[name] = (name, INSTANCEATTR)
return sorted(list(members.values()))
@ -202,7 +199,7 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
for name in __slots__:
members[name] = Attribute(name, True, SLOTSATTR)
except (AttributeError, TypeError, ValueError):
except (TypeError, ValueError):
pass
# other members
@ -218,13 +215,10 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
# annotation only member (ex. attr: int)
for i, cls in enumerate(getmro(subject)):
try:
for name in getannotations(cls):
name = unmangle(cls, name)
if name and name not in members:
members[name] = Attribute(name, i == 0, INSTANCEATTR)
except AttributeError:
pass
for name in getannotations(cls):
name = unmangle(cls, name)
if name and name not in members:
members[name] = Attribute(name, i == 0, INSTANCEATTR)
if analyzer:
# append instance attributes (cf. self.attr1) if analyzer knows
@ -267,7 +261,7 @@ def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
for name, docstring in __slots__.items():
members[name] = ObjectMember(name, SLOTSATTR, class_=subject,
docstring=docstring)
except (AttributeError, TypeError, ValueError):
except (TypeError, ValueError):
pass
# other members
@ -288,27 +282,35 @@ def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
try:
for cls in getmro(subject):
# annotation only member (ex. attr: int)
try:
for name in getannotations(cls):
name = unmangle(cls, name)
if name and name not in members:
members[name] = ObjectMember(name, INSTANCEATTR, class_=cls)
except AttributeError:
pass
# append instance attributes (cf. self.attr1) if analyzer knows
try:
modname = safe_getattr(cls, '__module__')
qualname = safe_getattr(cls, '__qualname__')
analyzer = ModuleAnalyzer.for_module(modname)
analyzer.analyze()
except AttributeError:
qualname = None
analyzer = None
except PycodeError:
analyzer = None
# annotation only member (ex. attr: int)
for name in getannotations(cls):
name = unmangle(cls, name)
if name and name not in members:
if analyzer and (qualname, name) in analyzer.attr_docs:
docstring = '\n'.join(analyzer.attr_docs[qualname, name])
else:
docstring = None
members[name] = ObjectMember(name, INSTANCEATTR, class_=cls,
docstring=docstring)
# append instance attributes (cf. self.attr1) if analyzer knows
if analyzer:
for (ns, name), docstring in analyzer.attr_docs.items():
if ns == qualname and name not in members:
members[name] = ObjectMember(name, INSTANCEATTR, class_=cls,
docstring='\n'.join(docstring))
except (AttributeError, PycodeError):
pass
except AttributeError:
pass

21
sphinx/ext/todo.py
View File

@ -19,6 +19,7 @@ from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
import sphinx
from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.domains import Domain
from sphinx.environment import BuildEnvironment
@ -123,12 +124,12 @@ class TodoListProcessor:
self.config = app.config
self.env = app.env
self.domain = cast(TodoDomain, app.env.get_domain('todo'))
self.document = new_document('')
self.process(doctree, docname)
def process(self, doctree: nodes.document, docname: str) -> None:
todos = sum(self.domain.todos.values(), []) # type: List[todo_node]
document = new_document('')
for node in doctree.traverse(todolist):
if not self.config.todo_include_todos:
node.parent.remove(node)
@ -144,12 +145,7 @@ class TodoListProcessor:
new_todo = todo.deepcopy()
new_todo['ids'].clear()
# (Recursively) resolve references in the todo content
#
# Note: To resolve references, it is needed to wrap it with document node
document += new_todo
self.env.resolve_references(document, todo['docname'], self.builder)
document.remove(new_todo)
self.resolve_reference(new_todo, docname)
content.append(new_todo)
todo_ref = self.create_todo_reference(todo, docname)
@ -185,6 +181,17 @@ class TodoListProcessor:
return para
def resolve_reference(self, todo: todo_node, docname: str) -> None:
"""Resolve references in the todo content."""
for node in todo.traverse(addnodes.pending_xref):
if 'refdoc' in node:
node['refdoc'] = docname
# Note: To resolve references, it is needed to wrap it with document node
self.document += todo
self.env.resolve_references(self.document, docname, self.builder)
self.document.remove(todo)
def visit_todo_node(self: HTMLTranslator, node: todo_node) -> None:
if self.config.todo_include_todos:

30
sphinx/texinputs/sphinxpackagefootnote.sty
View File

@ -1,6 +1,6 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{sphinxpackagefootnote}%
[2021/01/26 v1.1b footnotehyper adapted to sphinx (Sphinx team)]
[2021/01/29 v1.1c footnotehyper adapted to sphinx (Sphinx team)]
% Provides support for this output mark-up from Sphinx latex writer:
% - footnote environment
% - savenotes environment (table templates)
@ -8,7 +8,7 @@
%
%%
%% Package: sphinxpackagefootnote
%% Version: based on footnotehyper.sty 2021/01/26 v1.1b
%% Version: based on footnotehyper.sty 2021/01/29 v1.1c
%% as available at https://www.ctan.org/pkg/footnotehyper
%% License: the one applying to Sphinx
%%
@ -25,6 +25,7 @@
\DeclareOption*{\PackageWarning{sphinxpackagefootnote}{Option `\CurrentOption' is unknown}}%
\ProcessOptions\relax
\newbox\FNH@notes
\newtoks\FNH@toks % 1.1c
\newdimen\FNH@width
\let\FNH@colwidth\columnwidth
\newif\ifFNH@savingnotes
@ -32,6 +33,7 @@
\let\FNH@latex@footnote \footnote
\let\FNH@latex@footnotetext\footnotetext
\let\FNH@H@@footnotetext \@footnotetext
\let\FNH@H@@mpfootnotetext \@mpfootnotetext
\newenvironment{savenotes}
{\FNH@savenotes\ignorespaces}{\FNH@spewnotes\ignorespacesafterend}%
\let\spewnotes \FNH@spewnotes
@ -42,6 +44,7 @@
\@ifpackageloaded{hyperref}
{\ifHy@hyperfootnotes
\let\FNH@H@@footnotetext\H@@footnotetext
\let\FNH@H@@mpfootnotetext\H@@mpfootnotetext
\else
\let\FNH@hyper@fntext\FNH@nohyp@fntext
\fi}%
@ -116,14 +119,33 @@
\fi
}%
\def\FNH@spewnotes {%
\endgroup
\if@endpe\ifx\par\@@par\FNH@toks{}\else
\FNH@toks\expandafter{\expandafter
\def\expandafter\par\expandafter{\par}\@endpetrue}%
\expandafter\expandafter\expandafter
\FNH@toks
\expandafter\expandafter\expandafter
{\expandafter\the\expandafter\FNH@toks
\expandafter\def\expandafter\@par\expandafter{\@par}}%
\expandafter\expandafter\expandafter
\FNH@toks
\expandafter\expandafter\expandafter
{\expandafter\the\expandafter\FNH@toks
\expandafter\everypar\expandafter{\the\everypar}}\fi
\else\FNH@toks{}\fi
\expandafter
\endgroup\the\FNH@toks
\ifFNH@savingnotes\else
\ifvoid\FNH@notes\else
\begingroup
\let\@makefntext\@empty
\let\@finalstrut\@gobble
\let\rule\@gobbletwo
\FNH@H@@footnotetext{\unvbox\FNH@notes}%
\ifx\@footnotetext\@mpfootnotetext
\expandafter\FNH@H@@mpfootnotetext
\else
\expandafter\FNH@H@@footnotetext
\fi{\unvbox\FNH@notes}%
\endgroup
\fi
\fi

19
sphinx/util/inspect.py
View File

@ -145,7 +145,6 @@ def getall(obj: Any) -> Optional[Sequence[str]]:
"""Get __all__ attribute of the module as dict.
Return None if given *obj* does not have __all__.
Raises AttributeError if given *obj* raises an error on accessing __all__.
Raises ValueError if given *obj* have invalid __all__.
"""
__all__ = safe_getattr(obj, '__all__', None)
@ -159,10 +158,7 @@ def getall(obj: Any) -> Optional[Sequence[str]]:
def getannotations(obj: Any) -> Mapping[str, Any]:
"""Get __annotations__ from given *obj* safely.
Raises AttributeError if given *obj* raises an error on accessing __attribute__.
"""
"""Get __annotations__ from given *obj* safely."""
__annotations__ = safe_getattr(obj, '__annotations__', None)
if isinstance(__annotations__, Mapping):
return __annotations__
@ -171,10 +167,7 @@ def getannotations(obj: Any) -> Mapping[str, Any]:
def getmro(obj: Any) -> Tuple["Type", ...]:
"""Get __mro__ from given *obj* safely.
Raises AttributeError if given *obj* raises an error on accessing __mro__.
"""
"""Get __mro__ from given *obj* safely."""
__mro__ = safe_getattr(obj, '__mro__', None)
if isinstance(__mro__, tuple):
return __mro__
@ -186,7 +179,6 @@ def getslots(obj: Any) -> Optional[Dict]:
"""Get __slots__ attribute of the class as dict.
Return None if gienv *obj* does not have __slots__.
Raises AttributeError if given *obj* raises an error on accessing __slots__.
Raises TypeError if given *obj* is not a class.
Raises ValueError if given *obj* have invalid __slots__.
"""
@ -464,12 +456,7 @@ def is_builtin_class_method(obj: Any, attr_name: str) -> bool:
but PyPy implements it by pure Python code.
"""
try:
mro = inspect.getmro(obj)
except AttributeError:
# no __mro__, assume the object has no methods as we know them
return False
try:
mro = getmro(obj)
cls = next(c for c in mro if attr_name in safe_getattr(c, '__dict__', {}))
except StopIteration:
return False

23
sphinx/util/typing.py
View File

@ -30,6 +30,11 @@ else:
ref = _ForwardRef(self.arg)
return ref._eval_type(globalns, localns)
if sys.version_info > (3, 10):
from types import Union as types_Union
else:
types_Union = None
if False:
# For type annotation
from typing import Type # NOQA # for python3.5.1
@ -72,7 +77,9 @@ def get_type_hints(obj: Any, globalns: Dict = None, localns: Dict = None) -> Dic
# Failed to evaluate ForwardRef (maybe TYPE_CHECKING)
return safe_getattr(obj, '__annotations__', {})
except TypeError:
return {}
# Invalid object is given. But try to get __annotations__ as a fallback for
# the code using type union operator (PEP 604) in python 3.9 or below.
return safe_getattr(obj, '__annotations__', {})
except KeyError:
# a broken class found (refs: https://github.com/sphinx-doc/sphinx/issues/8084)
return {}
@ -97,6 +104,12 @@ def restify(cls: Optional["Type"]) -> str:
return ':class:`struct.Struct`'
elif inspect.isNewType(cls):
return ':class:`%s`' % cls.__name__
elif types_Union and isinstance(cls, types_Union):
if len(cls.__args__) > 1 and None in cls.__args__:
args = ' | '.join(restify(a) for a in cls.__args__ if a)
return 'Optional[%s]' % args
else:
return ' | '.join(restify(a) for a in cls.__args__)
elif cls.__module__ in ('__builtin__', 'builtins'):
return ':class:`%s`' % cls.__name__
else:
@ -290,6 +303,8 @@ def _stringify_py37(annotation: Any) -> str:
elif hasattr(annotation, '__origin__'):
# instantiated generic provided by a user
qualname = stringify(annotation.__origin__)
elif types_Union and isinstance(annotation, types_Union): # types.Union (for py3.10+)
qualname = 'types.Union'
else:
# we weren't able to extract the base type, appending arguments would
# only make them appear twice
@ -309,6 +324,12 @@ def _stringify_py37(annotation: Any) -> str:
else:
args = ', '.join(stringify(a) for a in annotation.__args__)
return 'Union[%s]' % args
elif qualname == 'types.Union':
if len(annotation.__args__) > 1 and None in annotation.__args__:
args = ' | '.join(stringify(a) for a in annotation.__args__ if a)
return 'Optional[%s]' % args
else:
return ' | '.join(stringify(a) for a in annotation.__args__)
elif qualname == 'Callable':
args = ', '.join(stringify(a) for a in annotation.__args__[:-1])
returns = stringify(annotation.__args__[-1])

2
sphinx/writers/html.py
View File

@ -116,8 +116,10 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
def visit_desc_signature(self, node: Element) -> None:
# the id is set automatically
self.body.append(self.starttag(node, 'dt'))
self.protect_literal_text += 1
def depart_desc_signature(self, node: Element) -> None:
self.protect_literal_text -= 1
if not node.get('is_multiline'):
self.add_permalink_ref(node, _('Permalink to this definition'))
self.body.append('</dt>\n')

2
sphinx/writers/html5.py
View File

@ -87,8 +87,10 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
def visit_desc_signature(self, node: Element) -> None:
# the id is set automatically
self.body.append(self.starttag(node, 'dt'))
self.protect_literal_text += 1
def depart_desc_signature(self, node: Element) -> None:
self.protect_literal_text -= 1
if not node.get('is_multiline'):
self.add_permalink_ref(node, _('Permalink to this definition'))
self.body.append('</dt>\n')

10
sphinx/writers/latex.py
View File

@ -702,12 +702,18 @@ class LaTeXTranslator(SphinxTranslator):
self.body.append(self.context.pop())
def visit_desc(self, node: Element) -> None:
self.body.append('\n\n\\begin{fulllineitems}\n')
if self.config.latex_show_urls == 'footnote':
self.body.append('\n\n\\begin{savenotes}\\begin{fulllineitems}\n')
else:
self.body.append('\n\n\\begin{fulllineitems}\n')
if self.table:
self.table.has_problematic = True
def depart_desc(self, node: Element) -> None:
self.body.append('\n\\end{fulllineitems}\n\n')
if self.config.latex_show_urls == 'footnote':
self.body.append('\n\\end{fulllineitems}\\end{savenotes}\n\n')
else:
self.body.append('\n\\end{fulllineitems}\n\n')
def _visit_signature_line(self, node: Element) -> None:
for child in node:

16
tests/roots/test-ext-autodoc/target/pep604.py Normal file
View File

@ -0,0 +1,16 @@
from __future__ import annotations
attr: int | str #: docstring
def sum(x: int | str, y: int | str) -> int | str:
"""docstring"""
class Foo:
"""docstring"""
attr: int | str #: docstring
def meth(self, x: int | str, y: int | str) -> int | str:
"""docstring"""

8
tests/roots/test-ext-autodoc/target/uninitialized_attributes.py Normal file
View File

@ -0,0 +1,8 @@
class Base:
attr1: int #: docstring
attr2: str
class Derived(Base):
attr3: int #: docstring
attr4: str

6
tests/roots/test-footnotes/index.rst
View File

@ -169,3 +169,9 @@ Footnote in term [#]_
def bar(x,y):
return x+y
The section with an object description
======================================
.. py:function:: dummy(N)
:noindex:

10
tests/test_build_html.py
View File

@ -178,8 +178,8 @@ def test_html4_output(app, status, warning):
],
'autodoc.html': [
(".//dl[@class='py class']/dt[@id='autodoc_target.Class']", ''),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span", r'\*\*'),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span", r'kwds'),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span/span", r'\*\*'),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span/span", r'kwds'),
(".//dd/p", r'Return spam\.'),
],
'extapi.html': [
@ -279,8 +279,10 @@ def test_html4_output(app, status, warning):
'objects.html': [
(".//dt[@id='mod.Cls.meth1']", ''),
(".//dt[@id='errmod.Error']", ''),
(".//dt/code", r'long\(parameter,\s* list\)'),
(".//dt/code", 'another one'),
(".//dt/code/span", r'long\(parameter,'),
(".//dt/code/span", r'list\)'),
(".//dt/code/span", 'another'),
(".//dt/code/span", 'one'),
(".//a[@href='#mod.Cls'][@class='reference internal']", ''),
(".//dl[@class='std userdesc']", ''),
(".//dt[@id='userdesc-myobj']", ''),

3
tests/test_build_latex.py
View File

@ -828,6 +828,7 @@ def test_latex_show_urls_is_inline(app, status, warning):
assert '\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result
assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}'
'{sphinx\\sphinxhyphen{}dev@googlegroups.com}') in result
assert '\\begin{savenotes}\\begin{fulllineitems}' not in result
@pytest.mark.sphinx(
@ -882,6 +883,7 @@ def test_latex_show_urls_is_footnote(app, status, warning):
assert ('\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result)
assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}'
'{sphinx\\sphinxhyphen{}dev@googlegroups.com}\n') in result
assert '\\begin{savenotes}\\begin{fulllineitems}' in result
@pytest.mark.sphinx(
@ -925,6 +927,7 @@ def test_latex_show_urls_is_no(app, status, warning):
assert ('\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result)
assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}'
'{sphinx\\sphinxhyphen{}dev@googlegroups.com}\n') in result
assert '\\begin{savenotes}\\begin{fulllineitems}' not in result
@pytest.mark.sphinx(

28
tests/test_domain_py.py
View File

@ -431,6 +431,20 @@ def test_pyfunction_with_number_literals(app):
[nodes.inline, "1_6_0"])])])
def test_pyfunction_with_union_type_operator(app):
text = ".. py:function:: hello(age: int | None)"
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, ([desc_sig_name, "age"],
[desc_sig_punctuation, ":"],
" ",
[desc_sig_name, ([pending_xref, "int"],
" ",
[desc_sig_punctuation, "|"],
" ",
[pending_xref, "None"])])])])
def test_optional_pyfunction_signature(app):
text = ".. py:function:: compile(source [, filename [, symbol]]) -> ast object"
doctree = restructuredtext.parse(app, text)
@ -498,6 +512,20 @@ def test_pydata_signature_old(app):
domain="py", objtype="data", noindex=False)
def test_pydata_with_union_type_operator(app):
text = (".. py:data:: version\n"
" :type: int | str")
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0],
([desc_name, "version"],
[desc_annotation, (": ",
[pending_xref, "int"],
" ",
[desc_sig_punctuation, "|"],
" ",
[pending_xref, "str"])]))
def test_pyobject_prefix(app):
text = (".. py:class:: Foo\n"
"\n"

44
tests/test_ext_autodoc.py
View File

@ -2226,6 +2226,50 @@ def test_name_mangling(app):
]
@pytest.mark.skipif(sys.version_info < (3, 7), reason='python 3.7+ is required.')
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_type_union_operator(app):
options = {'members': None}
actual = do_autodoc(app, 'module', 'target.pep604', options)
assert list(actual) == [
'',
'.. py:module:: target.pep604',
'',
'',
'.. py:class:: Foo()',
' :module: target.pep604',
'',
' docstring',
'',
'',
' .. py:attribute:: Foo.attr',
' :module: target.pep604',
' :type: int | str',
'',
' docstring',
'',
'',
' .. py:method:: Foo.meth(x: int | str, y: int | str) -> int | str',
' :module: target.pep604',
'',
' docstring',
'',
'',
'.. py:data:: attr',
' :module: target.pep604',
' :type: int | str',
'',
' docstring',
'',
'',
'.. py:function:: sum(x: int | str, y: int | str) -> int | str',
' :module: target.pep604',
'',
' docstring',
'',
]
@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_hide_value(app):

67
tests/test_ext_autodoc_autoclass.py
View File

@ -106,6 +106,73 @@ def test_inherited_instance_variable(app):
]
@pytest.mark.skipif(sys.version_info < (3, 6), reason='py36+ is available since python3.6.')
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_uninitialized_attributes(app):
options = {"members": None,
"inherited-members": True}
actual = do_autodoc(app, 'class', 'target.uninitialized_attributes.Derived', options)
assert list(actual) == [
'',
'.. py:class:: Derived()',
' :module: target.uninitialized_attributes',
'',
'',
' .. py:attribute:: Derived.attr1',
' :module: target.uninitialized_attributes',
' :type: int',
'',
' docstring',
'',
'',
' .. py:attribute:: Derived.attr3',
' :module: target.uninitialized_attributes',
' :type: int',
'',
' docstring',
'',
]
@pytest.mark.skipif(sys.version_info < (3, 6), reason='py36+ is available since python3.6.')
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_undocumented_uninitialized_attributes(app):
options = {"members": None,
"inherited-members": True,
"undoc-members": True}
actual = do_autodoc(app, 'class', 'target.uninitialized_attributes.Derived', options)
assert list(actual) == [
'',
'.. py:class:: Derived()',
' :module: target.uninitialized_attributes',
'',
'',
' .. py:attribute:: Derived.attr1',
' :module: target.uninitialized_attributes',
' :type: int',
'',
' docstring',
'',
'',
' .. py:attribute:: Derived.attr2',
' :module: target.uninitialized_attributes',
' :type: str',
'',
'',
' .. py:attribute:: Derived.attr3',
' :module: target.uninitialized_attributes',
' :type: int',
'',
' docstring',
'',
'',
' .. py:attribute:: Derived.attr4',
' :module: target.uninitialized_attributes',
' :type: str',
'',
]
def test_decorators(app):
actual = do_autodoc(app, 'class', 'target.decorator.Baz')
assert list(actual) == [

4
tests/test_ext_intersphinx.py
View File

@ -250,10 +250,10 @@ def test_missing_reference_cppdomain(tempdir, app, status, warning):
'<span class="pre">Bar</span></code></a>' in html)
assert ('<a class="reference external"'
' href="https://docs.python.org/index.html#foons"'
' title="(in foo v2.0)">foons</a>' in html)
' title="(in foo v2.0)"><span class="pre">foons</span></a>' in html)
assert ('<a class="reference external"'
' href="https://docs.python.org/index.html#foons_bartype"'
' title="(in foo v2.0)">bartype</a>' in html)
' title="(in foo v2.0)"><span class="pre">bartype</span></a>' in html)
def test_missing_reference_jsdomain(tempdir, app, status, warning):

14
tests/test_util_typing.py
View File

@ -117,6 +117,13 @@ def test_restify_type_ForwardRef():
assert restify(ForwardRef("myint")) == ":class:`myint`"
@pytest.mark.skipif(sys.version_info < (3, 10), reason='python 3.10+ is required.')
def test_restify_type_union_operator():
assert restify(int | None) == "Optional[:class:`int`]" # type: ignore
assert restify(int | str) == ":class:`int` | :class:`str`" # type: ignore
assert restify(int | str | None) == "Optional[:class:`int` | :class:`str`]" # type: ignore
def test_restify_broken_type_hints():
assert restify(BrokenType) == ':class:`tests.test_util_typing.BrokenType`'
@ -206,5 +213,12 @@ def test_stringify_type_hints_alias():
assert stringify(MyTuple) == "Tuple[str, str]" # type: ignore
@pytest.mark.skipif(sys.version_info < (3, 10), reason='python 3.10+ is required.')
def test_stringify_type_union_operator():
assert stringify(int | None) == "Optional[int]" # type: ignore
assert stringify(int | str) == "int | str" # type: ignore
assert stringify(int | str | None) == "Optional[int | str]" # type: ignore
def test_stringify_broken_type_hints():
assert stringify(BrokenType) == 'tests.test_util_typing.BrokenType'