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 '2.0'

Browse Source
This commit is contained in:
Takeshi KOMIYA 2020-01-01 11:39:46 +09:00
commit e628afd5cd
203 changed files with 1167 additions and 1370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
CHANGES
View File

@ -50,10 +50,16 @@ Incompatible changes
Deprecated
----------
* The ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``
* ``sphinx.directives.other.Index``
* ``sphinx.environment.BuildEnvironment.indexentries``
* ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``
* ``sphinx.io.FiletypeNotFoundError``
* ``sphinx.io.get_filetype()``
* ``sphinx.pycode.ModuleAnalyzer.encoding``
* ``sphinx.roles.Index``
* ``sphinx.util.detect_encoding()``
* ``sphinx.util.get_module_source()``
Features added
--------------
@ -62,12 +68,14 @@ Features added
* #6446: duration: Add ``sphinx.ext.durations`` to inspect which documents slow
down the build
* #6837: LaTeX: Support a nested table
* #6966: graphviz: Support ``:class:`` option
Bugs fixed
----------
* #6925: html: Remove redundant type="text/javascript" from <script> elements
* #6906: autodoc: failed to read the source codes encoeded in cp1251
* #6906, #6907: autodoc: failed to read the source codes encoeded in cp1251
* #6961: latex: warning for babel shown twice
Testing
--------

30
doc/extdev/deprecated.rst
View File

@ -31,6 +31,16 @@ The following is a list of deprecated interfaces.
- 5.0
- ``sphinx.domains.std.StandardDomain.note_object()``
* - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``
- 2.4
- 4.0
- N/A
* - ``sphinx.directives.other.Index``
- 2.4
- 4.0
- ``sphinx.domains.index.IndexDirective``
* - ``sphinx.environment.BuildEnvironment.indexentries``
- 2.4
- 4.0
@ -51,6 +61,26 @@ The following is a list of deprecated interfaces.
- 4.0
- ``sphinx.util.get_filetype()``
* - ``sphinx.pycode.ModuleAnalyzer.encoding``
- 2.4
- 4.0
- N/A
* - ``sphinx.roles.Index``
- 2.4
- 4.0
- ``sphinx.domains.index.IndexRole``
* - ``sphinx.util.detect_encoding()``
- 2.4
- 4.0
- ``tokenize.detect_encoding()``
* - ``sphinx.util.get_module_source()``
- 2.4
- 4.0
- N/A
* - ``sphinx.builders.gettext.POHEADER``
- 2.3
- 4.0

21
doc/usage/extensions/graphviz.rst
View File

@ -82,6 +82,13 @@ It adds these directives:
.. versionadded:: 1.6
.. rst:directive:option:: class: class names
:type: a list of class names separeted by spaces
The class name of the graph.
.. versionadded:: 2.4
.. rst:directive:: graph
@ -131,6 +138,13 @@ It adds these directives:
.. versionadded:: 1.6
.. rst:directive:option:: class: class names
:type: a list of class names separeted by spaces
The class name of the graph.
.. versionadded:: 2.4
.. rst:directive:: digraph
@ -176,6 +190,13 @@ It adds these directives:
.. versionadded:: 1.6
.. rst:directive:option:: class: class names
:type: a list of class names separeted by spaces
The class name of the graph.
.. versionadded:: 2.4
There are also these config values:

1
setup.cfg
View File

@ -41,6 +41,7 @@ paths =
[mypy]
python_version = 3.5
disallow_incomplete_defs = True
show_column_numbers = True
show_error_context = True
ignore_missing_imports = True

2
sphinx/__init__.py
View File

@ -4,7 +4,7 @@
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/__main__.py
View File

@ -4,7 +4,7 @@
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/addnodes.py
View File

@ -4,7 +4,7 @@
Additional docutils nodes.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -12,6 +12,7 @@ import warnings
from typing import Any, Dict, List, Sequence
from docutils import nodes
from docutils.nodes import Node
from sphinx.deprecation import RemovedInSphinx40Warning
@ -305,7 +306,8 @@ class abbreviation(nodes.abbreviation):
.. deprecated:: 2.0
"""
def __init__(self, rawsource: str = '', text: str = '', *children, **attributes) -> None:
def __init__(self, rawsource: str = '', text: str = '',
*children: Node, **attributes: Any) -> None:
warnings.warn("abbrevition node for Sphinx was replaced by docutils'.",
RemovedInSphinx40Warning, stacklevel=2)

15
sphinx/application.py
View File

@ -6,7 +6,7 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -422,7 +422,7 @@ class Sphinx:
logger.debug('[app] disconnecting event: [id=%s]', listener_id)
self.events.disconnect(listener_id)
def emit(self, event: str, *args) -> List:
def emit(self, event: str, *args: Any) -> List:
"""Emit *event* and pass *arguments* to the callback functions.
Return the return values of all callbacks as a list. Do not emit core
@ -430,7 +430,7 @@ class Sphinx:
"""
return self.events.emit(event, *args)
def emit_firstresult(self, event: str, *args) -> Any:
def emit_firstresult(self, event: str, *args: Any) -> Any:
"""Emit *event* and pass *arguments* to the callback functions.
Return the result of the first callback that doesn't return ``None``.
@ -508,7 +508,8 @@ class Sphinx:
"""
self.registry.add_translator(name, translator_class, override=override)
def add_node(self, node: "Type[Element]", override: bool = False, **kwds) -> None:
def add_node(self, node: "Type[Element]", override: bool = False,
**kwds: Tuple[Callable, Callable]) -> None:
"""Register a Docutils node class.
This is necessary for Docutils internals. It may also be used in the
@ -548,7 +549,7 @@ class Sphinx:
def add_enumerable_node(self, node: "Type[Element]", figtype: str,
title_getter: TitleGetter = None, override: bool = False,
**kwds) -> None:
**kwds: Tuple[Callable, Callable]) -> None:
"""Register a Docutils node class as a numfig target.
Sphinx numbers the node automatically. And then the users can refer it
@ -575,7 +576,7 @@ class Sphinx:
self.registry.add_enumerable_node(node, figtype, title_getter, override=override)
self.add_node(node, override=override, **kwds)
def add_directive(self, name: str, cls: "Type[Directive]", override: bool = False):
def add_directive(self, name: str, cls: "Type[Directive]", override: bool = False) -> None:
"""Register a Docutils directive.
*name* must be the prospective directive name. *cls* is a directive
@ -1036,7 +1037,7 @@ class Sphinx:
"""
self.registry.add_source_suffix(suffix, filetype, override=override)
def add_source_parser(self, *args, **kwargs) -> None:
def add_source_parser(self, *args: Any, **kwargs: Any) -> None:
"""Register a parser class.
.. versionadded:: 1.4

6
sphinx/builders/__init__.py
View File

@ -4,7 +4,7 @@
Builder superclass for all builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -118,11 +118,11 @@ class Builder:
self.env.set_versioning_method(self.versioning_method,
self.versioning_compare)
def get_translator_class(self, *args) -> "Type[nodes.NodeVisitor]":
def get_translator_class(self, *args: Any) -> "Type[nodes.NodeVisitor]":
"""Return a class of translator."""
return self.app.registry.get_translator_class(self)
def create_translator(self, *args) -> nodes.NodeVisitor:
def create_translator(self, *args: Any) -> nodes.NodeVisitor:
"""Return an instance of translator.
This method returns an instance of ``default_translator_class`` by default.

2
sphinx/builders/_epub_base.py
View File

@ -4,7 +4,7 @@
Base class of epub2/epub3 builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/applehelp.py
View File

@ -4,7 +4,7 @@
Build Apple help books.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/builders/changes.py
View File

@ -4,7 +4,7 @@
Changelog builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -50,7 +50,7 @@ class ChangesBuilder(Builder):
'deprecated': 'deprecated',
}
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
version = self.config.version
domain = cast(ChangeSetDomain, self.env.get_domain('changeset'))
libchanges = {} # type: Dict[str, List[Tuple[str, str, int]]]

2
sphinx/builders/devhelp.py
View File

@ -6,7 +6,7 @@
.. _Devhelp: https://wiki.gnome.org/Apps/Devhelp
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/dirhtml.py
View File

@ -4,7 +4,7 @@
Directory HTML builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/builders/gettext.py
View File

@ -4,7 +4,7 @@
The MessageCatalogBuilder class.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -198,7 +198,7 @@ if source_date_epoch is not None:
class LocalTimeZone(tzinfo):
def __init__(self, *args, **kw) -> None:
def __init__(self, *args: Any, **kw: Any) -> None:
super().__init__(*args, **kw) # type: ignore
self.tzdelta = tzdelta
@ -212,7 +212,7 @@ class LocalTimeZone(tzinfo):
ltz = LocalTimeZone()
def should_write(filepath: str, new_content: str):
def should_write(filepath: str, new_content: str) -> bool:
if not path.exists(filepath):
return True
try:

4
sphinx/builders/html.py
View File

@ -4,7 +4,7 @@
Several HTML builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -858,7 +858,7 @@ class StandaloneHTMLBuilder(Builder):
indexer_name, indexer_name),
RemovedInSphinx40Warning)
def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds) -> str:
def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds: Any) -> str:
if 'includehidden' not in kwds:
kwds['includehidden'] = False
return self.render_partial(TocTree(self.env).get_toctree_for(

2
sphinx/builders/htmlhelp.py
View File

@ -5,7 +5,7 @@
Build HTML help support files.
Parts adapted from Python's Doc/tools/prechm.py.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/builders/latex/__init__.py
View File

@ -4,7 +4,7 @@
LaTeX builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -216,7 +216,7 @@ class LaTeXBuilder(Builder):
'[2016/05/29 stylesheet for highlighting with pygments]\n\n')
f.write(highlighter.get_stylesheet())
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
docwriter = LaTeXWriter(self)
docsettings = OptionParser(
defaults=self.env.settings,

2
sphinx/builders/latex/nodes.py
View File

@ -4,7 +4,7 @@
Additional nodes for LaTeX writer.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

18
sphinx/builders/latex/transforms.py
View File

@ -4,7 +4,7 @@
Transforms for LaTeX builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -32,7 +32,7 @@ class FootnoteDocnameUpdater(SphinxTransform):
default_priority = 700
TARGET_NODES = (nodes.footnote, nodes.footnote_reference)
def apply(self, **kwargs) -> None:
def apply(self, **kwargs: Any) -> None:
matcher = NodeMatcher(*self.TARGET_NODES)
for node in self.document.traverse(matcher): # type: nodes.Element
node['docname'] = self.env.docname
@ -51,7 +51,7 @@ class ShowUrlsTransform(SphinxPostTransform):
# references are expanded to footnotes (or not)
expanded = False
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
try:
# replace id_prefix temporarily
settings = self.document.settings # type: Any
@ -338,7 +338,7 @@ class LaTeXFootnoteTransform(SphinxPostTransform):
default_priority = 600
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
footnotes = list(self.document.traverse(nodes.footnote))
for node in footnotes:
node.parent.remove(node)
@ -490,7 +490,7 @@ class BibliographyTransform(SphinxPostTransform):
default_priority = 750
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
citations = thebibliography()
for node in self.document.traverse(nodes.citation):
node.parent.remove(node)
@ -509,7 +509,7 @@ class CitationReferenceTransform(SphinxPostTransform):
default_priority = 5 # before ReferencesResolver
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
domain = cast(CitationDomain, self.env.get_domain('citation'))
matcher = NodeMatcher(addnodes.pending_xref, refdomain='citation', reftype='ref')
for node in self.document.traverse(matcher): # type: addnodes.pending_xref
@ -529,7 +529,7 @@ class MathReferenceTransform(SphinxPostTransform):
default_priority = 5 # before ReferencesResolver
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
equations = self.env.get_domain('math').data['objects']
for node in self.document.traverse(addnodes.pending_xref):
if node['refdomain'] == 'math' and node['reftype'] in ('eq', 'numref'):
@ -544,7 +544,7 @@ class LiteralBlockTransform(SphinxPostTransform):
default_priority = 400
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
matcher = NodeMatcher(nodes.container, literal_block=True)
for node in self.document.traverse(matcher): # type: nodes.container
newnode = captioned_literal_block('', *node.children, **node.attributes)
@ -556,7 +556,7 @@ class DocumentTargetTransform(SphinxPostTransform):
default_priority = 400
builders = ('latex',)
def run(self, **kwargs) -> None:
def run(self, **kwargs: Any) -> None:
for node in self.document.traverse(addnodes.start_of_file):
section = node.next_node(nodes.section)
if section:

2
sphinx/builders/linkcheck.py
View File

@ -4,7 +4,7 @@
The CheckExternalLinksBuilder class.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/builders/manpage.py
View File

@ -4,7 +4,7 @@
Manual pages builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -56,7 +56,7 @@ class ManualPageBuilder(Builder):
raise NoUri
@progress_message(__('writing'))
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
docwriter = ManualPageWriter(self)
docsettings = OptionParser(
defaults=self.env.settings,

2
sphinx/builders/qthelp.py
View File

@ -4,7 +4,7 @@
Build input files for the Qt collection generator.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/builders/singlehtml.py
View File

@ -4,7 +4,7 @@
Single HTML builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -67,7 +67,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
if hashindex >= 0:
refnode['refuri'] = fname + refuri[hashindex:]
def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds) -> str:
def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds: Any) -> str:
if 'includehidden' not in kwds:
kwds['includehidden'] = False
toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwds)
@ -149,7 +149,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
'display_toc': display_toc,
}
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
docnames = self.env.all_docs
with progress_message(__('preparing documents')):

4
sphinx/builders/texinfo.py
View File

@ -4,7 +4,7 @@
Texinfo builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -90,7 +90,7 @@ class TexinfoBuilder(Builder):
docname = docname[:-5]
self.titles.append((docname, entry[2]))
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
self.init_document_data()
for entry in self.document_data:
docname, targetname, title, author = entry[:4]

2
sphinx/builders/text.py
View File

@ -4,7 +4,7 @@
Plain-text Sphinx builder.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/xml.py
View File

@ -4,7 +4,7 @@
Docutils-native XML and pseudo-XML builders.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/cmd/__init__.py
View File

@ -4,6 +4,6 @@
Modules for command line executables.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/cmd/build.py
View File

@ -4,7 +4,7 @@
Build documentation from a provided source.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/cmd/make_mode.py
View File

@ -10,7 +10,7 @@
This is in its own module so that importing it is fast. It should not
import the main Sphinx modules (like sphinx.applications, sphinx.builders).
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/cmd/quickstart.py
View File

@ -4,7 +4,7 @@
Quickly setup documentation source to work with Sphinx.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/config.py
View File

@ -4,7 +4,7 @@
Build configuration file handling.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/deprecation.py
View File

@ -4,7 +4,7 @@
Sphinx deprecation classes and utilities.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

7
sphinx/directives/__init__.py
View File

@ -4,7 +4,7 @@
Handlers for additional ReST directives.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -253,12 +253,13 @@ from sphinx.directives.code import ( # noqa
Highlight, CodeBlock, LiteralInclude
)
from sphinx.directives.other import ( # noqa
TocTree, Author, Index, VersionChange, SeeAlso,
TocTree, Author, VersionChange, SeeAlso,
TabularColumns, Centered, Acks, HList, Only, Include, Class
)
from sphinx.directives.patches import ( # noqa
Figure, Meta
)
from sphinx.domains.index import IndexDirective # noqa
deprecated_alias('sphinx.directives',
{
@ -267,7 +268,7 @@ deprecated_alias('sphinx.directives',
'LiteralInclude': LiteralInclude,
'TocTree': TocTree,
'Author': Author,
'Index': Index,
'Index': IndexDirective,
'VersionChange': VersionChange,
'SeeAlso': SeeAlso,
'TabularColumns': TabularColumns,

2
sphinx/directives/code.py
View File

@ -2,7 +2,7 @@
sphinx.directives.code
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

40
sphinx/directives/other.py
View File

@ -2,7 +2,7 @@
sphinx.directives.other
~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -18,12 +18,13 @@ from docutils.parsers.rst.directives.misc import Class
from docutils.parsers.rst.directives.misc import Include as BaseInclude
from sphinx import addnodes
from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
from sphinx.domains.changeset import VersionChange # NOQA # for compatibility
from sphinx.locale import _
from sphinx.util import url_re, docname_join
from sphinx.util.docutils import SphinxDirective
from sphinx.util.matching import Matcher, patfilter
from sphinx.util.nodes import explicit_title_re, process_index_entry
from sphinx.util.nodes import explicit_title_re
if False:
# For type annotation
@ -182,30 +183,6 @@ class Author(SphinxDirective):
return ret
class Index(SphinxDirective):
"""
Directive to add entries to the index.
"""
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {} # type: Dict
def run(self) -> List[Node]:
arguments = self.arguments[0].split('\n')
targetid = 'index-%s' % self.env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
self.state.document.note_explicit_target(targetnode)
indexnode = addnodes.index()
indexnode['entries'] = []
indexnode['inline'] = False
self.set_source_info(indexnode)
for entry in arguments:
indexnode['entries'].extend(process_index_entry(entry, targetid))
return [indexnode, targetnode]
class SeeAlso(BaseAdmonition):
"""
An admonition mentioning things to look at as reference.
@ -383,12 +360,21 @@ class Include(BaseInclude, SphinxDirective):
return super().run()
# Import old modules here for compatibility
from sphinx.domains.index import IndexDirective # NOQA
deprecated_alias('sphinx.directives.other',
{
'Index': IndexDirective,
},
RemovedInSphinx40Warning)
def setup(app: "Sphinx") -> Dict[str, Any]:
directives.register_directive('toctree', TocTree)
directives.register_directive('sectionauthor', Author)
directives.register_directive('moduleauthor', Author)
directives.register_directive('codeauthor', Author)
directives.register_directive('index', Index)
directives.register_directive('seealso', SeeAlso)
directives.register_directive('tabularcolumns', TabularColumns)
directives.register_directive('centered', Centered)

2
sphinx/directives/patches.py
View File

@ -2,7 +2,7 @@
sphinx.directives.patches
~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/domains/__init__.py
View File

@ -5,7 +5,7 @@
Support for domains, which are groupings of description directives
and roles describing e.g. constructs of one programming language.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -48,7 +48,7 @@ class ObjType:
'searchprio': 1,
}
def __init__(self, lname: str, *roles, **attrs) -> None:
def __init__(self, lname: str, *roles: Any, **attrs: Any) -> None:
self.lname = lname
self.roles = roles # type: Tuple
self.attrs = self.known_attrs.copy() # type: Dict

2
sphinx/domains/c.py
View File

@ -4,7 +4,7 @@
The C language domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/changeset.py
View File

@ -4,7 +4,7 @@
The changeset domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/domains/citation.py
View File

@ -4,7 +4,7 @@
The citation domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -112,7 +112,7 @@ class CitationDefinitionTransform(SphinxTransform):
"""Mark citation definition labels as not smartquoted."""
default_priority = 619
def apply(self, **kwargs) -> None:
def apply(self, **kwargs: Any) -> None:
domain = cast(CitationDomain, self.env.get_domain('citation'))
for node in self.document.traverse(nodes.citation):
# register citation node to domain
@ -131,7 +131,7 @@ class CitationReferenceTransform(SphinxTransform):
"""
default_priority = 619
def apply(self, **kwargs) -> None:
def apply(self, **kwargs: Any) -> None:
domain = cast(CitationDomain, self.env.get_domain('citation'))
for node in self.document.traverse(nodes.citation_reference):
target = node.astext()

1557
sphinx/domains/cpp.py
View File

File diff suppressed because it is too large Load Diff

63
sphinx/domains/index.py
View File

@ -4,20 +4,26 @@
The index domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from typing import Any, Dict, Iterable, List, Tuple
from docutils.nodes import Node
from docutils import nodes
from docutils.nodes import Node, system_message
from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.domains import Domain
from sphinx.environment import BuildEnvironment
from sphinx.util import logging
from sphinx.util import split_index_msg
from sphinx.util.docutils import ReferenceRole, SphinxDirective
from sphinx.util.nodes import process_index_entry
if False:
# For type annotation
from sphinx.application import Sphinx
logger = logging.getLogger(__name__)
@ -54,8 +60,57 @@ class IndexDomain(Domain):
entries.append(entry)
def setup(app: Sphinx) -> Dict[str, Any]:
class IndexDirective(SphinxDirective):
"""
Directive to add entries to the index.
"""
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {} # type: Dict
def run(self) -> List[Node]:
arguments = self.arguments[0].split('\n')
targetid = 'index-%s' % self.env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
self.state.document.note_explicit_target(targetnode)
indexnode = addnodes.index()
indexnode['entries'] = []
indexnode['inline'] = False
self.set_source_info(indexnode)
for entry in arguments:
indexnode['entries'].extend(process_index_entry(entry, targetid))
return [indexnode, targetnode]
class IndexRole(ReferenceRole):
def run(self) -> Tuple[List[Node], List[system_message]]:
target_id = 'index-%s' % self.env.new_serialno('index')
if self.has_explicit_title:
# if an explicit target is given, process it as a full entry
title = self.title
entries = process_index_entry(self.target, target_id)
else:
# otherwise we just create a single entry
if self.target.startswith('!'):
title = self.title[1:]
entries = [('single', self.target[1:], target_id, 'main', None)]
else:
title = self.title
entries = [('single', self.target, target_id, '', None)]
index = addnodes.index(entries=entries)
target = nodes.target('', '', ids=[target_id])
text = nodes.Text(title, title)
self.set_source_info(index)
return [index, target, text], []
def setup(app: "Sphinx") -> Dict[str, Any]:
app.add_domain(IndexDomain)
app.add_directive('index', IndexDirective)
app.add_role('index', IndexRole())
return {
'version': 'builtin',

2
sphinx/domains/javascript.py
View File

@ -4,7 +4,7 @@
The JavaScript domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/math.py
View File

@ -4,7 +4,7 @@
The math domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/python.py
View File

@ -4,7 +4,7 @@
The Python domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/rst.py
View File

@ -4,7 +4,7 @@
The reStructuredText domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/domains/std.py
View File

@ -4,7 +4,7 @@
The standard domain.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -643,7 +643,7 @@ class StandardDomain(Domain):
self.progoptions[program, name] = (docname, labelid)
def build_reference_node(self, fromdocname: str, builder: "Builder", docname: str,
labelid: str, sectname: str, rolename: str, **options
labelid: str, sectname: str, rolename: str, **options: Any
) -> Element:
nodeclass = options.pop('nodeclass', nodes.reference)
newnode = nodeclass('', '', internal=True, **options)

2
sphinx/environment/__init__.py
View File

@ -4,7 +4,7 @@
Global creation environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/adapters/__init__.py
View File

@ -4,6 +4,6 @@
Sphinx environment adapters
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/adapters/asset.py
View File

@ -4,7 +4,7 @@
Assets adapter for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/adapters/indexentries.py
View File

@ -4,7 +4,7 @@
Index entries adapters for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import bisect

8
sphinx/environment/adapters/toctree.py
View File

@ -4,12 +4,12 @@
Toctree adapter for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from typing import Any, Iterable, List
from typing import cast
from typing import Iterable, List
from docutils import nodes
from docutils.nodes import Element, Node
@ -314,8 +314,8 @@ class TocTree:
node['refuri'] = node['anchorname'] or '#'
return toc
def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool, **kwds
) -> Element:
def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool,
**kwds: Any) -> Element:
"""Return the global TOC nodetree."""
doctree = self.env.get_doctree(self.env.config.master_doc)
toctrees = [] # type: List[Element]

2
sphinx/environment/collectors/__init__.py
View File

@ -4,7 +4,7 @@
The data collector components for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/asset.py
View File

@ -4,7 +4,7 @@
The image collector for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/dependencies.py
View File

@ -4,7 +4,7 @@
The dependencies collector components for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/indexentries.py
View File

@ -4,7 +4,7 @@
Index entries collector for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/metadata.py
View File

@ -4,7 +4,7 @@
The metadata collector components for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/title.py
View File

@ -4,7 +4,7 @@
The title collector components for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/toctree.py
View File

@ -4,7 +4,7 @@
Toctree collector for sphinx.environment.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/errors.py
View File

@ -5,7 +5,7 @@
Contains SphinxError and a few subclasses (in an extra module to avoid
circular import problems).
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/events.py
View File

@ -6,7 +6,7 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -81,7 +81,7 @@ class EventManager:
for event in self.listeners.values():
event.pop(listener_id, None)
def emit(self, name: str, *args) -> List:
def emit(self, name: str, *args: Any) -> List:
"""Emit a Sphinx event."""
try:
logger.debug('[app] emitting event: %r%s', name, repr(args)[:100])
@ -99,7 +99,7 @@ class EventManager:
results.append(callback(self.app, *args))
return results
def emit_firstresult(self, name: str, *args) -> Any:
def emit_firstresult(self, name: str, *args: Any) -> Any:
"""Emit a Sphinx event and returns first result.
This returns the result of the first handler that doesn't return ``None``.

2
sphinx/ext/__init__.py
View File

@ -4,6 +4,6 @@
Contains Sphinx features not activated by default.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/apidoc.py
View File

@ -10,7 +10,7 @@
Copyright 2008 Société des arts technologiques (SAT),
https://sat.qc.ca/
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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

@ -6,7 +6,7 @@
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -227,7 +227,7 @@ class Documenter:
option_spec = {'noindex': bool_option} # type: Dict[str, Callable]
def get_attr(self, obj: Any, name: str, *defargs) -> Any:
def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
"""getattr() override for types such as Zope interfaces."""
return autodoc_attrgetter(self.env.app, obj, name, *defargs)
@ -357,7 +357,7 @@ class Documenter:
return False
return True
def format_args(self, **kwargs) -> str:
def format_args(self, **kwargs: Any) -> str:
"""Format the argument signature of *self.object*.
Should return None if the object does not have a signature.
@ -375,7 +375,7 @@ class Documenter:
# directives of course)
return '.'.join(self.objpath) or self.modname
def format_signature(self, **kwargs) -> str:
def format_signature(self, **kwargs: Any) -> str:
"""Format the signature (arguments and return annotation) of the object.
Let the user process it via the ``autodoc-process-signature`` event.
@ -773,7 +773,7 @@ class ModuleDocumenter(Documenter):
'imported-members': bool_option, 'ignore-module-all': bool_option
} # type: Dict[str, Callable]
def __init__(self, *args) -> None:
def __init__(self, *args: Any) -> None:
super().__init__(*args)
merge_special_members_option(self.options)
@ -951,7 +951,7 @@ class DocstringSignatureMixin:
return lines
return super().get_doc(None, ignore) # type: ignore
def format_signature(self, **kwargs) -> str:
def format_signature(self, **kwargs: Any) -> str:
if self.args is None and self.env.config.autodoc_docstring_signature: # type: ignore
# only act if a signature is not explicitly given already, and if
# the feature is enabled
@ -966,7 +966,7 @@ class DocstringStripSignatureMixin(DocstringSignatureMixin):
Mixin for AttributeDocumenter to provide the
feature of stripping any function signature from the docstring.
"""
def format_signature(self, **kwargs) -> str:
def format_signature(self, **kwargs: Any) -> str:
if self.args is None and self.env.config.autodoc_docstring_signature: # type: ignore
# only act if a signature is not explicitly given already, and if
# the feature is enabled
@ -993,7 +993,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
return (inspect.isfunction(member) or inspect.isbuiltin(member) or
(inspect.isroutine(member) and isinstance(parent, ModuleDocumenter)))
def format_args(self, **kwargs) -> str:
def format_args(self, **kwargs: Any) -> str:
if self.env.config.autodoc_typehints == 'none':
kwargs.setdefault('show_annotation', False)
@ -1070,7 +1070,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
'private-members': bool_option, 'special-members': members_option,
} # type: Dict[str, Callable]
def __init__(self, *args) -> None:
def __init__(self, *args: Any) -> None:
super().__init__(*args)
merge_special_members_option(self.options)
@ -1090,7 +1090,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
self.doc_as_attr = True
return ret
def format_args(self, **kwargs) -> str:
def format_args(self, **kwargs: Any) -> str:
if self.env.config.autodoc_typehints == 'none':
kwargs.setdefault('show_annotation', False)
@ -1110,7 +1110,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
# with __init__ in C
return None
def format_signature(self, **kwargs) -> str:
def format_signature(self, **kwargs: Any) -> str:
if self.doc_as_attr:
return ''
@ -1298,7 +1298,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
return ret
def format_args(self, **kwargs) -> str:
def format_args(self, **kwargs: Any) -> str:
if self.env.config.autodoc_typehints == 'none':
kwargs.setdefault('show_annotation', False)
@ -1313,7 +1313,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
args = args.replace('\\', '\\\\')
return args
def add_directive_header(self, sig) -> None:
def add_directive_header(self, sig: str) -> None:
super().add_directive_header(sig)
sourcename = self.get_sourcename()
@ -1515,7 +1515,7 @@ def get_documenters(app: Sphinx) -> Dict[str, "Type[Documenter]"]:
return app.registry.documenters
def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs) -> Any:
def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
"""Alternative getattr() for types"""
for typ, func in app.registry.autodoc_attrgettrs.items():
if isinstance(obj, typ):

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

@ -4,7 +4,7 @@
Importer utilities for autodoc
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

8
sphinx/ext/autodoc/mock.py
View File

@ -4,7 +4,7 @@
mock for autodoc
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -26,7 +26,7 @@ class _MockObject:
__display_name__ = '_MockObject'
def __new__(cls, *args, **kwargs) -> Any:
def __new__(cls, *args: Any, **kwargs: Any) -> Any:
if len(args) == 3 and isinstance(args[1], tuple):
superclass = args[1][-1].__class__
if superclass is cls:
@ -36,7 +36,7 @@ class _MockObject:
return super().__new__(cls)
def __init__(self, *args, **kwargs) -> None:
def __init__(self, *args: Any, **kwargs: Any) -> None:
self.__qualname__ = ''
def __len__(self) -> int:
@ -57,7 +57,7 @@ class _MockObject:
def __getattr__(self, key: str) -> "_MockObject":
return _make_subclass(key, self.__display_name__, self.__class__)()
def __call__(self, *args, **kw) -> Any:
def __call__(self, *args: Any, **kw: Any) -> Any:
if args and type(args[0]) in [type, FunctionType, MethodType]:
# Appears to be a decorator, pass through unchanged
return args[0]

2
sphinx/ext/autosectionlabel.py
View File

@ -4,7 +4,7 @@
Allow reference sections by :ref: role using its title.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/autosummary/__init__.py
View File

@ -48,7 +48,7 @@
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/ext/autosummary/generate.py
View File

@ -13,7 +13,7 @@
generate:
sphinx-autogen -o source/generated source/*.rst
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -62,7 +62,7 @@ class DummyApplication:
self._warncount = 0
self.warningiserror = False
def emit_firstresult(self, *args) -> None:
def emit_firstresult(self, *args: Any) -> None:
pass

4
sphinx/ext/coverage.py
View File

@ -5,7 +5,7 @@
Check Python modules and C API for coverage. Mostly written by Josip
Dzolonga for the Google Highly Open Participation contest.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -80,7 +80,7 @@ class CoverageBuilder(Builder):
def get_outdated_docs(self) -> str:
return 'coverage overview'
def write(self, *ignored) -> None:
def write(self, *ignored: Any) -> None:
self.py_undoc = {} # type: Dict[str, Dict[str, Any]]
self.build_py_coverage()
self.write_py_coverage()

2
sphinx/ext/doctest.py
View File

@ -5,7 +5,7 @@
Mimic doctest by automatically executing code snippets and checking
their results.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/ext/duration.py
View File

@ -4,7 +4,7 @@
Measure durations of Sphinx processing.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -32,7 +32,7 @@ class DurationDomain(Domain):
def reading_durations(self) -> Dict[str, timedelta]:
return self.data.setdefault('reading_durations', {})
def note_reading_duration(self, duration: timedelta):
def note_reading_duration(self, duration: timedelta) -> None:
self.reading_durations[self.env.docname] = duration
def clear(self) -> None:
@ -69,7 +69,7 @@ def on_doctree_read(app: Sphinx, doctree: nodes.document) -> None:
domain.note_reading_duration(duration)
def on_build_finished(app: Sphinx, error):
def on_build_finished(app: Sphinx, error: Exception) -> None:
"""Display duration ranking on current build."""
domain = cast(DurationDomain, app.env.get_domain('duration'))
durations = sorted(domain.reading_durations.items(), key=itemgetter(1), reverse=True)

2
sphinx/ext/extlinks.py
View File

@ -19,7 +19,7 @@
You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/githubpages.py
View File

@ -4,7 +4,7 @@
To publish HTML docs at GitHub Pages, create .nojekyll file.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

14
sphinx/ext/graphviz.py
View File

@ -5,7 +5,7 @@
Allow graphviz-formatted graphs to be included in Sphinx-generated
documents inline.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -121,6 +121,7 @@ class Graphviz(SphinxDirective):
'layout': directives.unchanged,
'graphviz_dot': directives.unchanged, # an old alias of `layout` option
'name': directives.unchanged,
'class': directives.class_option,
}
def run(self) -> List[Node]:
@ -158,6 +159,8 @@ class Graphviz(SphinxDirective):
node['alt'] = self.options['alt']
if 'align' in self.options:
node['align'] = self.options['align']
if 'class' in self.options:
node['classes'] = self.options['class']
if 'caption' not in self.options:
self.add_name(node)
@ -182,6 +185,7 @@ class GraphvizSimple(SphinxDirective):
'caption': directives.unchanged,
'graphviz_dot': directives.unchanged,
'name': directives.unchanged,
'class': directives.class_option,
}
def run(self) -> List[Node]:
@ -195,6 +199,8 @@ class GraphvizSimple(SphinxDirective):
node['alt'] = self.options['alt']
if 'align' in self.options:
node['align'] = self.options['align']
if 'class' in self.options:
node['classes'] = self.options['class']
if 'caption' not in self.options:
self.add_name(node)
@ -267,10 +273,8 @@ def render_dot_html(self: HTMLTranslator, node: graphviz, code: str, options: Di
logger.warning(__('dot code %r: %s'), code, exc)
raise nodes.SkipNode
if imgcls:
imgcls += " graphviz"
else:
imgcls = "graphviz"
classes = [imgcls, 'graphviz'] + node.get('classes', [])
imgcls = ' '.join(filter(None, classes))
if fname is None:
self.body.append(self.encode(code))

2
sphinx/ext/ifconfig.py
View File

@ -15,7 +15,7 @@
namespace of the project configuration (that is, all variables from
``conf.py`` are available.)
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/imgconverter.py
View File

@ -4,7 +4,7 @@
Image converter extension for Sphinx
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/imgmath.py
View File

@ -4,7 +4,7 @@
Render math in HTML via dvipng or dvisvgm.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/inheritance_diagram.py
View File

@ -31,7 +31,7 @@ r"""
The graph is inserted as a PNG+image map into HTML and a PDF in
LaTeX.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/intersphinx.py
View File

@ -19,7 +19,7 @@
also be specified individually, e.g. if the docs should be buildable
without Internet access.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/jsmath.py
View File

@ -5,7 +5,7 @@
Set up everything for use of JSMath to display math in HTML
via JavaScript.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/linkcode.py
View File

@ -4,7 +4,7 @@
Add external links to module code in Python object descriptions.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/mathjax.py
View File

@ -6,7 +6,7 @@
Sphinx's HTML writer -- requires the MathJax JavaScript library on your
webserver/computer.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/ext/napoleon/__init__.py
View File

@ -4,7 +4,7 @@
Support for NumPy and Google style docstrings.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -265,7 +265,7 @@ class Config:
'napoleon_custom_sections': (None, 'env')
}
def __init__(self, **settings) -> None:
def __init__(self, **settings: Any) -> None:
for name, (default, rebuild) in self._config_values.items():
setattr(self, name, default)
for name, value in settings.items():

2
sphinx/ext/napoleon/docstring.py
View File

@ -6,7 +6,7 @@
Classes for docstring parsing and formatting.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/ext/napoleon/iterators.py
View File

@ -6,7 +6,7 @@
A collection of helpful iterators.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -47,7 +47,7 @@ class peek_iter:
be set to a new object instance: ``object()``.
"""
def __init__(self, *args) -> None:
def __init__(self, *args: Any) -> None:
"""__init__(o, sentinel=None)"""
self._iterable = iter(*args) # type: Iterable
self._cache = collections.deque() # type: collections.deque
@ -206,7 +206,7 @@ class modify_iter(peek_iter):
"whitespace."
"""
def __init__(self, *args, **kwargs) -> None:
def __init__(self, *args: Any, **kwargs: Any) -> None:
"""__init__(o, sentinel=None, modifier=lambda x: x)"""
if 'modifier' in kwargs:
self.modifier = kwargs['modifier']

2
sphinx/ext/todo.py
View File

@ -7,7 +7,7 @@
all todos of your project and lists them along with a backlink to the
original location.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/viewcode.py
View File

@ -4,7 +4,7 @@
Add links to module code in Python object descriptions.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/extension.py
View File

@ -4,7 +4,7 @@
Utilities for Sphinx extensions.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -23,7 +23,7 @@ logger = logging.getLogger(__name__)
class Extension:
def __init__(self, name: str, module: Any, **kwargs) -> None:
def __init__(self, name: str, module: Any, **kwargs: Any) -> None:
self.name = name
self.module = module
self.metadata = kwargs

6
sphinx/highlighting.py
View File

@ -4,7 +4,7 @@
Highlight code blocks using Pygments.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -84,7 +84,7 @@ class PygmentsBridge:
else:
return get_style_by_name(stylename)
def get_formatter(self, **kwargs) -> Formatter:
def get_formatter(self, **kwargs: Any) -> Formatter:
kwargs.update(self.formatter_args)
return self.formatter(**kwargs)
@ -133,7 +133,7 @@ class PygmentsBridge:
return lexer
def highlight_block(self, source: str, lang: str, opts: Dict = None,
force: bool = False, location: Any = None, **kwargs) -> str:
force: bool = False, location: Any = None, **kwargs: Any) -> str:
if not isinstance(source, str):
source = source.decode()

8
sphinx/io.py
View File

@ -4,7 +4,7 @@
Input/Output files
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import codecs
@ -55,7 +55,7 @@ class SphinxBaseReader(standalone.Reader):
transforms = [] # type: List[Type[Transform]]
def __init__(self, *args, **kwargs) -> None:
def __init__(self, *args: Any, **kwargs: Any) -> None:
from sphinx.application import Sphinx
if len(args) > 0 and isinstance(args[0], Sphinx):
self._app = args[0]
@ -166,14 +166,14 @@ class SphinxDummyWriter(UnfilteredWriter):
pass
def SphinxDummySourceClass(source: Any, *args, **kwargs) -> Any:
def SphinxDummySourceClass(source: Any, *args: Any, **kwargs: Any) -> Any:
"""Bypass source object as is to cheat Publisher."""
return source
class SphinxFileInput(FileInput):
"""A basic FileInput for Sphinx."""
def __init__(self, *args, **kwargs) -> None:
def __init__(self, *args: Any, **kwargs: Any) -> None:
kwargs['error_handler'] = 'sphinx'
super().__init__(*args, **kwargs)

4
sphinx/jinja2glue.py
View File

@ -4,7 +4,7 @@
Glue code for the jinja2 templating engine.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -103,7 +103,7 @@ class idgen:
@contextfunction
def warning(context: Dict, message: str, *args, **kwargs) -> str:
def warning(context: Dict, message: str, *args: Any, **kwargs: Any) -> str:
if 'pagename' in context:
filename = context.get('pagename') + context.get('file_suffix', '')
message = 'in rendering %s: %s' % (filename, message)

2
sphinx/locale/__init__.py
View File

@ -222,7 +222,7 @@ def get_translation(catalog, namespace='general'):
.. versionadded:: 1.8
"""
def gettext(message: str, *args) -> str:
def gettext(message: str, *args: Any) -> str:
if not is_translator_registered(catalog, namespace):
# not initialized yet
return _TranslationProxy(_lazy_translate, catalog, namespace, message) # type: ignore # NOQA

2
sphinx/parsers.py
View File

@ -4,7 +4,7 @@
A Base class for additional parsers.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/project.py
View File

@ -4,7 +4,7 @@
Utility function and classes for Sphinx projects.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

87
sphinx/pycode/__init__.py
View File

@ -4,25 +4,76 @@
Utilities parsing and analyzing Python code.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re
import tokenize
import warnings
from importlib import import_module
from io import StringIO
from os import path
from typing import Any, Dict, IO, List, Tuple
from typing import Any, Dict, IO, List, Tuple, Optional
from zipfile import ZipFile
from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.errors import PycodeError
from sphinx.pycode.parser import Parser
from sphinx.util import get_module_source, detect_encoding
class ModuleAnalyzer:
# cache for analyzer objects -- caches both by module and file name
cache = {} # type: Dict[Tuple[str, str], Any]
@staticmethod
def get_module_source(modname: str) -> Tuple[Optional[str], Optional[str]]:
"""Try to find the source code for a module.
Returns ('filename', 'source'). One of it can be None if
no filename or source found
"""
try:
mod = import_module(modname)
except Exception as err:
raise PycodeError('error importing %r' % modname, err)
loader = getattr(mod, '__loader__', None)
filename = getattr(mod, '__file__', None)
if loader and getattr(loader, 'get_source', None):
# prefer Native loader, as it respects #coding directive
try:
source = loader.get_source(modname)
if source:
# no exception and not None - it must be module source
return filename, source
except ImportError:
pass # Try other "source-mining" methods
if filename is None and loader and getattr(loader, 'get_filename', None):
# have loader, but no filename
try:
filename = loader.get_filename(modname)
except ImportError as err:
raise PycodeError('error getting filename for %r' % modname, err)
if filename is None:
# all methods for getting filename failed, so raise...
raise PycodeError('no source found for module %r' % modname)
filename = path.normpath(path.abspath(filename))
if filename.lower().endswith(('.pyo', '.pyc')):
filename = filename[:-1]
if not path.isfile(filename) and path.isfile(filename + 'w'):
filename += 'w'
elif not filename.lower().endswith(('.py', '.pyw')):
raise PycodeError('source is not a .py file: %r' % filename)
elif ('.egg' + path.sep) in filename:
pat = '(?<=\\.egg)' + re.escape(path.sep)
eggpath, _ = re.split(pat, filename, 1)
if path.isfile(eggpath):
return filename, None
if not path.isfile(filename):
raise PycodeError('source file is not present: %r' % filename)
return filename, None
@classmethod
def for_string(cls, string: str, modname: str, srcname: str = '<string>'
) -> "ModuleAnalyzer":
@ -33,8 +84,8 @@ class ModuleAnalyzer:
if ('file', filename) in cls.cache:
return cls.cache['file', filename]
try:
with open(filename, 'rb') as f:
obj = cls(f, modname, filename)
with tokenize.open(filename) as f:
obj = cls(f, modname, filename, decoded=True)
cls.cache['file', filename] = obj
except Exception as err:
if '.egg' + path.sep in filename:
@ -63,11 +114,11 @@ class ModuleAnalyzer:
return entry
try:
type, source = get_module_source(modname)
if type == 'string':
obj = cls.for_string(source, modname)
else:
obj = cls.for_file(source, modname)
filename, source = cls.get_module_source(modname)
if source is not None:
obj = cls.for_string(source, modname, filename or '<string>')
elif filename is not None:
obj = cls.for_file(filename, modname)
except PycodeError as err:
cls.cache['module', modname] = err
raise
@ -81,11 +132,13 @@ class ModuleAnalyzer:
# cache the source code as well
pos = source.tell()
if not decoded:
self.encoding = detect_encoding(source.readline)
warnings.warn('decode option for ModuleAnalyzer is deprecated.',
RemovedInSphinx40Warning)
self._encoding, _ = tokenize.detect_encoding(source.readline)
source.seek(pos)
self.code = source.read().decode(self.encoding)
self.code = source.read().decode(self._encoding)
else:
self.encoding = None
self._encoding = None
self.code = source.read()
# will be filled by parse()
@ -96,7 +149,7 @@ class ModuleAnalyzer:
def parse(self) -> None:
"""Parse the source code."""
try:
parser = Parser(self.code, self.encoding)
parser = Parser(self.code, self._encoding)
parser.parse()
self.attr_docs = {}
@ -124,3 +177,9 @@ class ModuleAnalyzer:
self.parse()
return self.tags
@property
def encoding(self) -> str:
warnings.warn('ModuleAnalyzer.encoding is deprecated.',
RemovedInSphinx40Warning)
return self._encoding

4
sphinx/pycode/parser.py
View File

@ -4,7 +4,7 @@
Utilities parsing and analyzing Python code.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import ast
@ -117,7 +117,7 @@ class Token:
else:
raise ValueError('Unknown value: %r' % other)
def match(self, *conditions) -> bool:
def match(self, *conditions: Any) -> bool:
return any(self == candidate for candidate in conditions)
def __repr__(self) -> str:

2
sphinx/pygments_styles.py
View File

@ -4,7 +4,7 @@
Sphinx theme specific highlighting styles.
:copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

9
sphinx/registry.py
View File

@ -257,7 +257,7 @@ class SphinxComponentRegistry:
else:
self.source_suffix[suffix] = filetype
def add_source_parser(self, parser: "Type[Parser]", **kwargs) -> None:
def add_source_parser(self, parser: "Type[Parser]", **kwargs: Any) -> None:
logger.debug('[app] adding search source_parser: %r', parser)
# create a map from filetype to parser
@ -301,7 +301,8 @@ class SphinxComponentRegistry:
raise ExtensionError(__('Translator for %r already exists') % name)
self.translators[name] = translator
def add_translation_handlers(self, node: "Type[Element]", **kwargs) -> None:
def add_translation_handlers(self, node: "Type[Element]",
**kwargs: Tuple[Callable, Callable]) -> None:
logger.debug('[app] adding translation_handlers: %r, %r', node, kwargs)
for builder_name, handlers in kwargs.items():
translation_handlers = self.translation_handlers.setdefault(builder_name, {})
@ -310,13 +311,13 @@ class SphinxComponentRegistry:
translation_handlers[node.__name__] = (visit, depart)
except ValueError:
raise ExtensionError(__('kwargs for add_node() must be a (visit, depart) '
'function tuple: %r=%r') % builder_name, handlers)
'function tuple: %r=%r') % (builder_name, handlers))
def get_translator_class(self, builder: Builder) -> "Type[nodes.NodeVisitor]":
return self.translators.get(builder.name,
builder.default_translator_class)
def create_translator(self, builder: Builder, *args) -> nodes.NodeVisitor:
def create_translator(self, builder: Builder, *args: Any) -> nodes.NodeVisitor:
translator_class = self.get_translator_class(builder)
assert translator_class, "translator not found for %s" % builder.name
translator = translator_class(*args)

Some files were not shown because too many files have changed in this diff Show More