diff options
142 files changed, 5581 insertions, 2277 deletions
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 000000000..4fbf6ff2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,27 @@ +Subject: <what happen when you do on which document project> + +### Problem +- <Detail of problem> + +#### Procedure to reproduce the problem +``` +<Paste your command-line here which cause the problem> +``` + +#### Error logs / results +``` +<Paste your error log here> +``` +- <public link of unexpected result if you have> + +#### Expected results +<Describe what to actually do> + +### Reproducible project / your project +- <link to your project, or attach zipped small project sample> + +### Environment info +- OS: <Unix/Linux/Mac/Win/other with version> +- Python version: +- Sphinx version: +- <Extra tools e.g.: Browser, tex or something else> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..073a57795 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +Subject: <short purpose of this pull request> + +### Feature or Bugfix +<!-- please choose --> +- Feature +- Bugfix + +### Purpose +- <long purpose of this pull request> +- <Environment if this PR depends on> + +### Detail +- <feature1 or bug1> +- <feature2 or bug2> + +### Relates +- <URL or Ticket> + @@ -1,3 +1,55 @@ +Release 1.6 (in development) +============================ + +Incompatible changes +-------------------- + +* #1061, #2336, #3235: Now generation of autosummary doesn't contain imported + members by default. Thanks to Luc Saffre. +* LaTeX ``\includegraphics`` command isn't overloaded: only ``\sphinxincludegraphics`` + has the custom code to fit image to available width if oversized. + +Features removed +---------------- + +* Configuration variables + + - epub3_contributor + - epub3_description + - epub3_page_progression_direction + - html_translator_class + - html_use_modindex + - latex_font_size + - latex_paper_size + - latex_preamble + - latex_use_modindex + - latex_use_parts + +* ``termsep`` node +* defindex.html template +* LDML format support in `today`, `today_fmt` and `html_last_updated_fmt` +* ``:inline:`` option for the directives of sphinx.ext.graphviz extension +* sphinx.ext.pngmath extension + +Features added +-------------- + +* #3136: Add ``:name:`` option to the directives in ``sphinx.ext.graphviz`` +* #2336: Add ``imported_members`` option to ``sphinx-autogen`` command to document + imported members. + +Bugs fixed +---------- + +Deprecated +---------- + +* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead + ``docutils.parsers.rsr.Directive`` +* ``sphinx.util.compat.docutils_version`` is now deprecated +* #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now + deprecated. Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead. + Release 1.5.2 (in development) =============================== @@ -108,7 +160,7 @@ Incompatible changes * Fix ``genindex.html``, Sphinx's document template, link address to itself to satisfy xhtml standard. * Use epub3 builder by default. And the old epub builder is renamed to epub2. * Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even if ``epub_use_index = False``. -* `html_translator_class` is now deprecated. +* ``html_translator_class`` is now deprecated. Use `Sphinx.set_translator()` API instead. * Drop python 2.6 and 3.3 support * Drop epub3 builder's ``epub3_page_progression_direction`` option (use ``epub3_writing_mode``). @@ -277,7 +329,7 @@ Bugs fixed * `sphinx.ext.autodoc` crashes if target code imports * from mock modules by `autodoc_mock_imports`. * #1953: ``Sphinx.add_node`` does not add handlers the translator installed by - `html_translator_class` + ``html_translator_class`` * #1797: text builder inserts blank line on top * #2894: quickstart main() doesn't use argv argument * #2874: gettext builder could not extract all text under the ``only`` @@ -684,7 +736,8 @@ Incompatible changes ``"MMMM dd, YYYY"`` is default format for `today_fmt` and `html_last_updated_fmt`. However strftime format like ``"%B %d, %Y"`` is also supported for backward compatibility until Sphinx-1.5. Later format will be disabled from Sphinx-1.5. -* #2327: `latex_use_parts` is deprecated now. Use `latex_toplevel_sectioning` instead. +* #2327: ``latex_use_parts`` is deprecated now. Use `latex_toplevel_sectioning` + instead. * #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer. * #1498: manpage writer: don't make whole of item in definition list bold if it includes strong node. * #582: Remove hint message from quick search box for html output. @@ -1247,7 +1300,7 @@ Features added for the ids defined on the node. Thanks to Olivier Heurtier. * PR#229: Allow registration of other translators. Thanks to Russell Sim. * Add app.set_translator() API to register or override a Docutils translator - class like `html_translator_class`. + class like ``html_translator_class``. * PR#267, #1134: add 'diff' parameter to literalinclude. Thanks to Richard Wall and WAKAYAMA shirou. * PR#272: Added 'bizstyle' theme. Thanks to Shoji KUMAGAI. @@ -1,6 +1,6 @@ PYTHON ?= python -.PHONY: all style-check clean clean-pyc clean-patchfiles clean-backupfiles \ +.PHONY: all style-check type-check clean clean-pyc clean-patchfiles clean-backupfiles \ clean-generated pylint reindent test covertest build DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \ @@ -30,11 +30,14 @@ DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \ -i sphinx/search/tr.py \ -i .tox -all: clean-pyc clean-backupfiles style-check test +all: clean-pyc clean-backupfiles style-check type-check test style-check: @$(PYTHON) utils/check_sources.py $(DONT_CHECK) . +type-check: + mypy sphinx/ + clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles clean-pyc: diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt index ab54f15b8..f70ae3568 100644 --- a/doc/_static/conf.py.txt +++ b/doc/_static/conf.py.txt @@ -268,11 +268,6 @@ latex_documents = [ # # latex_logo = None -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - # If true, show page references after internal links. # # latex_show_pagerefs = False diff --git a/doc/config.rst b/doc/config.rst index 3a375eeeb..c8a99a5ab 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -379,18 +379,6 @@ Project information %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent format for the selected locale). - .. versionchanged:: 1.4 - - Format specification was changed from strftime to Locale Data Markup - Language. strftime format is also supported for backward compatibility - until Sphinx-1.5. - - .. versionchanged:: 1.4.1 - - Format specification was changed again from Locale Data Markup Language - to strftime. LDML format is also supported for backward compatibility - until Sphinx-1.5. - .. confval:: highlight_language The default language to highlight source code in. The default is @@ -766,19 +754,6 @@ that use Sphinx's HTMLWriter class. The empty string is equivalent to ``'%b %d, %Y'`` (or a locale-dependent equivalent). - .. versionchanged:: 1.4 - - Format specification was changed from strftime to Locale Data Markup - Language. strftime format is also supported for backward compatibility - until Sphinx-1.5. - - .. versionchanged:: 1.4.1 - - Format specification was changed again from Locale Data Markup Language - to strftime. LDML format is also supported for backward compatibility - until Sphinx-1.5. - - .. confval:: html_use_smartypants If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_ @@ -878,13 +853,6 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.0 -.. confval:: html_use_modindex - - If true, add a module index to the HTML documents. Default is ``True``. - - .. deprecated:: 1.0 - Use :confval:`html_domain_indices`. - .. confval:: html_use_index If true, add an index to the HTML documents. Default is ``True``. @@ -947,20 +915,6 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 0.6 -.. confval:: html_translator_class - - A string with the fully-qualified name of a HTML Translator class, that is, a - subclass of Sphinx's :class:`~sphinx.writers.html.HTMLTranslator`, that is - used to translate document trees to HTML. Default is ``None`` (use the - builtin translator). - - .. seealso:: :meth:`~sphinx.application.Sphinx.set_translator` - - .. deprecated:: 1.5 - - Implement your translator as extension and use `Sphinx.set_translator` - instead. - .. confval:: html_show_copyright If true, "(C) Copyright ..." is shown in the HTML footer. Default is @@ -1536,20 +1490,6 @@ the `Dublin Core metadata <http://dublincore.org/>`_. .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode -.. confval:: epub3_page_progression_direction - - The global direction in which the content flows. - Allowed values are ``'ltr'`` (left-to-right), ``'rtl'`` (right-to-left) and - ``'default'``. The default value is ``'ltr'``. - - When the ``'default'`` value is specified, the Author is expressing no - preference and the Reading System may chose the rendering direction. - - .. versionadded:: 1.4 - - .. deprecated:: 1.5 - Use ``epub_writing_mode`` instead. - .. _latex-options: Options for LaTeX output @@ -1621,16 +1561,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.4 -.. confval:: latex_use_parts - - If true, the topmost sectioning unit is parts, else it is chapters. Default: - ``False``. - - .. versionadded:: 0.3 - - .. deprecated:: 1.4 - Use :confval:`latex_toplevel_sectioning`. - .. confval:: latex_appendices A list of document names to append as an appendix to all manuals. @@ -1646,13 +1576,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.0 -.. confval:: latex_use_modindex - - If true, add a module index to LaTeX documents. Default is ``True``. - - .. deprecated:: 1.0 - Use :confval:`latex_domain_indices`. - .. confval:: latex_show_pagerefs If true, add page references after internal references. This is very useful @@ -1903,27 +1826,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionchanged:: 1.2 This overrides the files which is provided from Sphinx such as sphinx.sty. -.. confval:: latex_preamble - - Additional LaTeX markup for the preamble. - - .. deprecated:: 0.5 - Use the ``'preamble'`` key in the :confval:`latex_elements` value. - -.. confval:: latex_paper_size - - The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``. - - .. deprecated:: 0.5 - Use the ``'papersize'`` key in the :confval:`latex_elements` value. - -.. confval:: latex_font_size - - The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``. - - .. deprecated:: 0.5 - Use the ``'pointsize'`` key in the :confval:`latex_elements` value. - .. _text-options: diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 63c959869..50004e575 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -446,6 +446,11 @@ member should be included in the documentation by using the following event: documentation. The member is excluded if a handler returns ``True``. It is included if the handler returns ``False``. + If more than one enabled extension handles the ``autodoc-skip-member`` + event, autodoc will use the first non-``None`` value returned by a handler. + Handlers should return ``None`` to fall back to the skipping behavior of + autodoc and other enabled extensions. + :param app: the Sphinx application object :param what: the type of the object which the docstring belongs to (one of ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 0994c932a..ef0483da7 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -77,20 +77,8 @@ It adds these directives: the graphviz code. .. versionadded:: 1.1 - All three directives support an ``inline`` flag that controls paragraph - breaks in the output. When set, the graph is inserted into the current - paragraph. If the flag is not given, paragraph breaks are introduced before - and after the image (the default). - -.. versionadded:: 1.1 All three directives support a ``caption`` option that can be used to give a - caption to the diagram. Naturally, diagrams marked as "inline" cannot have a - caption. - -.. deprecated:: 1.4 - ``inline`` option is deprecated. - All three directives generate inline node by default. If ``caption`` is given, - these generate block node instead. + caption to the diagram. .. versionchanged:: 1.4 All three directives support a ``graphviz_dot`` option that can be switch the @@ -100,6 +88,9 @@ It adds these directives: All three directives support a ``align`` option to align the graph horizontal. The values "left", "center", "right" are allowed. +.. versionadded:: 1.6 + All three directives support a ``name`` option to set the label to graph. + There are also these new config values: .. confval:: graphviz_dot diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index b3ffb7af0..f6d21c057 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -89,11 +89,6 @@ package. This allows extensions to use custom translator and define custom nodes for the translator (see :meth:`add_node`). - This is a API version of :confval:`html_translator_class` for all other - builders. Note that if :confval:`html_translator_class` is specified and - this API is called for html related builders, API overriding takes - precedence. - .. versionadded:: 1.3 .. method:: Sphinx.add_node(node, **kwds) @@ -420,6 +415,10 @@ The application object also provides support for emitting leveled messages. the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a custom subclass) to do that. +.. deprecated:: 1.6 + + Please use :ref:`logging-api` instead. + .. automethod:: Sphinx.warn .. automethod:: Sphinx.info diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index b27db4b2d..1f3871c21 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -54,3 +54,4 @@ APIs used for writing extensions domainapi parserapi nodes + logging diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst new file mode 100644 index 000000000..60e11469e --- /dev/null +++ b/doc/extdev/logging.rst @@ -0,0 +1,77 @@ +.. _logging-api: + +Logging API +=========== + +.. function:: sphinx.util.logging.getLogger(name) + + Return a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*. + + Example usage:: + + from sphinx.util import logging # Load instead python's logging module + + logger = logging.getLogger(__name__) + logger.info('Hello, this is an extension!') + +.. class:: SphinxLoggerAdapter(logging.LoggerAdapter) + + .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.warning(level, msg, *args, **kwargs) + + Logs a message with specified level on this logger. + Basically, the arguments are same as python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **type**, ***subtype*** + Indicate categories of warning logs. It is used to suppress + warnings by :confval:`suppress_warnings` setting. + + **location** + Indicate where the warning is happened. It is used to show + the path and line number to each log. It allows docname, + tuple of docname and line number and nodes:: + + logger = sphinx.util.logging.getLogger(__name__) + logger.warning('Warning happened!', location='index') + logger.warning('Warning happened!', location=('chapter1/index', 10)) + logger.warning('Warning happened!', location=some_node) + + **color** + Indicate the color of logs. By default, warning level logs are + colored as ``"darkred"``. The others are not colored. + + .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.info(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.verbose(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs) + + Logs a message with specified level on this logger. + Basically, the arguments are same as python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **nonl** + If true, the logger does not fold lines at end of the log message. + The default is ``False``. + + **color** + Indicate the color of logs. By default, debug level logs are + colored as ``"darkgray"``, and debug2 ones are ``"lightgray"``. + The others are not colored. + +.. function:: pending_logging() + + Make all logs as pending while the context:: + + with pending_logging(): + logger.warning('Warning message!') # not flushed yet + some_long_process() + + # the warning is flushed here + +.. function:: pending_warnings() + + Make warning logs as pending while the context. Similar to :func:`pending_logging`. diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst index 359410e25..5d8272eae 100644 --- a/doc/extdev/nodes.rst +++ b/doc/extdev/nodes.rst @@ -55,4 +55,3 @@ You should not need to generate the nodes below in extensions. .. autoclass:: start_of_file .. autoclass:: productionlist .. autoclass:: production -.. autoclass:: termsep diff --git a/doc/faq.rst b/doc/faq.rst index eaa663d92..5924f5f68 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -201,7 +201,7 @@ The following list gives some hints for the creation of epub files: Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) Error(prcgen):E24001: The table of content could not be built. -.. _Epubcheck: https://code.google.com/archive/p/epubcheck +.. _Epubcheck: https://github.com/IDPF/epubcheck .. _Calibre: http://calibre-ebook.com/ .. _FBreader: https://fbreader.org/ .. _Bookworm: http://www.oreilly.com/bookworm/index.html diff --git a/doc/invocation.rst b/doc/invocation.rst index d65fa27c4..783e1fe6d 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -404,7 +404,7 @@ variables to customize behavior: .. describe:: PAPER - The value for :confval:`latex_paper_size`. + The value for '"papersize"` key of :confval:`latex_elements`. .. describe:: SPHINXBUILD diff --git a/mypy.ini b/mypy.ini new file mode 100644 index 000000000..17ded7ab8 --- /dev/null +++ b/mypy.ini @@ -0,0 +1,6 @@ +[mypy] +python_version = 2.7 +silent_imports = True +fast_parser = True +incremental = True +check_untyped_defs = True @@ -51,6 +51,7 @@ requires = [ 'alabaster>=0.7,<0.8', 'imagesize', 'requests>=2.4.0', + 'typing', ] extras_require = { # Environment Marker works for wheel 0.24 or later diff --git a/sphinx/__init__.py b/sphinx/__init__.py index e5768dcbe..ad9493ecd 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -30,19 +30,19 @@ if 'PYTHONWARNINGS' not in os.environ: warnings.filterwarnings('ignore', "'U' mode is deprecated", DeprecationWarning, module='docutils.io') -__version__ = '1.5.2+' -__released__ = '1.5.2' # used when Sphinx builds its own docs +__version__ = '1.6' +__released__ = '1.6+' # used when Sphinx builds its own docs # version info for better programmatic use # possible values for 3rd element: 'alpha', 'beta', 'rc', 'final' # 'final' has 0 as the last element -version_info = (1, 5, 2, 'beta', 1) +version_info = (1, 6, 0, 'beta', 1) package_dir = path.abspath(path.dirname(__file__)) __display_version__ = __version__ # used for command line version if __version__.endswith('+'): - # try to find out the changeset hash if checked out from hg, and append + # try to find out the commit hash if checked out from git, and append # it to __version__ (since we use this value from setup.py, it gets # automatically propagated to an installed copy as well) __display_version__ = __version__ @@ -54,7 +54,7 @@ if __version__.endswith('+'): stdout=subprocess.PIPE, stderr=subprocess.PIPE) out, err = p.communicate() if out: - __display_version__ += '/' + out.decode().strip() + __display_version__ += '/' + out.decode().strip() # type: ignore except Exception: pass @@ -99,8 +99,8 @@ def build_main(argv=sys.argv): return 1 raise - from sphinx.util.compat import docutils_version - if docutils_version < (0, 10): + import sphinx.util.docutils + if sphinx.util.docutils.__version_info__ < (0, 10): sys.stderr.write('Error: Sphinx requires at least Docutils 0.10 to ' 'run.\n') return 1 diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index b85637c87..c410cb9b7 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -9,10 +9,7 @@ :license: BSD, see LICENSE for details. """ -import warnings - from docutils import nodes -from sphinx.deprecation import RemovedInSphinx16Warning class translatable(object): @@ -273,19 +270,6 @@ class abbreviation(nodes.Inline, nodes.TextElement): """Node for abbreviations with explanations.""" -class termsep(nodes.Structural, nodes.Element): - """Separates two terms within a <term> node. - - .. versionchanged:: 1.4 - sphinx.addnodes.termsep is deprecated. It will be removed at Sphinx-1.6. - """ - - def __init__(self, *args, **kw): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6', - RemovedInSphinx16Warning, stacklevel=2) - super(termsep, self).__init__(*args, **kw) - - class manpage(nodes.Inline, nodes.TextElement): """Node for references to manpages.""" diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index d4793ff4d..e48a527a5 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -26,6 +26,10 @@ from fnmatch import fnmatch from sphinx.util.osutil import FileAvoidWrite, walk from sphinx import __display_version__ +if False: + # For type annotation + from typing import Any, Tuple # NOQA + # automodule options if 'SPHINX_APIDOC_OPTIONS' in os.environ: OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',') @@ -42,6 +46,7 @@ PY_SUFFIXES = set(['.py', '.pyx']) def makename(package, module): + # type: (unicode, unicode) -> unicode """Join package and module with a dot.""" # Both package and module can be None/empty. if package: @@ -54,6 +59,7 @@ def makename(package, module): def write_file(name, text, opts): + # type: (unicode, unicode, Any) -> None """Write the output file for module/package <name>.""" fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix)) if opts.dryrun: @@ -68,12 +74,14 @@ def write_file(name, text, opts): def format_heading(level, text): + # type: (int, unicode) -> unicode """Create a heading of <level> [1, 2 or 3 supported].""" underlining = ['=', '-', '~', ][level - 1] * len(text) return '%s\n%s\n\n' % (text, underlining) def format_directive(module, package=None): + # type: (unicode, unicode) -> unicode """Create the automodule directive and add the options.""" directive = '.. automodule:: %s\n' % makename(package, module) for option in OPTIONS: @@ -82,6 +90,7 @@ def format_directive(module, package=None): def create_module_file(package, module, opts): + # type: (unicode, unicode, Any) -> None """Build the text of the file and write the file.""" if not opts.noheadings: text = format_heading(1, '%s module' % module) @@ -93,6 +102,7 @@ def create_module_file(package, module, opts): def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace): + # type: (unicode, unicode, unicode, List[unicode], Any, List[unicode], bool) -> None """Build the text of the file and write the file.""" text = format_heading(1, ('%s package' if not is_namespace else "%s namespace") % makename(master_package, subroot)) @@ -148,13 +158,14 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_ def create_modules_toc_file(modules, opts, name='modules'): + # type: (List[unicode], Any, unicode) -> None """Create the module's index.""" text = format_heading(1, '%s' % opts.header) text += '.. toctree::\n' text += ' :maxdepth: %s\n\n' % opts.maxdepth modules.sort() - prev_module = '' + prev_module = '' # type: unicode for module in modules: # look if the module is a subpackage and, if yes, ignore it if module.startswith(prev_module + '.'): @@ -166,6 +177,7 @@ def create_modules_toc_file(modules, opts, name='modules'): def shall_skip(module, opts): + # type: (unicode, Any) -> bool """Check if we want to skip this module.""" # skip if the file doesn't exist and not using implicit namespaces if not opts.implicit_namespaces and not path.exists(module): @@ -184,6 +196,7 @@ def shall_skip(module, opts): def recurse_tree(rootpath, excludes, opts): + # type: (unicode, List[unicode], Any) -> List[unicode] """ Look for every file in the directory tree and create the corresponding ReST files. @@ -217,7 +230,7 @@ def recurse_tree(rootpath, excludes, opts): # remove hidden ('.') and private ('_') directories, as well as # excluded dirs if includeprivate: - exclude_prefixes = ('.',) + exclude_prefixes = ('.',) # type: Tuple[unicode, ...] else: exclude_prefixes = ('.', '_') subs[:] = sorted(sub for sub in subs if not sub.startswith(exclude_prefixes) and @@ -247,23 +260,26 @@ def recurse_tree(rootpath, excludes, opts): def normalize_excludes(rootpath, excludes): + # type: (unicode, List[unicode]) -> List[unicode] """Normalize the excluded directory list.""" return [path.abspath(exclude) for exclude in excludes] def is_excluded(root, excludes): + # type: (unicode, List[unicode]) -> bool """Check if the directory is in the exclude list. Note: by having trailing slashes, we avoid common prefix issues, like e.g. an exlude "foo" also accidentally excluding "foobar". """ for exclude in excludes: - if fnmatch(root, exclude): + if fnmatch(root, exclude): # type: ignore return True return False def main(argv=sys.argv): + # type: (List[str]) -> int """Parse and check the command line arguments.""" parser = optparse.OptionParser( usage="""\ @@ -359,7 +375,7 @@ Note: By default this script will not overwrite already created files.""") if opts.full: from sphinx import quickstart as qs modules.sort() - prev_module = '' + prev_module = '' # type: unicode text = '' for module in modules: if module.startswith(prev_module + '.'): diff --git a/sphinx/application.py b/sphinx/application.py index f3bc381bc..168e48983 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -15,6 +15,7 @@ from __future__ import print_function import os import sys import types +import warnings import posixpath import traceback from os import path @@ -22,29 +23,40 @@ from collections import deque from six import iteritems, itervalues, text_type from six.moves import cStringIO + from docutils import nodes from docutils.parsers.rst import convert_directive_function, \ directives, roles import sphinx from sphinx import package_dir, locale -from sphinx.roles import XRefRole from sphinx.config import Config -from sphinx.errors import SphinxError, SphinxWarning, ExtensionError, \ - VersionRequirementError, ConfigError +from sphinx.errors import SphinxError, ExtensionError, VersionRequirementError, \ + ConfigError from sphinx.domains import ObjType from sphinx.domains.std import GenericObject, Target, StandardDomain +from sphinx.deprecation import RemovedInSphinx17Warning, RemovedInSphinx20Warning from sphinx.environment import BuildEnvironment from sphinx.io import SphinxStandaloneReader +from sphinx.roles import XRefRole from sphinx.util import pycompat # noqa: F401 from sphinx.util import import_object +from sphinx.util import logging from sphinx.util.tags import Tags from sphinx.util.osutil import ENOENT -from sphinx.util.logging import is_suppressed_warning -from sphinx.util.console import bold, lightgray, darkgray, darkred, darkgreen, \ - term_width_line +from sphinx.util.console import ( # type: ignore + bold, darkgreen, term_width_line +) from sphinx.util.i18n import find_catalog_source_files +if False: + # For type annotation + from typing import Any, Callable, IO, Iterable, Iterator, Tuple, Type, Union # NOQA + from docutils.parsers import Parser # NOQA + from docutils.transform import Transform # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.domains import Domain, Index # NOQA + # List of all known core events. Maps name to arguments description. events = { 'builder-inited': '', @@ -60,7 +72,7 @@ events = { 'html-collect-pages': 'builder', 'html-page-context': 'pagename, context, doctree or None', 'build-finished': 'exception', -} +} # type: Dict[unicode, unicode] builtin_extensions = ( 'sphinx.builders.applehelp', 'sphinx.builders.changes', @@ -90,14 +102,16 @@ builtin_extensions = ( 'sphinx.directives.other', 'sphinx.directives.patches', 'sphinx.roles', -) +) # type: Tuple[unicode, ...] CONFIG_FILENAME = 'conf.py' ENV_PICKLE_FILENAME = 'environment.pickle' # list of deprecated extensions. Keys are extension name. # Values are Sphinx version that merge the extension. -EXTENSION_BLACKLIST = {"sphinxjp.themecore": "1.2"} +EXTENSION_BLACKLIST = {"sphinxjp.themecore": "1.2"} # type: Dict[unicode, unicode] + +logger = logging.getLogger(__name__) class Sphinx(object): @@ -106,19 +120,20 @@ class Sphinx(object): confoverrides=None, status=sys.stdout, warning=sys.stderr, freshenv=False, warningiserror=False, tags=None, verbosity=0, parallel=0): + # type: (unicode, unicode, unicode, unicode, unicode, Dict, IO, IO, bool, bool, unicode, int, int) -> None # NOQA self.verbosity = verbosity self.next_listener_id = 0 - self._extensions = {} - self._extension_metadata = {} - self._additional_source_parsers = {} - self._listeners = {} - self._setting_up_extension = ['?'] - self.domains = {} + self._extensions = {} # type: Dict[unicode, Any] + self._extension_metadata = {} # type: Dict[unicode, Dict[unicode, Any]] + self._additional_source_parsers = {} # type: Dict[unicode, Parser] + self._listeners = {} # type: Dict[unicode, Dict[int, Callable]] + self._setting_up_extension = ['?'] # type: List[unicode] + self.domains = {} # type: Dict[unicode, Type[Domain]] self.buildername = buildername - self.builderclasses = {} - self.builder = None - self.env = None - self.enumerable_nodes = {} + self.builderclasses = {} # type: Dict[unicode, Type[Builder]] + self.builder = None # type: Builder + self.env = None # type: BuildEnvironment + self.enumerable_nodes = {} # type: Dict[nodes.Node, Tuple[unicode, Callable]] # NOQA self.srcdir = srcdir self.confdir = confdir @@ -128,44 +143,45 @@ class Sphinx(object): self.parallel = parallel if status is None: - self._status = cStringIO() + self._status = cStringIO() # type: IO self.quiet = True else: self._status = status self.quiet = False if warning is None: - self._warning = cStringIO() + self._warning = cStringIO() # type: IO else: self._warning = warning self._warncount = 0 self.warningiserror = warningiserror + logging.setup(self, self._status, self._warning) self._events = events.copy() - self._translators = {} + self._translators = {} # type: Dict[unicode, nodes.GenericNodeVisitor] # keep last few messages for traceback - self.messagelog = deque(maxlen=10) + self.messagelog = deque(maxlen=10) # type: deque # say hello to the world - self.info(bold('Running Sphinx v%s' % sphinx.__display_version__)) + logger.info(bold('Running Sphinx v%s' % sphinx.__display_version__)) # status code for command-line application self.statuscode = 0 if not path.isdir(outdir): - self.info('making output directory...') + logger.info('making output directory...') os.makedirs(outdir) # read config self.tags = Tags(tags) self.config = Config(confdir, CONFIG_FILENAME, confoverrides or {}, self.tags) - self.config.check_unicode(self.warn) + self.config.check_unicode() # defer checking types until i18n has been initialized # initialize some limited config variables before loading extensions - self.config.pre_init_values(self.warn) + self.config.pre_init_values() # check the Sphinx version if requested if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__: @@ -173,12 +189,6 @@ class Sphinx(object): 'This project needs at least Sphinx v%s and therefore cannot ' 'be built with this version.' % self.config.needs_sphinx) - # force preload html_translator_class - if self.config.html_translator_class: - translator_class = self.import_object(self.config.html_translator_class, - 'html_translator_class setting') - self.set_translator('html', translator_class) - # set confdir to srcdir if -C given (!= no confdir); a few pieces # of code expect a confdir to be set if self.confdir is None: @@ -211,15 +221,15 @@ class Sphinx(object): ) # now that we know all config values, collect them from conf.py - self.config.init_values(self.warn) + self.config.init_values() # check extension versions if requested if self.config.needs_extensions: for extname, needs_ver in self.config.needs_extensions.items(): if extname not in self._extensions: - self.warn('needs_extensions config value specifies a ' - 'version requirement for extension %s, but it is ' - 'not loaded' % extname) + logger.warning('needs_extensions config value specifies a ' + 'version requirement for extension %s, but it is ' + 'not loaded', extname) continue has_ver = self._extension_metadata[extname]['version'] if has_ver == 'unknown version' or needs_ver > has_ver: @@ -230,12 +240,12 @@ class Sphinx(object): # check primary_domain if requested if self.config.primary_domain and self.config.primary_domain not in self.domains: - self.warn('primary_domain %r not found, ignored.' % self.config.primary_domain) + logger.warning('primary_domain %r not found, ignored.', self.config.primary_domain) # set up translation infrastructure self._init_i18n() # check all configuration values for permissible types - self.config.check_types(self.warn) + self.config.check_types() # set up source_parsers self._init_source_parsers() # set up the build environment @@ -246,12 +256,13 @@ class Sphinx(object): self._init_enumerable_nodes() def _init_i18n(self): + # type: () -> None """Load translated strings from the configured localedirs if enabled in the configuration. """ if self.config.language is not None: - self.info(bold('loading translations [%s]... ' % - self.config.language), nonl=True) + logger.info(bold('loading translations [%s]... ' % self.config.language), + nonl=True) user_locale_dirs = [ path.join(self.srcdir, x) for x in self.config.locale_dirs] # compile mo files if sphinx.po file in user locale directories are updated @@ -266,11 +277,12 @@ class Sphinx(object): if self.config.language is not None: if has_translation or self.config.language == 'en': # "en" never needs to be translated - self.info('done') + logger.info('done') else: - self.info('not available for built-in messages') + logger.info('not available for built-in messages') def _init_source_parsers(self): + # type: () -> None for suffix, parser in iteritems(self._additional_source_parsers): if suffix not in self.config.source_suffix: self.config.source_suffix.append(suffix) @@ -278,6 +290,7 @@ class Sphinx(object): self.config.source_parsers[suffix] = parser def _init_env(self, freshenv): + # type: (bool) -> None if freshenv: self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) self.env.set_warnfunc(self.warn) @@ -286,7 +299,7 @@ class Sphinx(object): self.env.domains[domain] = self.domains[domain](self.env) else: try: - self.info(bold('loading pickled environment... '), nonl=True) + logger.info(bold('loading pickled environment... '), nonl=True) self.env = BuildEnvironment.frompickle( self.srcdir, self.config, path.join(self.doctreedir, ENV_PICKLE_FILENAME)) self.env.set_warnfunc(self.warn) @@ -295,15 +308,16 @@ class Sphinx(object): for domain in self.domains.keys(): # this can raise if the data version doesn't fit self.env.domains[domain] = self.domains[domain](self.env) - self.info('done') + logger.info('done') except Exception as err: if isinstance(err, IOError) and err.errno == ENOENT: - self.info('not yet created') + logger.info('not yet created') else: - self.info('failed: %s' % err) + logger.info('failed: %s', err) self._init_env(freshenv=True) def _init_builder(self, buildername): + # type: (unicode) -> None if buildername is None: print('No builder selected, using default: html', file=self._status) buildername = 'html' @@ -315,12 +329,14 @@ class Sphinx(object): self.emit('builder-inited') def _init_enumerable_nodes(self): + # type: () -> None for node, settings in iteritems(self.enumerable_nodes): - self.env.domains['std'].enumerable_nodes[node] = settings + self.env.get_domain('std').enumerable_nodes[node] = settings # type: ignore # ---- main "build" method ------------------------------------------------- def build(self, force_all=False, filenames=None): + # type: (bool, List[unicode]) -> None try: if force_all: self.builder.compile_all_catalogs() @@ -335,11 +351,11 @@ class Sphinx(object): status = (self.statuscode == 0 and 'succeeded' or 'finished with problems') if self._warncount: - self.info(bold('build %s, %s warning%s.' % - (status, self._warncount, - self._warncount != 1 and 's' or ''))) + logger.info(bold('build %s, %s warning%s.' % + (status, self._warncount, + self._warncount != 1 and 's' or ''))) else: - self.info(bold('build %s.' % status)) + logger.info(bold('build %s.' % status)) except Exception as err: # delete the saved env to force a fresh build next time envfile = path.join(self.doctreedir, ENV_PICKLE_FILENAME) @@ -352,23 +368,9 @@ class Sphinx(object): self.builder.cleanup() # ---- logging handling ---------------------------------------------------- - - def _log(self, message, wfile, nonl=False): - try: - wfile.write(message) - except UnicodeEncodeError: - encoding = getattr(wfile, 'encoding', 'ascii') or 'ascii' - # wfile.write accept only str, not bytes.So, we encode and replace - # non-encodable characters, then decode them. - wfile.write(message.encode(encoding, 'replace').decode(encoding)) - if not nonl: - wfile.write('\n') - if hasattr(wfile, 'flush'): - wfile.flush() - self.messagelog.append(message) - - def warn(self, message, location=None, prefix='WARNING: ', - type=None, subtype=None, colorfunc=darkred): + def warn(self, message, location=None, prefix=None, + type=None, subtype=None, colorfunc=None): + # type: (unicode, unicode, unicode, unicode, unicode, Callable) -> None """Emit a warning. If *location* is given, it should either be a tuple of (docname, lineno) @@ -384,76 +386,51 @@ class Sphinx(object): :meth:`.BuildEnvironment.warn` since that will collect all warnings during parsing for later output. """ - if is_suppressed_warning(type, subtype, self.config.suppress_warnings): - return + if prefix: + warnings.warn('prefix option of warn() is now deprecated.', + RemovedInSphinx17Warning) + if colorfunc: + warnings.warn('colorfunc option of warn() is now deprecated.', + RemovedInSphinx17Warning) - if isinstance(location, tuple): - docname, lineno = location - if docname: - location = '%s:%s' % (self.env.doc2path(docname), lineno or '') - else: - location = None - warntext = location and '%s: %s%s\n' % (location, prefix, message) or \ - '%s%s\n' % (prefix, message) - if self.warningiserror: - raise SphinxWarning(warntext) - self._warncount += 1 - self._log(colorfunc(warntext), self._warning, True) + warnings.warn('app.warning() is now deprecated. Use sphinx.util.logging instead.', + RemovedInSphinx20Warning) + logger.warning(message, type=type, subtype=subtype, location=location) def info(self, message='', nonl=False): + # type: (unicode, bool) -> None """Emit an informational message. If *nonl* is true, don't emit a newline at the end (which implies that more info output will follow soon.) """ - self._log(message, self._status, nonl) + warnings.warn('app.info() is now deprecated. Use sphinx.util.logging instead.', + RemovedInSphinx20Warning) + logger.info(message, nonl=nonl) def verbose(self, message, *args, **kwargs): - """Emit a verbose informational message. - - The message will only be emitted for verbosity levels >= 1 (i.e. at - least one ``-v`` option was given). - - The message can contain %-style interpolation placeholders, which is - formatted with either the ``*args`` or ``**kwargs`` when output. - """ - if self.verbosity < 1: - return - if args or kwargs: - message = message % (args or kwargs) - self._log(message, self._status) + # type: (unicode, Any, Any) -> None + """Emit a verbose informational message.""" + warnings.warn('app.verbose() is now deprecated. Use sphinx.util.logging instead.', + RemovedInSphinx20Warning) + logger.verbose(message, *args, **kwargs) def debug(self, message, *args, **kwargs): - """Emit a debug-level informational message. - - The message will only be emitted for verbosity levels >= 2 (i.e. at - least two ``-v`` options were given). - - The message can contain %-style interpolation placeholders, which is - formatted with either the ``*args`` or ``**kwargs`` when output. - """ - if self.verbosity < 2: - return - if args or kwargs: - message = message % (args or kwargs) - self._log(darkgray(message), self._status) + # type: (unicode, Any, Any) -> None + """Emit a debug-level informational message.""" + warnings.warn('app.debug() is now deprecated. Use sphinx.util.logging instead.', + RemovedInSphinx20Warning) + logger.debug(message, *args, **kwargs) def debug2(self, message, *args, **kwargs): - """Emit a lowlevel debug-level informational message. - - The message will only be emitted for verbosity level 3 (i.e. three - ``-v`` options were given). - - The message can contain %-style interpolation placeholders, which is - formatted with either the ``*args`` or ``**kwargs`` when output. - """ - if self.verbosity < 3: - return - if args or kwargs: - message = message % (args or kwargs) - self._log(lightgray(message), self._status) + # type: (unicode, Any, Any) -> None + """Emit a lowlevel debug-level informational message.""" + warnings.warn('app.debug2() is now deprecated. Use debug() instead.', + RemovedInSphinx20Warning) + logger.debug(message, *args, **kwargs) def _display_chunk(chunk): + # type: (Any) -> unicode if isinstance(chunk, (list, tuple)): if len(chunk) == 1: return text_type(chunk[0]) @@ -462,19 +439,21 @@ class Sphinx(object): def old_status_iterator(self, iterable, summary, colorfunc=darkgreen, stringify_func=_display_chunk): + # type: (Iterable, unicode, Callable, Callable[[Any], unicode]) -> Iterator l = 0 for item in iterable: if l == 0: - self.info(bold(summary), nonl=True) + logger.info(bold(summary), nonl=True) l = 1 - self.info(colorfunc(stringify_func(item)) + ' ', nonl=True) + logger.info(colorfunc(stringify_func(item)) + ' ', nonl=True) yield item if l == 1: - self.info() + logger.info('') # new version with progress info def status_iterator(self, iterable, summary, colorfunc=darkgreen, length=0, stringify_func=_display_chunk): + # type: (Iterable, unicode, Callable, int, Callable[[Any], unicode]) -> Iterable if length == 0: for item in self.old_status_iterator(iterable, summary, colorfunc, stringify_func): @@ -490,33 +469,34 @@ class Sphinx(object): s += '\n' else: s = term_width_line(s) - self.info(s, nonl=True) + logger.info(s, nonl=True) yield item if l > 0: - self.info() + logger.info('') # ---- general extensibility interface ------------------------------------- def setup_extension(self, extension): + # type: (unicode) -> None """Import and setup a Sphinx extension module. No-op if called twice.""" - self.debug('[app] setting up extension: %r', extension) + logger.debug('[app] setting up extension: %r', extension) if extension in self._extensions: return if extension in EXTENSION_BLACKLIST: - self.warn('the extension %r was already merged with Sphinx since version %s; ' - 'this extension is ignored.' % ( - extension, EXTENSION_BLACKLIST[extension])) + logger.warning('the extension %r was already merged with Sphinx since version %s; ' + 'this extension is ignored.', + extension, EXTENSION_BLACKLIST[extension]) return self._setting_up_extension.append(extension) try: mod = __import__(extension, None, None, ['setup']) except ImportError as err: - self.verbose('Original exception:\n' + traceback.format_exc()) + logger.verbose('Original exception:\n' + traceback.format_exc()) raise ExtensionError('Could not import extension %s' % extension, err) if not hasattr(mod, 'setup'): - self.warn('extension %r has no setup() function; is it really ' - 'a Sphinx extension module?' % extension) + logger.warning('extension %r has no setup() function; is it really ' + 'a Sphinx extension module?', extension) ext_meta = None else: try: @@ -536,30 +516,34 @@ class Sphinx(object): if not ext_meta.get('version'): ext_meta['version'] = 'unknown version' except Exception: - self.warn('extension %r returned an unsupported object from ' - 'its setup() function; it should return None or a ' - 'metadata dictionary' % extension) + logger.warning('extension %r returned an unsupported object from ' + 'its setup() function; it should return None or a ' + 'metadata dictionary', extension) ext_meta = {'version': 'unknown version'} self._extensions[extension] = mod self._extension_metadata[extension] = ext_meta self._setting_up_extension.pop() def require_sphinx(self, version): + # type: (unicode) -> None # check the Sphinx version if requested if version > sphinx.__display_version__[:3]: raise VersionRequirementError(version) def import_object(self, objname, source=None): + # type: (str, unicode) -> Any """Import an object from a 'module.name' string.""" return import_object(objname, source=None) # event interface def _validate_event(self, event): + # type: (unicode) -> None if event not in self._events: raise ExtensionError('Unknown event name: %s' % event) def connect(self, event, callback): + # type: (unicode, Callable) -> int self._validate_event(event) listener_id = self.next_listener_id if event not in self._listeners: @@ -567,18 +551,20 @@ class Sphinx(object): else: self._listeners[event][listener_id] = callback self.next_listener_id += 1 - self.debug('[app] connecting event %r: %r [id=%s]', - event, callback, listener_id) + logger.debug('[app] connecting event %r: %r [id=%s]', + event, callback, listener_id) return listener_id def disconnect(self, listener_id): - self.debug('[app] disconnecting event: [id=%s]', listener_id) + # type: (int) -> None + logger.debug('[app] disconnecting event: [id=%s]', listener_id) for event in itervalues(self._listeners): event.pop(listener_id, None) def emit(self, event, *args): + # type: (unicode, Any) -> List try: - self.debug2('[app] emitting event: %r%s', event, repr(args)[:100]) + logger.debug('[app] emitting event: %r%s', event, repr(args)[:100]) except Exception: # not every object likes to be repr()'d (think # random stuff coming via autodoc) @@ -590,6 +576,7 @@ class Sphinx(object): return results def emit_firstresult(self, event, *args): + # type: (unicode, Any) -> Any for result in self.emit(event, *args): if result is not None: return result @@ -598,7 +585,8 @@ class Sphinx(object): # registering addon parts def add_builder(self, builder): - self.debug('[app] adding builder: %r', builder) + # type: (Type[Builder]) -> None + logger.debug('[app] adding builder: %r', builder) if not hasattr(builder, 'name'): raise ExtensionError('Builder class %s has no "name" attribute' % builder) @@ -609,8 +597,9 @@ class Sphinx(object): self.builderclasses[builder.name] = builder def add_config_value(self, name, default, rebuild, types=()): - self.debug('[app] adding config value: %r', - (name, default, rebuild) + ((types,) if types else ())) + # type: (unicode, Any, Union[bool, unicode], Any) -> None + logger.debug('[app] adding config value: %r', + (name, default, rebuild) + ((types,) if types else ())) # type: ignore if name in self.config.values: raise ExtensionError('Config value %r already present' % name) if rebuild in (False, True): @@ -618,23 +607,26 @@ class Sphinx(object): self.config.values[name] = (default, rebuild, types) def add_event(self, name): - self.debug('[app] adding event: %r', name) + # type: (unicode) -> None + logger.debug('[app] adding event: %r', name) if name in self._events: raise ExtensionError('Event %r already present' % name) self._events[name] = '' def set_translator(self, name, translator_class): - self.info(bold('A Translator for the %s builder is changed.' % name)) + # type: (unicode, Any) -> None + logger.info(bold('A Translator for the %s builder is changed.' % name)) self._translators[name] = translator_class def add_node(self, node, **kwds): - self.debug('[app] adding node: %r', (node, kwds)) + # type: (nodes.Node, Any) -> None + logger.debug('[app] adding node: %r', (node, kwds)) if not kwds.pop('override', False) and \ hasattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__): - self.warn('while setting up extension %s: node class %r is ' - 'already registered, its visitors will be overridden' % - (self._setting_up_extension, node.__name__), - type='app', subtype='add_node') + logger.warning('while setting up extension %s: node class %r is ' + 'already registered, its visitors will be overridden', + self._setting_up_extension, node.__name__, + type='app', subtype='add_node') nodes._add_node_class_names([node.__name__]) for key, val in iteritems(kwds): try: @@ -646,17 +638,15 @@ class Sphinx(object): if translator is not None: pass elif key == 'html': - from sphinx.writers.html import HTMLTranslator as translator + from sphinx.writers.html import HTMLTranslator as translator # type: ignore elif key == 'latex': - from sphinx.writers.latex import LaTeXTranslator as translator + from sphinx.writers.latex import LaTeXTranslator as translator # type: ignore elif key == 'text': - from sphinx.writers.text import TextTranslator as translator + from sphinx.writers.text import TextTranslator as translator # type: ignore elif key == 'man': - from sphinx.writers.manpage import ManualPageTranslator \ - as translator + from sphinx.writers.manpage import ManualPageTranslator as translator # type: ignore # NOQA elif key == 'texinfo': - from sphinx.writers.texinfo import TexinfoTranslator \ - as translator + from sphinx.writers.texinfo import TexinfoTranslator as translator # type: ignore # NOQA else: # ignore invalid keys for compatibility continue @@ -665,14 +655,16 @@ class Sphinx(object): setattr(translator, 'depart_'+node.__name__, depart) def add_enumerable_node(self, node, figtype, title_getter=None, **kwds): + # type: (nodes.Node, unicode, Callable, Any) -> None self.enumerable_nodes[node] = (figtype, title_getter) self.add_node(node, **kwds) def _directive_helper(self, obj, content=None, arguments=None, **options): + # type: (Any, unicode, Any, Any) -> Any if isinstance(obj, (types.FunctionType, types.MethodType)): - obj.content = content - obj.arguments = arguments or (0, 0, False) - obj.options = options + obj.content = content # type: ignore + obj.arguments = arguments or (0, 0, False) # type: ignore + obj.options = options # type: ignore return convert_directive_function(obj) else: if content or arguments or options: @@ -681,45 +673,50 @@ class Sphinx(object): return obj def add_directive(self, name, obj, content=None, arguments=None, **options): - self.debug('[app] adding directive: %r', - (name, obj, content, arguments, options)) + # type: (unicode, Any, unicode, Any, Any) -> None + logger.debug('[app] adding directive: %r', + (name, obj, content, arguments, options)) if name in directives._directives: - self.warn('while setting up extension %s: directive %r is ' - 'already registered, it will be overridden' % - (self._setting_up_extension[-1], name), - type='app', subtype='add_directive') + logger.warning('while setting up extension %s: directive %r is ' + 'already registered, it will be overridden', + self._setting_up_extension[-1], name, + type='app', subtype='add_directive') directives.register_directive( name, self._directive_helper(obj, content, arguments, **options)) def add_role(self, name, role): - self.debug('[app] adding role: %r', (name, role)) + # type: (unicode, Any) -> None + logger.debug('[app] adding role: %r', (name, role)) if name in roles._roles: - self.warn('while setting up extension %s: role %r is ' - 'already registered, it will be overridden' % - (self._setting_up_extension[-1], name), - type='app', subtype='add_role') + logger.warning('while setting up extension %s: role %r is ' + 'already registered, it will be overridden', + self._setting_up_extension[-1], name, + type='app', subtype='add_role') roles.register_local_role(name, role) def add_generic_role(self, name, nodeclass): + # type: (unicode, Any) -> None # don't use roles.register_generic_role because it uses # register_canonical_role - self.debug('[app] adding generic role: %r', (name, nodeclass)) + logger.debug('[app] adding generic role: %r', (name, nodeclass)) if name in roles._roles: - self.warn('while setting up extension %s: role %r is ' - 'already registered, it will be overridden' % - (self._setting_up_extension[-1], name), - type='app', subtype='add_generic_role') + logger.warning('while setting up extension %s: role %r is ' + 'already registered, it will be overridden', + self._setting_up_extension[-1], name, + type='app', subtype='add_generic_role') role = roles.GenericRole(name, nodeclass) roles.register_local_role(name, role) def add_domain(self, domain): - self.debug('[app] adding domain: %r', domain) + # type: (Type[Domain]) -> None + logger.debug('[app] adding domain: %r', domain) if domain.name in self.domains: raise ExtensionError('domain %s already registered' % domain.name) self.domains[domain.name] = domain def override_domain(self, domain): - self.debug('[app] overriding domain: %r', domain) + # type: (Type[Domain]) -> None + logger.debug('[app] overriding domain: %r', domain) if domain.name not in self.domains: raise ExtensionError('domain %s not yet registered' % domain.name) if not issubclass(domain, self.domains[domain.name]): @@ -729,21 +726,24 @@ class Sphinx(object): def add_directive_to_domain(self, domain, name, obj, content=None, arguments=None, **options): - self.debug('[app] adding directive to domain: %r', - (domain, name, obj, content, arguments, options)) + # type: (unicode, unicode, Any, unicode, Any, Any) -> None + logger.debug('[app] adding directive to domain: %r', + (domain, name, obj, content, arguments, options)) if domain not in self.domains: raise ExtensionError('domain %s not yet registered' % domain) self.domains[domain].directives[name] = \ self._directive_helper(obj, content, arguments, **options) def add_role_to_domain(self, domain, name, role): - self.debug('[app] adding role to domain: %r', (domain, name, role)) + # type: (unicode, unicode, Any) -> None + logger.debug('[app] adding role to domain: %r', (domain, name, role)) if domain not in self.domains: raise ExtensionError('domain %s not yet registered' % domain) self.domains[domain].roles[name] = role def add_index_to_domain(self, domain, index): - self.debug('[app] adding index to domain: %r', (domain, index)) + # type: (unicode, Type[Index]) -> None + logger.debug('[app] adding index to domain: %r', (domain, index)) if domain not in self.domains: raise ExtensionError('domain %s not yet registered' % domain) self.domains[domain].indices.append(index) @@ -751,15 +751,16 @@ class Sphinx(object): def add_object_type(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[]): - self.debug('[app] adding object type: %r', - (directivename, rolename, indextemplate, parse_node, - ref_nodeclass, objname, doc_field_types)) + # type: (unicode, unicode, unicode, Callable, nodes.Node, unicode, List) -> None + logger.debug('[app] adding object type: %r', + (directivename, rolename, indextemplate, parse_node, + ref_nodeclass, objname, doc_field_types)) StandardDomain.object_types[directivename] = \ ObjType(objname or directivename, rolename) # create a subclass of GenericObject as the new directive - new_directive = type(directivename, (GenericObject, object), + new_directive = type(directivename, (GenericObject, object), # type: ignore {'indextemplate': indextemplate, - 'parse_node': staticmethod(parse_node), + 'parse_node': staticmethod(parse_node), # type: ignore 'doc_field_types': doc_field_types}) StandardDomain.directives[directivename] = new_directive # XXX support more options? @@ -770,24 +771,27 @@ class Sphinx(object): def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None, objname=''): - self.debug('[app] adding crossref type: %r', - (directivename, rolename, indextemplate, ref_nodeclass, - objname)) + # type: (unicode, unicode, unicode, nodes.Node, unicode) -> None + logger.debug('[app] adding crossref type: %r', + (directivename, rolename, indextemplate, ref_nodeclass, + objname)) StandardDomain.object_types[directivename] = \ ObjType(objname or directivename, rolename) # create a subclass of Target as the new directive - new_directive = type(directivename, (Target, object), + new_directive = type(directivename, (Target, object), # type: ignore {'indextemplate': indextemplate}) StandardDomain.directives[directivename] = new_directive # XXX support more options? StandardDomain.roles[rolename] = XRefRole(innernodeclass=ref_nodeclass) def add_transform(self, transform): - self.debug('[app] adding transform: %r', transform) + # type: (Transform) -> None + logger.debug('[app] adding transform: %r', transform) SphinxStandaloneReader.transforms.append(transform) def add_javascript(self, filename): - self.debug('[app] adding javascript: %r', filename) + # type: (unicode) -> None + logger.debug('[app] adding javascript: %r', filename) from sphinx.builders.html import StandaloneHTMLBuilder if '://' in filename: StandaloneHTMLBuilder.script_files.append(filename) @@ -796,7 +800,8 @@ class Sphinx(object): posixpath.join('_static', filename)) def add_stylesheet(self, filename): - self.debug('[app] adding stylesheet: %r', filename) + # type: (unicode) -> None + logger.debug('[app] adding stylesheet: %r', filename) from sphinx.builders.html import StandaloneHTMLBuilder if '://' in filename: StandaloneHTMLBuilder.css_files.append(filename) @@ -805,41 +810,47 @@ class Sphinx(object): posixpath.join('_static', filename)) def add_latex_package(self, packagename, options=None): - self.debug('[app] adding latex package: %r', packagename) + # type: (unicode, unicode) -> None + logger.debug('[app] adding latex package: %r', packagename) if hasattr(self.builder, 'usepackages'): # only for LaTeX builder self.builder.usepackages.append((packagename, options)) def add_lexer(self, alias, lexer): - self.debug('[app] adding lexer: %r', (alias, lexer)) + # type: (unicode, Any) -> None + logger.debug('[app] adding lexer: %r', (alias, lexer)) from sphinx.highlighting import lexers if lexers is None: return lexers[alias] = lexer def add_autodocumenter(self, cls): - self.debug('[app] adding autodocumenter: %r', cls) + # type: (Any) -> None + logger.debug('[app] adding autodocumenter: %r', cls) from sphinx.ext import autodoc autodoc.add_documenter(cls) self.add_directive('auto' + cls.objtype, autodoc.AutoDirective) def add_autodoc_attrgetter(self, type, getter): - self.debug('[app] adding autodoc attrgetter: %r', (type, getter)) + # type: (Any, Callable) -> None + logger.debug('[app] adding autodoc attrgetter: %r', (type, getter)) from sphinx.ext import autodoc autodoc.AutoDirective._special_attrgetters[type] = getter def add_search_language(self, cls): - self.debug('[app] adding search language: %r', cls) + # type: (Any) -> None + logger.debug('[app] adding search language: %r', cls) from sphinx.search import languages, SearchLanguage assert issubclass(cls, SearchLanguage) languages[cls.lang] = cls def add_source_parser(self, suffix, parser): - self.debug('[app] adding search source_parser: %r, %r', suffix, parser) + # type: (unicode, Parser) -> None + logger.debug('[app] adding search source_parser: %r, %r', suffix, parser) if suffix in self._additional_source_parsers: - self.warn('while setting up extension %s: source_parser for %r is ' - 'already registered, it will be overridden' % - (self._setting_up_extension[-1], suffix), - type='app', subtype='add_source_parser') + logger.warning('while setting up extension %s: source_parser for %r is ' + 'already registered, it will be overridden', + self._setting_up_extension[-1], suffix, + type='app', subtype='add_source_parser') self._additional_source_parsers[suffix] = parser @@ -850,6 +861,7 @@ class TemplateBridge(object): """ def init(self, builder, theme=None, dirs=None): + # type: (Builder, unicode, List[unicode]) -> None """Called by the builder to initialize the template system. *builder* is the builder object; you'll probably want to look at the @@ -861,6 +873,7 @@ class TemplateBridge(object): raise NotImplementedError('must be implemented in subclasses') def newest_template_mtime(self): + # type: () -> float """Called by the builder to determine if output files are outdated because of template changes. Return the mtime of the newest template file that was changed. The default implementation returns ``0``. @@ -868,12 +881,14 @@ class TemplateBridge(object): return 0 def render(self, template, context): + # type: (unicode, Dict) -> None """Called by the builder to render a template given as a filename with a specified context (a Python dictionary). """ raise NotImplementedError('must be implemented in subclasses') def render_string(self, template, context): + # type: (unicode, Dict) -> unicode """Called by the builder to render a template given as a string with a specified context (a Python dictionary). """ diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index fe0c9c665..191646a94 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -19,10 +19,10 @@ except ImportError: from docutils import nodes -from sphinx.util import i18n, path_stabilize +from sphinx.util import i18n, path_stabilize, logging from sphinx.util.osutil import SEP, relative_uri from sphinx.util.i18n import find_catalog -from sphinx.util.console import bold, darkgreen +from sphinx.util.console import bold, darkgreen # type: ignore from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \ parallel_available @@ -30,6 +30,18 @@ from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \ from sphinx import roles # noqa from sphinx import directives # noqa +if False: + # For type annotation + from typing import Any, Callable, Iterable, Sequence, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.config import Config # NOQA + from sphinx.environment import BuildEnvironment # NOQA + from sphinx.util.i18n import CatalogInfo # NOQA + from sphinx.util.tags import Tags # NOQA + + +logger = logging.getLogger(__name__) + class Builder(object): """ @@ -47,7 +59,8 @@ class Builder(object): allow_parallel = False def __init__(self, app): - self.env = app.env + # type: (Sphinx) -> None + self.env = app.env # type: BuildEnvironment self.env.set_versioning_method(self.versioning_method, self.versioning_compare) self.srcdir = app.srcdir @@ -57,11 +70,11 @@ class Builder(object): if not path.isdir(self.doctreedir): os.makedirs(self.doctreedir) - self.app = app - self.warn = app.warn - self.info = app.info - self.config = app.config - self.tags = app.tags + self.app = app # type: Sphinx + self.warn = app.warn # type: Callable + self.info = app.info # type: Callable + self.config = app.config # type: Config + self.tags = app.tags # type: Tags self.tags.add(self.format) self.tags.add(self.name) self.tags.add("format_%s" % self.format) @@ -71,7 +84,7 @@ class Builder(object): self.old_status_iterator = app.old_status_iterator # images that need to be copied over (source -> dest) - self.images = {} + self.images = {} # type: Dict[unicode, unicode] # basename of images directory self.imagedir = "" # relative path to image directory from current docname (used at writing docs) @@ -79,7 +92,7 @@ class Builder(object): # these get set later self.parallel_ok = False - self.finish_tasks = None + self.finish_tasks = None # type: Any # load default translator class self.translator_class = app._translators.get(self.name) @@ -88,12 +101,14 @@ class Builder(object): # helper methods def init(self): + # type: () -> None """Load necessary templates and perform initialization. The default implementation does nothing. """ pass def create_template_bridge(self): + # type: () -> None """Return the template bridge configured.""" if self.config.template_bridge: self.templates = self.app.import_object( @@ -103,6 +118,7 @@ class Builder(object): self.templates = BuiltinTemplateLoader() def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode """Return the target URI for a document name. *typ* can be used to qualify the link characteristic for individual @@ -111,6 +127,7 @@ class Builder(object): raise NotImplementedError def get_relative_uri(self, from_, to, typ=None): + # type: (unicode, unicode, unicode) -> unicode """Return a relative URI between two source filenames. May raise environment.NoUri if there's no way to return a sensible URI. @@ -119,6 +136,7 @@ class Builder(object): self.get_target_uri(to, typ)) def get_outdated_docs(self): + # type: () -> Union[unicode, Iterable[unicode]] """Return an iterable of output files that are outdated, or a string describing what an update build will build. @@ -128,9 +146,10 @@ class Builder(object): """ raise NotImplementedError - supported_image_types = [] + supported_image_types = [] # type: List[unicode] def post_process_images(self, doctree): + # type: (nodes.Node) -> None """Pick the best candidate for all image URIs.""" for node in doctree.traverse(nodes.image): if '?' in node['candidates']: @@ -142,9 +161,8 @@ class Builder(object): if candidate: break else: - self.warn( - 'no matching candidate for image URI %r' % node['uri'], - '%s:%s' % (node.source, getattr(node, 'line', ''))) + logger.warning('no matching candidate for image URI %r', node['uri'], + location=node) continue node['uri'] = candidate else: @@ -157,19 +175,21 @@ class Builder(object): # compile po methods def compile_catalogs(self, catalogs, message): + # type: (Set[CatalogInfo], unicode) -> None if not self.config.gettext_auto_build: return def cat2relpath(cat): return path.relpath(cat.mo_path, self.env.srcdir).replace(path.sep, SEP) - self.info(bold('building [mo]: ') + message) + logger.info(bold('building [mo]: ') + message) for catalog in self.app.status_iterator( catalogs, 'writing output... ', darkgreen, len(catalogs), cat2relpath): catalog.write_mo(self.config.language) def compile_all_catalogs(self): + # type: () -> None catalogs = i18n.find_catalog_source_files( [path.join(self.srcdir, x) for x in self.config.locale_dirs], self.config.language, @@ -180,6 +200,7 @@ class Builder(object): self.compile_catalogs(catalogs, message) def compile_specific_catalogs(self, specified_files): + # type: (List[unicode]) -> None def to_domain(fpath): docname, _ = path.splitext(path_stabilize(fpath)) dom = find_catalog(docname, self.config.gettext_compact) @@ -196,6 +217,7 @@ class Builder(object): self.compile_catalogs(catalogs, message) def compile_update_catalogs(self): + # type: () -> None catalogs = i18n.find_catalog_source_files( [path.join(self.srcdir, x) for x in self.config.locale_dirs], self.config.language, @@ -207,26 +229,29 @@ class Builder(object): # build methods def build_all(self): + # type: () -> None """Build all source files.""" self.build(None, summary='all source files', method='all') def build_specific(self, filenames): + # type: (List[unicode]) -> None """Only rebuild as much as needed for changes in the *filenames*.""" # bring the filenames to the canonical format, that is, # relative to the source directory and without source_suffix. dirlen = len(self.srcdir) + 1 to_write = [] - suffixes = tuple(self.config.source_suffix) + suffixes = None # type: Tuple[unicode] + suffixes = tuple(self.config.source_suffix) # type: ignore for filename in filenames: filename = path.normpath(path.abspath(filename)) if not filename.startswith(self.srcdir): - self.warn('file %r given on command line is not under the ' - 'source directory, ignoring' % filename) + logger.warning('file %r given on command line is not under the ' + 'source directory, ignoring', filename) continue if not (path.isfile(filename) or any(path.isfile(filename + suffix) for suffix in suffixes)): - self.warn('file %r given on command line does not exist, ' - 'ignoring' % filename) + logger.warning('file %r given on command line does not exist, ' + 'ignoring', filename) continue filename = filename[dirlen:] for suffix in suffixes: @@ -240,6 +265,7 @@ class Builder(object): 'line' % len(to_write)) def build_update(self): + # type: () -> None """Only rebuild what was changed or added since last build.""" to_build = self.get_outdated_docs() if isinstance(to_build, str): @@ -251,46 +277,43 @@ class Builder(object): 'out of date' % len(to_build)) def build(self, docnames, summary=None, method='update'): + # type: (Iterable[unicode], unicode, unicode) -> None """Main build method. First updates the environment, and then calls :meth:`write`. """ if summary: - self.info(bold('building [%s]' % self.name) + ': ' + summary) + logger.info(bold('building [%s]' % self.name) + ': ' + summary) # while reading, collect all warnings from docutils - warnings = [] - self.env.set_warnfunc(lambda *args, **kwargs: warnings.append((args, kwargs))) - updated_docnames = set(self.env.update(self.config, self.srcdir, - self.doctreedir, self.app)) - self.env.set_warnfunc(self.warn) - for warning, kwargs in warnings: - self.warn(*warning, **kwargs) + with logging.pending_warnings(): + updated_docnames = set(self.env.update(self.config, self.srcdir, + self.doctreedir, self.app)) doccount = len(updated_docnames) - self.info(bold('looking for now-outdated files... '), nonl=1) + logger.info(bold('looking for now-outdated files... '), nonl=1) for docname in self.env.check_dependents(updated_docnames): updated_docnames.add(docname) outdated = len(updated_docnames) - doccount if outdated: - self.info('%d found' % outdated) + logger.info('%d found', outdated) else: - self.info('none found') + logger.info('none found') if updated_docnames: # save the environment from sphinx.application import ENV_PICKLE_FILENAME - self.info(bold('pickling environment... '), nonl=True) + logger.info(bold('pickling environment... '), nonl=True) self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.info('done') + logger.info('done') # global actions - self.info(bold('checking consistency... '), nonl=True) + logger.info(bold('checking consistency... '), nonl=True) self.env.check_consistency() - self.info('done') + logger.info('done') else: if method == 'update' and not docnames: - self.info(bold('no targets are out of date.')) + logger.info(bold('no targets are out of date.')) return # filter "docnames" (list of outdated files) by the updated @@ -306,8 +329,8 @@ class Builder(object): for extname, md in self.app._extension_metadata.items(): par_ok = md.get('parallel_write_safe', True) if not par_ok: - self.app.warn('the %s extension is not safe for parallel ' - 'writing, doing serial write' % extname) + logger.warning('the %s extension is not safe for parallel ' + 'writing, doing serial write', extname) self.parallel_ok = False break @@ -328,6 +351,7 @@ class Builder(object): self.finish_tasks.join() def write(self, build_docnames, updated_docnames, method='update'): + # type: (Iterable[unicode], Sequence[unicode], unicode) -> None if build_docnames is None or build_docnames == ['__all__']: # build_all build_docnames = self.env.found_docs @@ -336,55 +360,45 @@ class Builder(object): docnames = set(build_docnames) | set(updated_docnames) else: docnames = set(build_docnames) - self.app.debug('docnames to write: %s', ', '.join(sorted(docnames))) + logger.debug('docnames to write: %s', ', '.join(sorted(docnames))) # add all toctree-containing files that may have changed for docname in list(docnames): - for tocdocname in self.env.files_to_rebuild.get(docname, []): + for tocdocname in self.env.files_to_rebuild.get(docname, set()): if tocdocname in self.env.found_docs: docnames.add(tocdocname) docnames.add(self.config.master_doc) - self.info(bold('preparing documents... '), nonl=True) + logger.info(bold('preparing documents... '), nonl=True) self.prepare_writing(docnames) - self.info('done') + logger.info('done') - warnings = [] - self.env.set_warnfunc(lambda *args, **kwargs: warnings.append((args, kwargs))) if self.parallel_ok: # number of subprocesses is parallel-1 because the main process # is busy loading doctrees and doing write_doc_serialized() - self._write_parallel(sorted(docnames), warnings, + self._write_parallel(sorted(docnames), nproc=self.app.parallel - 1) else: - self._write_serial(sorted(docnames), warnings) - self.env.set_warnfunc(self.warn) - - def _write_serial(self, docnames, warnings): - for docname in self.app.status_iterator( - docnames, 'writing output... ', darkgreen, len(docnames)): - doctree = self.env.get_and_resolve_doctree(docname, self) - self.write_doc_serialized(docname, doctree) - self.write_doc(docname, doctree) - for warning, kwargs in warnings: - self.warn(*warning, **kwargs) - - def _write_parallel(self, docnames, warnings, nproc): - def write_process(docs): - local_warnings = [] + self._write_serial(sorted(docnames)) - def warnfunc(*args, **kwargs): - local_warnings.append((args, kwargs)) - self.env.set_warnfunc(warnfunc) - for docname, doctree in docs: + def _write_serial(self, docnames): + # type: (Sequence[unicode]) -> None + with logging.pending_warnings(): + for docname in self.app.status_iterator( + docnames, 'writing output... ', darkgreen, len(docnames)): + doctree = self.env.get_and_resolve_doctree(docname, self) + self.write_doc_serialized(docname, doctree) self.write_doc(docname, doctree) - return local_warnings - def add_warnings(docs, wlist): - warnings.extend(wlist) + def _write_parallel(self, docnames, nproc): + # type: (Sequence[unicode], int) -> None + def write_process(docs): + # type: (List[Tuple[unicode, nodes.Node]]) -> None + for docname, doctree in docs: + self.write_doc(docname, doctree) # warm up caches/compile templates using the first document - firstname, docnames = docnames[0], docnames[1:] + firstname, docnames = docnames[0], docnames[1:] # type: ignore doctree = self.env.get_and_resolve_doctree(firstname, self) self.write_doc_serialized(firstname, doctree) self.write_doc(firstname, doctree) @@ -399,30 +413,31 @@ class Builder(object): doctree = self.env.get_and_resolve_doctree(docname, self) self.write_doc_serialized(docname, doctree) arg.append((docname, doctree)) - tasks.add_task(write_process, arg, add_warnings) + tasks.add_task(write_process, arg) # make sure all threads have finished - self.info(bold('waiting for workers...')) + logger.info(bold('waiting for workers...')) tasks.join() - for warning, kwargs in warnings: - self.warn(*warning, **kwargs) - def prepare_writing(self, docnames): + # type: (Set[unicode]) -> None """A place where you can add logic before :meth:`write_doc` is run""" raise NotImplementedError def write_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Where you actually write something to the filesystem.""" raise NotImplementedError def write_doc_serialized(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Handle parts of write_doc that must be called in the main process if parallel build is active. """ pass def finish(self): + # type: () -> None """Finish the building process. The default implementation does nothing. @@ -430,6 +445,7 @@ class Builder(object): pass def cleanup(self): + # type: () -> None """Cleanup any resources. The default implementation does nothing. @@ -437,6 +453,7 @@ class Builder(object): pass def get_builder_config(self, option, default): + # type: (unicode, unicode) -> Any """Return a builder specific option. This method allows customization of common builder settings by diff --git a/sphinx/builders/applehelp.py b/sphinx/builders/applehelp.py index 9a0c20ce9..6337f96da 100644 --- a/sphinx/builders/applehelp.py +++ b/sphinx/builders/applehelp.py @@ -18,8 +18,9 @@ import shlex from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.config import string_classes +from sphinx.util import logging from sphinx.util.osutil import copyfile, ensuredir, make_filename -from sphinx.util.console import bold +from sphinx.util.console import bold # type: ignore from sphinx.util.fileutil import copy_asset from sphinx.util.pycompat import htmlescape from sphinx.util.matching import Matcher @@ -28,10 +29,17 @@ from sphinx.errors import SphinxError import plistlib import subprocess +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) # Use plistlib.dump in 3.4 and above try: - write_plist = plistlib.dump + write_plist = plistlib.dump # type: ignore except AttributeError: write_plist = plistlib.writePlist @@ -83,6 +91,7 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): search = False def init(self): + # type: () -> None super(AppleHelpBuilder, self).init() # the output files for HTML help must be .html only self.out_suffix = '.html' @@ -101,25 +110,28 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): self.config.applehelp_locale + '.lproj') def handle_finish(self): + # type: () -> None super(AppleHelpBuilder, self).handle_finish() self.finish_tasks.add_task(self.copy_localized_files) self.finish_tasks.add_task(self.build_helpbook) def copy_localized_files(self): + # type: () -> None source_dir = path.join(self.confdir, self.config.applehelp_locale + '.lproj') target_dir = self.outdir if path.isdir(source_dir): - self.info(bold('copying localized files... '), nonl=True) + logger.info(bold('copying localized files... '), nonl=True) excluded = Matcher(self.config.exclude_patterns + ['**/.*']) copy_asset(source_dir, target_dir, excluded, context=self.globalcontext, renderer=self.templates) - self.info('done') + logger.info('done') def build_helpbook(self): + # type: () -> None contents_dir = path.join(self.bundle_path, 'Contents') resources_dir = path.join(contents_dir, 'Resources') language_dir = path.join(resources_dir, @@ -157,37 +169,36 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): if self.config.applehelp_remote_url is not None: info_plist['HPDBookRemoteURL'] = self.config.applehelp_remote_url - self.info(bold('writing Info.plist... '), nonl=True) + logger.info(bold('writing Info.plist... '), nonl=True) with open(path.join(contents_dir, 'Info.plist'), 'wb') as f: write_plist(info_plist, f) - self.info('done') + logger.info('done') # Copy the icon, if one is supplied if self.config.applehelp_icon: - self.info(bold('copying icon... '), nonl=True) + logger.info(bold('copying icon... '), nonl=True) try: copyfile(path.join(self.srcdir, self.config.applehelp_icon), path.join(resources_dir, info_plist['HPDBookIconPath'])) - self.info('done') + logger.info('done') except Exception as err: - self.warn('cannot copy icon file %r: %s' % - (path.join(self.srcdir, self.config.applehelp_icon), - err)) + logger.warning('cannot copy icon file %r: %s', + path.join(self.srcdir, self.config.applehelp_icon), err) del info_plist['HPDBookIconPath'] # Build the access page - self.info(bold('building access page...'), nonl=True) + logger.info(bold('building access page...'), nonl=True) with codecs.open(path.join(language_dir, '_access.html'), 'w') as f: f.write(access_page_template % { 'toc': htmlescape(toc, quote=True), 'title': htmlescape(self.config.applehelp_title) }) - self.info('done') + logger.info('done') # Generate the help index - self.info(bold('generating help index... '), nonl=True) + logger.info(bold('generating help index... '), nonl=True) args = [ self.config.applehelp_indexer_path, @@ -209,10 +220,10 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): args += ['-l', self.config.applehelp_locale] if self.config.applehelp_disable_external_tools: - self.info('skipping') + logger.info('skipping') - self.warn('you will need to index this help book with:\n %s' - % (' '.join([pipes.quote(arg) for arg in args]))) + logger.warning('you will need to index this help book with:\n %s', + ' '.join([pipes.quote(arg) for arg in args])) else: try: p = subprocess.Popen(args, @@ -224,13 +235,13 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): if p.returncode != 0: raise AppleHelpIndexerFailed(output) else: - self.info('done') + logger.info('done') except OSError: raise AppleHelpIndexerFailed('Command not found: %s' % args[0]) # If we've been asked to, sign the bundle if self.config.applehelp_codesign_identity: - self.info(bold('signing help book... '), nonl=True) + logger.info(bold('signing help book... '), nonl=True) args = [ self.config.applehelp_codesign_path, @@ -243,10 +254,9 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): args.append(self.bundle_path) if self.config.applehelp_disable_external_tools: - self.info('skipping') - - self.warn('you will need to sign this help book with:\n %s' - % (' '.join([pipes.quote(arg) for arg in args]))) + logger.info('skipping') + logger.warning('you will need to sign this help book with:\n %s', + ' '.join([pipes.quote(arg) for arg in args])) else: try: p = subprocess.Popen(args, @@ -258,12 +268,13 @@ class AppleHelpBuilder(StandaloneHTMLBuilder): if p.returncode != 0: raise AppleHelpCodeSigningFailed(output) else: - self.info('done') + logger.info('done') except OSError: raise AppleHelpCodeSigningFailed('Command not found: %s' % args[0]) def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.setup_extension('sphinx.builders.html') app.add_builder(AppleHelpBuilder) diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index a756742c9..d6e118d97 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -18,11 +18,20 @@ from sphinx import package_dir from sphinx.locale import _ from sphinx.theming import Theme from sphinx.builders import Builder +from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path -from sphinx.util.console import bold +from sphinx.util.console import bold # type: ignore from sphinx.util.fileutil import copy_asset_file from sphinx.util.pycompat import htmlescape +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) + class ChangesBuilder(Builder): """ @@ -31,30 +40,32 @@ class ChangesBuilder(Builder): name = 'changes' def init(self): + # type: () -> None self.create_template_bridge() - Theme.init_themes(self.confdir, self.config.html_theme_path, - warn=self.warn) + Theme.init_themes(self.confdir, self.config.html_theme_path) self.theme = Theme('default') self.templates.init(self, self.theme) def get_outdated_docs(self): + # type: () -> unicode return self.outdir typemap = { 'versionadded': 'added', 'versionchanged': 'changed', 'deprecated': 'deprecated', - } + } # type: Dict[unicode, unicode] def write(self, *ignored): + # type: (Any) -> None version = self.config.version - libchanges = {} - apichanges = [] - otherchanges = {} + libchanges = {} # type: Dict[unicode, List[Tuple[unicode, unicode, int]]] + apichanges = [] # type: List[Tuple[unicode, unicode, int]] + otherchanges = {} # type: Dict[Tuple[unicode, unicode], List[Tuple[unicode, unicode, int]]] # NOQA if version not in self.env.versionchanges: - self.info(bold('no changes in version %s.' % version)) + logger.info(bold('no changes in version %s.' % version)) return - self.info(bold('writing summary file...')) + logger.info(bold('writing summary file...')) for type, docname, lineno, module, descname, content in \ self.env.versionchanges[version]: if isinstance(descname, tuple): @@ -101,9 +112,9 @@ class ChangesBuilder(Builder): 'show_copyright': self.config.html_show_copyright, 'show_sphinx': self.config.html_show_sphinx, } - with codecs.open(path.join(self.outdir, 'index.html'), 'w', 'utf8') as f: + with codecs.open(path.join(self.outdir, 'index.html'), 'w', 'utf8') as f: # type: ignore # NOQA f.write(self.templates.render('changes/frameset.html', ctx)) - with codecs.open(path.join(self.outdir, 'changes.html'), 'w', 'utf8') as f: + with codecs.open(path.join(self.outdir, 'changes.html'), 'w', 'utf8') as f: # type: ignore # NOQA f.write(self.templates.render('changes/versionchanges.html', ctx)) hltext = ['.. versionadded:: %s' % version, @@ -118,18 +129,18 @@ class ChangesBuilder(Builder): break return line - self.info(bold('copying source files...')) + logger.info(bold('copying source files...')) for docname in self.env.all_docs: - with codecs.open(self.env.doc2path(docname), 'r', + with codecs.open(self.env.doc2path(docname), 'r', # type: ignore self.env.config.source_encoding) as f: try: lines = f.readlines() except UnicodeDecodeError: - self.warn('could not read %r for changelog creation' % docname) + logger.warning('could not read %r for changelog creation', docname) continue targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html' ensuredir(path.dirname(targetfn)) - with codecs.open(targetfn, 'w', 'utf-8') as f: + with codecs.open(targetfn, 'w', 'utf-8') as f: # type: ignore text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) ctx = { 'filename': self.env.doc2path(docname, None), @@ -144,6 +155,7 @@ class ChangesBuilder(Builder): self.outdir) def hl(self, text, version): + # type: (unicode, unicode) -> unicode text = htmlescape(text) for directive in ['versionchanged', 'versionadded', 'deprecated']: text = text.replace('.. %s:: %s' % (directive, version), @@ -151,10 +163,12 @@ class ChangesBuilder(Builder): return text def finish(self): + # type: () -> None pass def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(ChangesBuilder) return { diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py index 0849a72ea..af8bcfeed 100644 --- a/sphinx/builders/devhelp.py +++ b/sphinx/builders/devhelp.py @@ -19,13 +19,22 @@ from os import path from docutils import nodes from sphinx import addnodes +from sphinx.util import logging from sphinx.util.osutil import make_filename from sphinx.builders.html import StandaloneHTMLBuilder try: import xml.etree.ElementTree as etree except ImportError: - import lxml.etree as etree + import lxml.etree as etree # type: ignore + +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) class DevhelpBuilder(StandaloneHTMLBuilder): @@ -44,15 +53,18 @@ class DevhelpBuilder(StandaloneHTMLBuilder): embedded = True def init(self): + # type: () -> None StandaloneHTMLBuilder.init(self) self.out_suffix = '.html' self.link_suffix = '.html' def handle_finish(self): + # type: () -> None self.build_devhelp(self.outdir, self.config.devhelp_basename) def build_devhelp(self, outdir, outname): - self.info('dumping devhelp index...') + # type: (unicode, unicode) -> None + logger.info('dumping devhelp index...') # Basic info root = etree.Element('book', @@ -69,6 +81,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder): self.config.master_doc, self, prune_toctrees=False) def write_toc(node, parent): + # type: (nodes.Node, nodes.Node) -> None if isinstance(node, addnodes.compact_paragraph) or \ isinstance(node, nodes.bullet_list): for subnode in node: @@ -82,6 +95,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder): parent.attrib['name'] = node.astext() def istoctree(node): + # type: (nodes.Node) -> bool return isinstance(node, addnodes.compact_paragraph) and \ 'toctree' in node @@ -93,6 +107,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder): index = self.env.create_index(self) def write_index(title, refs, subitems): + # type: (unicode, List[Any], Any) -> None if len(refs) == 0: pass elif len(refs) == 1: @@ -105,7 +120,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder): link=ref[1]) if subitems: - parent_title = re.sub(r'\s*\(.*\)\s*$', '', title) + parent_title = re.sub(r'\s*\(.*\)\s*$', '', title) # type: ignore for subitem in subitems: write_index("%s %s" % (parent_title, subitem[0]), subitem[1], []) @@ -116,11 +131,12 @@ class DevhelpBuilder(StandaloneHTMLBuilder): # Dump the XML file xmlfile = path.join(outdir, outname + '.devhelp.gz') - with gzip.open(xmlfile, 'w') as f: + with gzip.open(xmlfile, 'w') as f: # type: ignore tree.write(f, 'utf-8') def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.setup_extension('sphinx.builders.html') app.add_builder(DevhelpBuilder) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index c22f5ff76..a48f94436 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -29,9 +29,18 @@ from docutils import nodes from sphinx import addnodes from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.util import logging from sphinx.util.osutil import ensuredir, copyfile, make_filename, EEXIST from sphinx.util.smartypants import sphinx_smarty_pants as ssp -from sphinx.util.console import brown +from sphinx.util.console import brown # type: ignore + +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) # (Fragment) templates from which the metainfo files content.opf, toc.ncx, @@ -159,7 +168,7 @@ MEDIA_TYPES = { '.otf': 'application/x-font-otf', '.ttf': 'application/x-font-ttf', '.woff': 'application/font-woff', -} +} # type: Dict[unicode, unicode] VECTOR_GRAPHICS_EXTENSIONS = ('.svg',) @@ -221,6 +230,7 @@ class EpubBuilder(StandaloneHTMLBuilder): refuri_re = REFURI_RE def init(self): + # type: () -> None StandaloneHTMLBuilder.init(self) # the output files for epub must be .html only self.out_suffix = '.xhtml' @@ -230,10 +240,12 @@ class EpubBuilder(StandaloneHTMLBuilder): self.use_index = self.get_builder_config('use_index', 'epub') def get_theme_config(self): + # type: () -> Tuple[unicode, Dict] return self.config.epub_theme, self.config.epub_theme_options # generic support functions def make_id(self, name, id_cache={}): + # type: (unicode, Dict[unicode, unicode]) -> unicode # id_cache is intentionally mutable """Return a unique id for name.""" id = id_cache.get(name) @@ -243,6 +255,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return id def esc(self, name): + # type: (unicode) -> unicode """Replace all characters not allowed in text an attribute values.""" # Like cgi.escape, but also replace apostrophe name = name.replace('&', '&') @@ -253,6 +266,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return name def get_refnodes(self, doctree, result): + # type: (nodes.Node, List[Dict[unicode, Any]]) -> List[Dict[unicode, Any]] """Collect section titles, their depth in the toc and the refuri.""" # XXX: is there a better way than checking the attribute # toctree-l[1-8] on the parent node? @@ -276,6 +290,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return result def get_toc(self): + # type: () -> None """Get the total table of contents, containing the master_doc and pre and post files not managed by sphinx. """ @@ -291,6 +306,7 @@ class EpubBuilder(StandaloneHTMLBuilder): self.toc_add_files(self.refnodes) def toc_add_files(self, refnodes): + # type: (List[nodes.Node]) -> None """Add the master_doc, pre and post files to a list of refnodes. """ refnodes.insert(0, { @@ -313,10 +329,12 @@ class EpubBuilder(StandaloneHTMLBuilder): }) def fix_fragment(self, prefix, fragment): + # type: (unicode, unicode) -> unicode """Return a href/id attribute with colons replaced by hyphens.""" return prefix + fragment.replace(':', '-') def fix_ids(self, tree): + # type: (nodes.Node) -> None """Replace colons with hyphens in href and id attributes. Some readers crash because they interpret the part as a @@ -337,9 +355,11 @@ class EpubBuilder(StandaloneHTMLBuilder): node.attributes['ids'] = newids def add_visible_links(self, tree, show_urls='inline'): + # type: (nodes.Node, unicode) -> None """Add visible link targets for external links""" def make_footnote_ref(doc, label): + # type: (nodes.Node, unicode) -> nodes.footnote_reference """Create a footnote_reference node with children""" footnote_ref = nodes.footnote_reference('[#]_') footnote_ref.append(nodes.Text(label)) @@ -347,6 +367,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return footnote_ref def make_footnote(doc, label, uri): + # type: (nodes.Node, unicode, unicode) -> nodes.footnote """Create a footnote node with children""" footnote = nodes.footnote(uri) para = nodes.paragraph() @@ -357,6 +378,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return footnote def footnote_spot(tree): + # type: (nodes.Node) -> Tuple[nodes.Node, int] """Find or create a spot to place footnotes. The function returns the tuple (parent, index).""" @@ -406,6 +428,7 @@ class EpubBuilder(StandaloneHTMLBuilder): fn_idx += 1 def write_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Write one document file. This method is overwritten in order to fix fragment identifiers @@ -416,6 +439,7 @@ class EpubBuilder(StandaloneHTMLBuilder): StandaloneHTMLBuilder.write_doc(self, docname, doctree) def fix_genindex(self, tree): + # type: (nodes.Node) -> None """Fix href attributes for genindex pages.""" # XXX: modifies tree inline # Logic modeled from themes/basic/genindex.html @@ -434,11 +458,13 @@ class EpubBuilder(StandaloneHTMLBuilder): self.fix_fragment(m.group(1), m.group(2))) def is_vector_graphics(self, filename): + # type: (unicode) -> bool """Does the filename extension indicate a vector graphic format?""" ext = path.splitext(filename)[-1] return ext in VECTOR_GRAPHICS_EXTENSIONS def copy_image_files_pil(self): + # type: () -> None """Copy images using the PIL. The method tries to read and write the files with the PIL, converting the format and resizing the image if necessary/possible. @@ -451,14 +477,14 @@ class EpubBuilder(StandaloneHTMLBuilder): img = Image.open(path.join(self.srcdir, src)) except IOError: if not self.is_vector_graphics(src): - self.warn('cannot read image file %r: copying it instead' % - (path.join(self.srcdir, src), )) + logger.warning('cannot read image file %r: copying it instead', + path.join(self.srcdir, src)) try: copyfile(path.join(self.srcdir, src), path.join(self.outdir, self.imagedir, dest)) except (IOError, OSError) as err: - self.warn('cannot copy image file %r: %s' % - (path.join(self.srcdir, src), err)) + logger.warning('cannot copy image file %r: %s', + path.join(self.srcdir, src), err) continue if self.config.epub_fix_images: if img.mode in ('P',): @@ -473,17 +499,18 @@ class EpubBuilder(StandaloneHTMLBuilder): try: img.save(path.join(self.outdir, self.imagedir, dest)) except (IOError, OSError) as err: - self.warn('cannot write image file %r: %s' % - (path.join(self.srcdir, src), err)) + logger.warning('cannot write image file %r: %s', + path.join(self.srcdir, src), err) def copy_image_files(self): + # type: () -> None """Copy image files to destination directory. This overwritten method can use the PIL to convert image files. """ if self.images: if self.config.epub_fix_images or self.config.epub_max_image_width: if not Image: - self.warn('PIL not found - copying image files') + logger.warning('PIL not found - copying image files') super(EpubBuilder, self).copy_image_files() else: self.copy_image_files_pil() @@ -491,10 +518,12 @@ class EpubBuilder(StandaloneHTMLBuilder): super(EpubBuilder, self).copy_image_files() def copy_download_files(self): + # type: () -> None pass def handle_page(self, pagename, addctx, templatename='page.html', outfilename=None, event_arg=None): + # type: (unicode, Dict, unicode, unicode, Any) -> None """Create a rendered page. This method is overwritten for genindex pages in order to fix href link @@ -510,6 +539,7 @@ class EpubBuilder(StandaloneHTMLBuilder): # Finish by building the epub file def handle_finish(self): + # type: () -> None """Create the metainfo files and finally the epub.""" self.get_toc() self.build_mimetype(self.outdir, 'mimetype') @@ -519,28 +549,31 @@ class EpubBuilder(StandaloneHTMLBuilder): self.build_epub(self.outdir, self.config.epub_basename + '.epub') def build_mimetype(self, outdir, outname): + # type: (unicode, unicode) -> None """Write the metainfo file mimetype.""" - self.info('writing %s file...' % outname) - with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: + logger.info('writing %s file...', outname) + with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: # type: ignore f.write(self.mimetype_template) def build_container(self, outdir, outname): + # type: (unicode, unicode) -> None """Write the metainfo file META-INF/cointainer.xml.""" - self.info('writing %s file...' % outname) + logger.info('writing %s file...', outname) fn = path.join(outdir, outname) try: os.mkdir(path.dirname(fn)) except OSError as err: if err.errno != EEXIST: raise - with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: - f.write(self.container_template) + with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: # type: ignore + f.write(self.container_template) # type: ignore def content_metadata(self, files, spine, guide): + # type: (List[unicode], Any, Any) -> Dict[unicode, Any] """Create a dictionary with all metadata for the content.opf file properly escaped. """ - metadata = {} + metadata = {} # type: Dict[unicode, Any] metadata['title'] = self.esc(self.config.epub_title) metadata['author'] = self.esc(self.config.epub_author) metadata['uid'] = self.esc(self.config.epub_uid) @@ -556,17 +589,18 @@ class EpubBuilder(StandaloneHTMLBuilder): return metadata def build_content(self, outdir, outname): + # type: (unicode, unicode) -> None """Write the metainfo file content.opf It contains bibliographic data, a file list and the spine (the reading order). """ - self.info('writing %s file...' % outname) + logger.info('writing %s file...', outname) # files if not outdir.endswith(os.sep): outdir += os.sep olen = len(outdir) - projectfiles = [] - self.files = [] + projectfiles = [] # type: List[unicode] + self.files = [] # type: List[unicode] self.ignored_files = ['.buildinfo', 'mimetype', 'content.opf', 'toc.ncx', 'META-INF/container.xml', 'Thumbs.db', 'ehthumbs.db', '.DS_Store', @@ -584,8 +618,8 @@ class EpubBuilder(StandaloneHTMLBuilder): # we always have JS and potentially OpenSearch files, don't # always warn about them if ext not in ('.js', '.xml'): - self.warn('unknown mimetype for %s, ignoring' % filename, - type='epub', subtype='unknown_project_files') + logger.warning('unknown mimetype for %s, ignoring', filename, + type='epub', subtype='unknown_project_files') continue filename = filename.replace(os.sep, '/') projectfiles.append(self.file_template % { @@ -680,16 +714,17 @@ class EpubBuilder(StandaloneHTMLBuilder): 'title': self.guide_titles['toc'], 'uri': self.esc(self.refnodes[0]['refuri']) }) - projectfiles = '\n'.join(projectfiles) - spine = '\n'.join(spine) - guide = '\n'.join(guide) + projectfiles = '\n'.join(projectfiles) # type: ignore + spine = '\n'.join(spine) # type: ignore + guide = '\n'.join(guide) # type: ignore # write the project file - with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: - f.write(content_tmpl % + with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: # type: ignore + f.write(content_tmpl % # type: ignore self.content_metadata(projectfiles, spine, guide)) def new_navpoint(self, node, level, incr=True): + # type: (nodes.Node, int, bool) -> unicode """Create a new entry in the toc from the node at given level.""" # XXX Modifies the node if incr: @@ -701,6 +736,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return self.navpoint_template % node def insert_subnav(self, node, subnav): + # type: (nodes.Node, unicode) -> unicode """Insert nested navpoints for given node. The node and subnav are already rendered to text. @@ -710,6 +746,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return '\n'.join(nlist) def build_navpoints(self, nodes): + # type: (nodes.Node) -> unicode """Create the toc navigation structure. Subelements of a node are nested inside the navpoint. For nested nodes @@ -753,10 +790,11 @@ class EpubBuilder(StandaloneHTMLBuilder): return '\n'.join(navlist) def toc_metadata(self, level, navpoints): + # type: (int, List[unicode]) -> Dict[unicode, Any] """Create a dictionary with all metadata for the toc.ncx file properly escaped. """ - metadata = {} + metadata = {} # type: Dict[unicode, Any] metadata['uid'] = self.config.epub_uid metadata['title'] = self.config.epub_title metadata['level'] = level @@ -764,8 +802,9 @@ class EpubBuilder(StandaloneHTMLBuilder): return metadata def build_toc(self, outdir, outname): + # type: (unicode, unicode) -> None """Write the metainfo file toc.ncx.""" - self.info('writing %s file...' % outname) + logger.info('writing %s file...', outname) if self.config.epub_tocscope == 'default': doctree = self.env.get_and_resolve_doctree(self.config.master_doc, @@ -779,29 +818,31 @@ class EpubBuilder(StandaloneHTMLBuilder): navpoints = self.build_navpoints(refnodes) level = max(item['level'] for item in self.refnodes) level = min(level, self.config.epub_tocdepth) - with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: - f.write(self.toc_template % self.toc_metadata(level, navpoints)) + with codecs.open(path.join(outdir, outname), 'w', 'utf-8') as f: # type: ignore + f.write(self.toc_template % self.toc_metadata(level, navpoints)) # type: ignore def build_epub(self, outdir, outname): + # type: (unicode, unicode) -> None """Write the epub file. It is a zip file with the mimetype file stored uncompressed as the first entry. """ - self.info('writing %s file...' % outname) - projectfiles = ['META-INF/container.xml', 'content.opf', 'toc.ncx'] \ - + self.files - epub = zipfile.ZipFile(path.join(outdir, outname), 'w', + logger.info('writing %s file...', outname) + projectfiles = ['META-INF/container.xml', 'content.opf', 'toc.ncx'] # type: List[unicode] # NOQA + projectfiles.extend(self.files) + epub = zipfile.ZipFile(path.join(outdir, outname), 'w', # type: ignore zipfile.ZIP_DEFLATED) - epub.write(path.join(outdir, 'mimetype'), 'mimetype', + epub.write(path.join(outdir, 'mimetype'), 'mimetype', # type: ignore zipfile.ZIP_STORED) for file in projectfiles: fp = path.join(outdir, file) - epub.write(fp, file, zipfile.ZIP_DEFLATED) + epub.write(fp, file, zipfile.ZIP_DEFLATED) # type: ignore epub.close() def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.setup_extension('sphinx.builders.html') app.add_builder(EpubBuilder) diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py index 5e0663a08..c2022e622 100644 --- a/sphinx/builders/epub3.py +++ b/sphinx/builders/epub3.py @@ -16,6 +16,10 @@ from datetime import datetime from sphinx.config import string_classes from sphinx.builders.epub import EpubBuilder +from sphinx.util import logging + + +logger = logging.getLogger(__name__) # (Fragment) templates from which the metainfo files content.opf, toc.ncx, @@ -235,7 +239,7 @@ class Epub3Builder(EpubBuilder): def build_navigation_doc(self, outdir, outname): """Write the metainfo file nav.xhtml.""" - self.info('writing %s file...' % outname) + logger.info('writing %s file...', outname) if self.config.epub_tocscope == 'default': doctree = self.env.get_and_resolve_doctree( @@ -256,31 +260,13 @@ class Epub3Builder(EpubBuilder): self.files.append(outname) -def validate_config_values(app): - if app.config.epub3_description is not None: - app.warn('epub3_description is deprecated. Use epub_description instead.') - app.config.epub_description = app.config.epub3_description - - if app.config.epub3_contributor is not None: - app.warn('epub3_contributor is deprecated. Use epub_contributor instead.') - app.config.epub_contributor = app.config.epub3_contributor - - if app.config.epub3_page_progression_direction is not None: - app.warn('epub3_page_progression_direction option is deprecated' - ' from 1.5. Use epub_writing_mode instead.') - - def setup(app): app.setup_extension('sphinx.builders.epub') app.add_builder(Epub3Builder) - app.connect('builder-inited', validate_config_values) app.add_config_value('epub_description', '', 'epub3', string_classes) app.add_config_value('epub_contributor', 'unknown', 'epub3', string_classes) app.add_config_value('epub_writing_mode', 'horizontal', 'epub3', string_classes) - app.add_config_value('epub3_description', None, 'epub3', string_classes) - app.add_config_value('epub3_contributor', None, 'epub3', string_classes) - app.add_config_value('epub3_page_progression_direction', None, 'epub3', string_classes) return { 'version': 'builtin', diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py index ca51f90d0..6993210f3 100644 --- a/sphinx/builders/gettext.py +++ b/sphinx/builders/gettext.py @@ -21,14 +21,24 @@ from uuid import uuid4 from six import iteritems from sphinx.builders import Builder -from sphinx.util import split_index_msg +from sphinx.util import split_index_msg, logging from sphinx.util.tags import Tags from sphinx.util.nodes import extract_messages, traverse_translatable_index from sphinx.util.osutil import safe_relpath, ensuredir, canon_path from sphinx.util.i18n import find_catalog -from sphinx.util.console import darkgreen, purple, bold +from sphinx.util.console import darkgreen, purple, bold # type: ignore from sphinx.locale import pairindextypes +if False: + # For type annotation + from typing import Any, Iterable, Tuple # NOQA + from docutils import nodes # NOQA + from sphinx.util.i18n import CatalogInfo # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) + POHEADER = r""" # SOME DESCRIPTIVE TITLE. # Copyright (C) %(copyright)s @@ -55,10 +65,14 @@ class Catalog(object): """Catalog of translatable messages.""" def __init__(self): - self.messages = [] # retain insertion order, a la OrderedDict - self.metadata = {} # msgid -> file, line, uid + # type: () -> None + self.messages = [] # type: List[unicode] + # retain insertion order, a la OrderedDict + self.metadata = {} # type: Dict[unicode, List[Tuple[unicode, int, unicode]]] + # msgid -> file, line, uid def add(self, msg, origin): + # type: (unicode, MsgOrigin) -> None if not hasattr(origin, 'uid'): # Nodes that are replicated like todo don't have a uid, # however i18n is also unnecessary. @@ -75,6 +89,7 @@ class MsgOrigin(object): """ def __init__(self, source, line): + # type: (unicode, int) -> None self.source = source self.line = line self.uid = uuid4().hex @@ -87,6 +102,7 @@ class I18nTags(Tags): always returns True value even if no tags are defined. """ def eval_condition(self, condition): + # type: (Any) -> bool return True @@ -99,27 +115,34 @@ class I18nBuilder(Builder): versioning_compare = None # be set by `gettext_uuid` def __init__(self, app): + # type: (Sphinx) -> None self.versioning_compare = app.env.config.gettext_uuid super(I18nBuilder, self).__init__(app) def init(self): + # type: () -> None Builder.init(self) self.tags = I18nTags() - self.catalogs = defaultdict(Catalog) + self.catalogs = defaultdict(Catalog) # type: defaultdict[unicode, Catalog] def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode return '' def get_outdated_docs(self): + # type: () -> Set[unicode] return self.env.found_docs def prepare_writing(self, docnames): + # type: (Set[unicode]) -> None return def compile_catalogs(self, catalogs, message): + # type: (Set[CatalogInfo], unicode) -> None return def write_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None catalog = self.catalogs[find_catalog(docname, self.config.gettext_compact)] @@ -153,13 +176,16 @@ if source_date_epoch is not None: class LocalTimeZone(tzinfo): def __init__(self, *args, **kw): - super(LocalTimeZone, self).__init__(*args, **kw) + # type: (Any, Any) -> None + super(LocalTimeZone, self).__init__(*args, **kw) # type: ignore self.tzdelta = tzdelta def utcoffset(self, dt): + # type: (datetime) -> timedelta return self.tzdelta def dst(self, dt): + # type: (datetime) -> timedelta return timedelta(0) @@ -173,11 +199,13 @@ class MessageCatalogBuilder(I18nBuilder): name = 'gettext' def init(self): + # type: () -> None I18nBuilder.init(self) self.create_template_bridge() self.templates.init(self) def _collect_templates(self): + # type: () -> Set[unicode] template_files = set() for template_path in self.config.templates_path: tmpl_abs_path = path.join(self.app.srcdir, template_path) @@ -189,31 +217,34 @@ class MessageCatalogBuilder(I18nBuilder): return template_files def _extract_from_template(self): + # type: () -> None files = self._collect_templates() - self.info(bold('building [%s]: ' % self.name), nonl=1) - self.info('targets for %d template files' % len(files)) + logger.info(bold('building [%s]: ' % self.name), nonl=1) + logger.info('targets for %d template files', len(files)) extract_translations = self.templates.environment.extract_translations for template in self.app.status_iterator( files, 'reading templates... ', purple, len(files)): - with open(template, 'r', encoding='utf-8') as f: + with open(template, 'r', encoding='utf-8') as f: # type: ignore context = f.read() for line, meth, msg in extract_translations(context): origin = MsgOrigin(template, line) self.catalogs['sphinx'].add(msg, origin) def build(self, docnames, summary=None, method='update'): + # type: (Iterable[unicode], unicode, unicode) -> None self._extract_from_template() I18nBuilder.build(self, docnames, summary, method) def finish(self): + # type: () -> None I18nBuilder.finish(self) data = dict( version = self.config.version, copyright = self.config.copyright, project = self.config.project, - ctime = datetime.fromtimestamp( + ctime = datetime.fromtimestamp( # type: ignore timestamp, ltz).strftime('%Y-%m-%d %H:%M%z'), ) for textdomain, catalog in self.app.status_iterator( @@ -224,31 +255,32 @@ class MessageCatalogBuilder(I18nBuilder): ensuredir(path.join(self.outdir, path.dirname(textdomain))) pofn = path.join(self.outdir, textdomain + '.pot') - with open(pofn, 'w', encoding='utf-8') as pofile: - pofile.write(POHEADER % data) + with open(pofn, 'w', encoding='utf-8') as pofile: # type: ignore + pofile.write(POHEADER % data) # type: ignore for message in catalog.messages: positions = catalog.metadata[message] if self.config.gettext_location: # generate "#: file1:line1\n#: file2:line2 ..." - pofile.write("#: %s\n" % "\n#: ".join( + pofile.write("#: %s\n" % "\n#: ".join( # type: ignore "%s:%s" % (canon_path( safe_relpath(source, self.outdir)), line) for source, line, _ in positions)) if self.config.gettext_uuid: # generate "# uuid1\n# uuid2\n ..." - pofile.write("# %s\n" % "\n# ".join( + pofile.write("# %s\n" % "\n# ".join( # type: ignore uid for _, _, uid in positions)) # message contains *one* line of text ready for translation message = message.replace('\\', r'\\'). \ replace('"', r'\"'). \ replace('\n', '\\n"\n"') - pofile.write('msgid "%s"\nmsgstr ""\n\n' % message) + pofile.write('msgid "%s"\nmsgstr ""\n\n' % message) # type: ignore def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(MessageCatalogBuilder) app.add_config_value('gettext_compact', True, 'gettext') diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 9160080c8..d9512b5df 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -19,6 +19,7 @@ from hashlib import md5 from six import iteritems, text_type, string_types from six.moves import cPickle as pickle + from docutils import nodes from docutils.io import DocTreeInput, StringOutput from docutils.core import Publisher @@ -27,7 +28,7 @@ from docutils.frontend import OptionParser from docutils.readers.doctree import Reader as DoctreeReader from sphinx import package_dir, __display_version__ -from sphinx.util import jsonimpl +from sphinx.util import jsonimpl, logging from sphinx.util.i18n import format_date from sphinx.util.osutil import SEP, os_path, relative_uri, ensuredir, \ movefile, copyfile @@ -41,17 +42,26 @@ from sphinx.theming import Theme from sphinx.builders import Builder from sphinx.application import ENV_PICKLE_FILENAME from sphinx.highlighting import PygmentsBridge -from sphinx.util.console import bold, darkgreen, brown +from sphinx.util.console import bold, darkgreen, brown # type: ignore from sphinx.writers.html import HTMLWriter, HTMLTranslator, \ SmartyPantsHTMLTranslator +if False: + # For type annotation + from typing import Any, Iterable, Iterator, Tuple, Union # NOQA + from sphinx.domains import Domain, Index # NOQA + from sphinx.application import Sphinx # NOQA + #: the filename for the inventory of objects INVENTORY_FILENAME = 'objects.inv' #: the filename for the "last build" file (for serializing builders) LAST_BUILD_FILENAME = 'last_build' +logger = logging.getLogger(__name__) + def get_stable_hash(obj): + # type: (Any) -> unicode """ Return a stable hash for a Python data structure. We can't just use the md5 of str(obj) since for example dictionary items are enumerated @@ -85,13 +95,17 @@ class StandaloneHTMLBuilder(Builder): allow_sharp_as_current_path = True embedded = False # for things like HTML help or Qt help: suppresses sidebar search = True # for things like HTML help and Apple help: suppress search + use_index = False download_support = True # enable download role # This is a class attribute because it is mutated by Sphinx.add_javascript. script_files = ['_static/jquery.js', '_static/underscore.js', - '_static/doctools.js'] + '_static/doctools.js'] # type: List[unicode] # Dito for this one. - css_files = [] + css_files = [] # type: List[unicode] + + imgpath = None # type: unicode + domain_indices = [] # type: List[Tuple[unicode, Index, unicode, bool]] default_sidebars = ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] @@ -100,15 +114,16 @@ class StandaloneHTMLBuilder(Builder): _publisher = None def init(self): + # type: () -> None # a hash of all config values that, if changed, cause a full rebuild - self.config_hash = '' - self.tags_hash = '' + self.config_hash = '' # type: unicode + self.tags_hash = '' # type: unicode # basename of images directory self.imagedir = '_images' # section numbers for headings in the currently visited document - self.secnumbers = {} + self.secnumbers = {} # type: Dict[unicode, Tuple[int, ...]] # currently written docname - self.current_docname = None + self.current_docname = None # type: unicode self.init_templates() self.init_highlighter() @@ -127,6 +142,7 @@ class StandaloneHTMLBuilder(Builder): self.use_index = self.get_builder_config('use_index', 'html') def _get_translations_js(self): + # type: () -> unicode candidates = [path.join(package_dir, 'locale', self.config.language, 'LC_MESSAGES', 'sphinx.js'), path.join(sys.prefix, 'share/sphinx/locale', @@ -140,18 +156,20 @@ class StandaloneHTMLBuilder(Builder): return None def get_theme_config(self): + # type: () -> Tuple[unicode, Dict] return self.config.html_theme, self.config.html_theme_options def init_templates(self): - Theme.init_themes(self.confdir, self.config.html_theme_path, - warn=self.warn) + # type: () -> None + Theme.init_themes(self.confdir, self.config.html_theme_path) themename, themeoptions = self.get_theme_config() - self.theme = Theme(themename, warn=self.warn) + self.theme = Theme(themename) self.theme_options = themeoptions.copy() self.create_template_bridge() self.templates.init(self, self.theme) def init_highlighter(self): + # type: () -> None # determine Pygments style and create the highlighter if self.config.pygments_style is not None: style = self.config.pygments_style @@ -163,18 +181,20 @@ class StandaloneHTMLBuilder(Builder): self.config.trim_doctest_flags) def init_translator_class(self): + # type: () -> None if self.translator_class is None: if self.config.html_use_smartypants: self.translator_class = SmartyPantsHTMLTranslator else: self.translator_class = HTMLTranslator - def get_outdated_docs(self): + def get_outdated_docs(self): # type: ignore + # type: () -> Iterator[unicode] cfgdict = dict((name, self.config[name]) for (name, desc) in iteritems(self.config.values) if desc[1] == 'html') self.config_hash = get_stable_hash(cfgdict) - self.tags_hash = get_stable_hash(sorted(self.tags)) + self.tags_hash = get_stable_hash(sorted(self.tags)) # type: ignore old_config_hash = old_tags_hash = '' try: with open(path.join(self.outdir, '.buildinfo')) as fp: @@ -189,8 +209,8 @@ class StandaloneHTMLBuilder(Builder): if tag != 'tags': raise ValueError except ValueError: - self.warn('unsupported build info format in %r, building all' % - path.join(self.outdir, '.buildinfo')) + logger.warning('unsupported build info format in %r, building all', + path.join(self.outdir, '.buildinfo')) except Exception: pass if old_config_hash != self.config_hash or \ @@ -222,6 +242,7 @@ class StandaloneHTMLBuilder(Builder): pass def render_partial(self, node): + # type: (nodes.Nodes) -> Dict[unicode, unicode] """Utility: Render a lone doctree node.""" if node is None: return {'fragment': ''} @@ -247,6 +268,7 @@ class StandaloneHTMLBuilder(Builder): return pub.writer.parts def prepare_writing(self, docnames): + # type: (Iterable[unicode]) -> nodes.Node # create the search indexer self.indexer = None if self.search: @@ -272,16 +294,13 @@ class StandaloneHTMLBuilder(Builder): indices_config = self.config.html_domain_indices if indices_config: for domain_name in sorted(self.env.domains): + domain = None # type: Domain domain = self.env.domains[domain_name] for indexcls in domain.indices: indexname = '%s-%s' % (domain.name, indexcls.name) if isinstance(indices_config, list): if indexname not in indices_config: continue - # deprecated config value - if indexname == 'py-modindex' and \ - not self.config.html_use_modindex: - continue content, collapse = indexcls(domain).generate() if content: self.domain_indices.append( @@ -292,8 +311,7 @@ class StandaloneHTMLBuilder(Builder): lufmt = self.config.html_last_updated_fmt if lufmt is not None: self.last_updated = format_date(lufmt or _('%b %d, %Y'), - language=self.config.language, - warn=self.warn) + language=self.config.language) else: self.last_updated = None @@ -303,17 +321,17 @@ class StandaloneHTMLBuilder(Builder): favicon = self.config.html_favicon and \ path.basename(self.config.html_favicon) or '' if favicon and os.path.splitext(favicon)[1] != '.ico': - self.warn('html_favicon is not an .ico file') + logger.warning('html_favicon is not an .ico file') if not isinstance(self.config.html_use_opensearch, string_types): - self.warn('html_use_opensearch config value must now be a string') + logger.warning('html_use_opensearch config value must now be a string') self.relations = self.env.collect_relations() rellinks = [] if self.use_index: rellinks.append(('genindex', _('General Index'), 'I', _('index'))) - for indexname, indexcls, content, collapse in self.domain_indices: + for indexname, indexcls, content, collapse in self.domain_indices: # type: ignore # if it has a short name if indexcls.shortname: rellinks.append((indexname, indexcls.localname, @@ -353,7 +371,7 @@ class StandaloneHTMLBuilder(Builder): parents = [], logo = logo, favicon = favicon, - ) + ) # type: Dict[unicode, Any] if self.theme: self.globalcontext.update( ('theme_' + key, val) for (key, val) in @@ -361,6 +379,7 @@ class StandaloneHTMLBuilder(Builder): self.globalcontext.update(self.config.html_context) def get_doc_context(self, docname, body, metatags): + # type: (unicode, unicode, Dict) -> Dict[unicode, Any] """Collect items for the template context of a page.""" # find out relations prev = next = None @@ -441,6 +460,7 @@ class StandaloneHTMLBuilder(Builder): ) def write_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None destination = StringOutput(encoding='utf-8') doctree.settings = self.docsettings @@ -458,6 +478,7 @@ class StandaloneHTMLBuilder(Builder): self.handle_page(docname, ctx, event_arg=doctree) def write_doc_serialized(self, docname, doctree): + # type: (unicode, nodes.Node) -> None self.imgpath = relative_uri(self.get_target_uri(docname), self.imagedir) self.post_process_images(doctree) title = self.env.longtitles.get(docname) @@ -465,6 +486,7 @@ class StandaloneHTMLBuilder(Builder): self.index_page(docname, doctree, title) def finish(self): + # type: () -> None self.finish_tasks.add_task(self.gen_indices) self.finish_tasks.add_task(self.gen_additional_pages) self.finish_tasks.add_task(self.copy_image_files) @@ -477,7 +499,8 @@ class StandaloneHTMLBuilder(Builder): self.handle_finish() def gen_indices(self): - self.info(bold('generating indices...'), nonl=1) + # type: () -> None + logger.info(bold('generating indices...'), nonl=1) # the global general index if self.use_index: @@ -486,35 +509,37 @@ class StandaloneHTMLBuilder(Builder): # the global domain-specific indices self.write_domain_indices() - self.info() + logger.info('') def gen_additional_pages(self): + # type: () -> None # pages from extensions for pagelist in self.app.emit('html-collect-pages'): for pagename, context, template in pagelist: self.handle_page(pagename, context, template) - self.info(bold('writing additional pages...'), nonl=1) + logger.info(bold('writing additional pages...'), nonl=1) # additional pages from conf.py for pagename, template in self.config.html_additional_pages.items(): - self.info(' '+pagename, nonl=1) + logger.info(' '+pagename, nonl=1) self.handle_page(pagename, {}, template) # the search page if self.search: - self.info(' search', nonl=1) + logger.info(' search', nonl=1) self.handle_page('search', {}, 'search.html') # the opensearch xml file if self.config.html_use_opensearch and self.search: - self.info(' opensearch', nonl=1) + logger.info(' opensearch', nonl=1) fn = path.join(self.outdir, '_static', 'opensearch.xml') self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - self.info() + logger.info('') def write_genindex(self): + # type: () -> None # the total count of lines for each index letter, used to distribute # the entries into two columns genindex = self.env.create_index(self) @@ -528,7 +553,7 @@ class StandaloneHTMLBuilder(Builder): genindexcounts = indexcounts, split_index = self.config.html_split_index, ) - self.info(' genindex', nonl=1) + logger.info(' genindex', nonl=1) if self.config.html_split_index: self.handle_page('genindex', genindexcontext, @@ -544,16 +569,18 @@ class StandaloneHTMLBuilder(Builder): self.handle_page('genindex', genindexcontext, 'genindex.html') def write_domain_indices(self): + # type: () -> None for indexname, indexcls, content, collapse in self.domain_indices: indexcontext = dict( indextitle = indexcls.localname, content = content, collapse_index = collapse, ) - self.info(' ' + indexname, nonl=1) + logger.info(' ' + indexname, nonl=1) self.handle_page(indexname, indexcontext, 'domainindex.html') def copy_image_files(self): + # type: () -> None # copy image files if self.images: ensuredir(path.join(self.outdir, self.imagedir)) @@ -564,10 +591,11 @@ class StandaloneHTMLBuilder(Builder): copyfile(path.join(self.srcdir, src), path.join(self.outdir, self.imagedir, dest)) except Exception as err: - self.warn('cannot copy image file %r: %s' % - (path.join(self.srcdir, src), err)) + logger.warning('cannot copy image file %r: %s', + path.join(self.srcdir, src), err) def copy_download_files(self): + # type: () -> None def to_relpath(f): return relative_path(self.srcdir, f) # copy downloadable files @@ -582,12 +610,13 @@ class StandaloneHTMLBuilder(Builder): copyfile(path.join(self.srcdir, src), path.join(self.outdir, '_downloads', dest)) except Exception as err: - self.warn('cannot copy downloadable file %r: %s' % - (path.join(self.srcdir, src), err)) + logger.warning('cannot copy downloadable file %r: %s', + path.join(self.srcdir, src), err) def copy_static_files(self): + # type: () -> None # copy static files - self.info(bold('copying static files... '), nonl=True) + logger.info(bold('copying static files... '), nonl=True) ensuredir(path.join(self.outdir, '_static')) # first, create pygments style file with open(path.join(self.outdir, '_static', 'pygments.css'), 'w') as f: @@ -622,7 +651,7 @@ class StandaloneHTMLBuilder(Builder): for static_path in self.config.html_static_path: entry = path.join(self.confdir, static_path) if not path.exists(entry): - self.warn('html_static_path entry %r does not exist' % entry) + logger.warning('html_static_path entry %r does not exist', entry) continue copy_asset(entry, path.join(self.outdir, '_static'), excluded, context=ctx, renderer=self.templates) @@ -631,7 +660,7 @@ class StandaloneHTMLBuilder(Builder): logobase = path.basename(self.config.html_logo) logotarget = path.join(self.outdir, '_static', logobase) if not path.isfile(path.join(self.confdir, self.config.html_logo)): - self.warn('logo file %r does not exist' % self.config.html_logo) + logger.warning('logo file %r does not exist', self.config.html_logo) elif not path.isfile(logotarget): copyfile(path.join(self.confdir, self.config.html_logo), logotarget) @@ -639,27 +668,29 @@ class StandaloneHTMLBuilder(Builder): iconbase = path.basename(self.config.html_favicon) icontarget = path.join(self.outdir, '_static', iconbase) if not path.isfile(path.join(self.confdir, self.config.html_favicon)): - self.warn('favicon file %r does not exist' % self.config.html_favicon) + logger.warning('favicon file %r does not exist', self.config.html_favicon) elif not path.isfile(icontarget): copyfile(path.join(self.confdir, self.config.html_favicon), icontarget) - self.info('done') + logger.info('done') def copy_extra_files(self): + # type: () -> None # copy html_extra_path files - self.info(bold('copying extra files... '), nonl=True) + logger.info(bold('copying extra files... '), nonl=True) excluded = Matcher(self.config.exclude_patterns) for extra_path in self.config.html_extra_path: entry = path.join(self.confdir, extra_path) if not path.exists(entry): - self.warn('html_extra_path entry %r does not exist' % entry) + logger.warning('html_extra_path entry %r does not exist', entry) continue copy_asset(entry, self.outdir, excluded) - self.info('done') + logger.info('done') def write_buildinfo(self): + # type: () -> None # write build info file with open(path.join(self.outdir, '.buildinfo'), 'w') as fp: fp.write('# Sphinx build info version 1\n' @@ -669,11 +700,13 @@ class StandaloneHTMLBuilder(Builder): (self.config_hash, self.tags_hash)) def cleanup(self): + # type: () -> None # clean up theme stuff if self.theme: self.theme.cleanup() def post_process_images(self, doctree): + # type: (nodes.Node) -> None """Pick the best candidate for an image and link down-scaled images to their high res version. """ @@ -699,24 +732,26 @@ class StandaloneHTMLBuilder(Builder): reference.append(node) def load_indexer(self, docnames): + # type: (Iterable[unicode]) -> None keep = set(self.env.all_docs) - set(docnames) try: searchindexfn = path.join(self.outdir, self.searchindex_filename) if self.indexer_dumps_unicode: - f = codecs.open(searchindexfn, 'r', encoding='utf-8') + f = codecs.open(searchindexfn, 'r', encoding='utf-8') # type: ignore else: - f = open(searchindexfn, 'rb') + f = open(searchindexfn, 'rb') # type: ignore with f: - self.indexer.load(f, self.indexer_format) + self.indexer.load(f, self.indexer_format) # type: ignore except (IOError, OSError, ValueError): if keep: - self.warn('search index couldn\'t be loaded, but not all ' - 'documents will be built: the index will be ' - 'incomplete.') + logger.warning('search index couldn\'t be loaded, but not all ' + 'documents will be built: the index will be ' + 'incomplete.') # delete all entries for files that will be rebuilt self.indexer.prune(keep) def index_page(self, pagename, doctree, title): + # type: (unicode, nodes.Node, unicode) -> None # only index pages with title if self.indexer is not None and title: filename = self.env.doc2path(pagename, base=None) @@ -724,18 +759,21 @@ class StandaloneHTMLBuilder(Builder): self.indexer.feed(pagename, filename, title, doctree) except TypeError: # fallback for old search-adapters - self.indexer.feed(pagename, title, doctree) + self.indexer.feed(pagename, title, doctree) # type: ignore def _get_local_toctree(self, docname, collapse=True, **kwds): + # type: (unicode, bool, Any) -> unicode if 'includehidden' not in kwds: kwds['includehidden'] = False return self.render_partial(self.env.get_toctree_for( docname, self, collapse, **kwds))['fragment'] def get_outfilename(self, pagename): + # type: (unicode) -> unicode return path.join(self.outdir, os_path(pagename) + self.out_suffix) def add_sidebars(self, pagename, ctx): + # type: (unicode, Dict) -> None def has_wildcard(pattern): return any(char in pattern for char in '*?[') sidebars = None @@ -747,9 +785,9 @@ class StandaloneHTMLBuilder(Builder): if has_wildcard(pattern): # warn if both patterns contain wildcards if has_wildcard(matched): - self.warn('page %s matches two patterns in ' - 'html_sidebars: %r and %r' % - (pagename, matched, pattern)) + logger.warning('page %s matches two patterns in ' + 'html_sidebars: %r and %r', + pagename, matched, pattern) # else the already matched pattern is more specific # than the present one, because it contains no wildcard continue @@ -768,14 +806,17 @@ class StandaloneHTMLBuilder(Builder): # --------- these are overwritten by the serialization builder def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode return docname + self.link_suffix def handle_page(self, pagename, addctx, templatename='page.html', outfilename=None, event_arg=None): + # type: (unicode, Dict, unicode, unicode, Any) -> None ctx = self.globalcontext.copy() ctx['warn'] = self.warn # current_page_name is backwards compatibility ctx['pagename'] = ctx['current_page_name'] = pagename + ctx['encoding'] = self.config.html_output_encoding default_baseuri = self.get_target_uri(pagename) # in the singlehtml builder, default_baseuri still contains an #anchor # part, which relative_uri doesn't really like... @@ -803,14 +844,11 @@ class StandaloneHTMLBuilder(Builder): return False ctx['hasdoc'] = hasdoc - if self.name != 'htmlhelp': - ctx['encoding'] = encoding = self.config.html_output_encoding - else: - ctx['encoding'] = encoding = self.encoding ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw) self.add_sidebars(pagename, ctx) ctx.update(addctx) + self.update_page_context(pagename, templatename, ctx, event_arg) newtmpl = self.app.emit_firstresult('html-page-context', pagename, templatename, ctx, event_arg) if newtmpl: @@ -819,9 +857,9 @@ class StandaloneHTMLBuilder(Builder): try: output = self.templates.render(templatename, ctx) except UnicodeError: - self.warn("a Unicode error occurred when rendering the page %s. " - "Please make sure all config values that contain " - "non-ASCII content are Unicode strings." % pagename) + logger.warning("a Unicode error occurred when rendering the page %s. " + "Please make sure all config values that contain " + "non-ASCII content are Unicode strings.", pagename) return if not outfilename: @@ -829,10 +867,10 @@ class StandaloneHTMLBuilder(Builder): # outfilename's path is in general different from self.outdir ensuredir(path.dirname(outfilename)) try: - with codecs.open(outfilename, 'w', encoding, 'xmlcharrefreplace') as f: + with codecs.open(outfilename, 'w', ctx['encoding'], 'xmlcharrefreplace') as f: # type: ignore # NOQA f.write(output) except (IOError, OSError) as err: - self.warn("error writing file %s: %s" % (outfilename, err)) + logger.warning("error writing file %s: %s", outfilename, err) if self.copysource and ctx.get('sourcename'): # copy the source file for the "show source" link source_name = path.join(self.outdir, '_sources', @@ -840,13 +878,18 @@ class StandaloneHTMLBuilder(Builder): ensuredir(path.dirname(source_name)) copyfile(self.env.doc2path(pagename), source_name) + def update_page_context(self, pagename, templatename, ctx, event_arg): + pass + def handle_finish(self): + # type: () -> None if self.indexer: self.finish_tasks.add_task(self.dump_search_index) self.finish_tasks.add_task(self.dump_inventory) def dump_inventory(self): - self.info(bold('dumping object inventory... '), nonl=True) + # type: () -> None + logger.info(bold('dumping object inventory... '), nonl=True) with open(path.join(self.outdir, INVENTORY_FILENAME), 'wb') as f: f.write((u'# Sphinx inventory version 2\n' u'# Project: %s\n' @@ -869,10 +912,11 @@ class StandaloneHTMLBuilder(Builder): (u'%s %s:%s %s %s %s\n' % (name, domainname, type, prio, uri, dispname)).encode('utf-8'))) f.write(compressor.flush()) - self.info('done') + logger.info('done') def dump_search_index(self): - self.info( + # type: () -> None + logger.info( bold('dumping search index in %s ... ' % self.indexer.label()), nonl=True) self.indexer.prune(self.env.all_docs) @@ -880,13 +924,13 @@ class StandaloneHTMLBuilder(Builder): # first write to a temporary file, so that if dumping fails, # the existing index won't be overwritten if self.indexer_dumps_unicode: - f = codecs.open(searchindexfn + '.tmp', 'w', encoding='utf-8') + f = codecs.open(searchindexfn + '.tmp', 'w', encoding='utf-8') # type: ignore else: - f = open(searchindexfn + '.tmp', 'wb') + f = open(searchindexfn + '.tmp', 'wb') # type: ignore with f: - self.indexer.dump(f, self.indexer_format) + self.indexer.dump(f, self.indexer_format) # type: ignore movefile(searchindexfn + '.tmp', searchindexfn) - self.info('done') + logger.info('done') class DirectoryHTMLBuilder(StandaloneHTMLBuilder): @@ -898,6 +942,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder): name = 'dirhtml' def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if docname == 'index': return '' if docname.endswith(SEP + 'index'): @@ -905,6 +950,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder): return docname + SEP def get_outfilename(self, pagename): + # type: (unicode) -> unicode if pagename == 'index' or pagename.endswith(SEP + 'index'): outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) @@ -915,6 +961,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder): return outfilename def prepare_writing(self, docnames): + # type: (Iterable[unicode]) -> None StandaloneHTMLBuilder.prepare_writing(self, docnames) self.globalcontext['no_search_suffix'] = True @@ -927,10 +974,12 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): name = 'singlehtml' copysource = False - def get_outdated_docs(self): + def get_outdated_docs(self): # type: ignore + # type: () -> Union[unicode, List[unicode]] return 'all documents' def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if docname in self.env.all_docs: # all references are on the same page... return self.config.master_doc + self.out_suffix + \ @@ -940,10 +989,12 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return docname + self.out_suffix def get_relative_uri(self, from_, to, typ=None): + # type: (unicode, unicode, unicode) -> unicode # ignore source return self.get_target_uri(to, typ) def fix_refuris(self, tree): + # type: (nodes.Node) -> None # fix refuris with double anchor fname = self.config.master_doc + self.out_suffix for refnode in tree.traverse(nodes.reference): @@ -958,6 +1009,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): refnode['refuri'] = fname + refuri[hashindex:] def _get_local_toctree(self, docname, collapse=True, **kwds): + # type: (unicode, bool, Any) -> unicode if 'includehidden' not in kwds: kwds['includehidden'] = False toctree = self.env.get_toctree_for(docname, self, collapse, **kwds) @@ -965,6 +1017,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return self.render_partial(toctree)['fragment'] def assemble_doctree(self): + # type: () -> nodes.Node master = self.config.master_doc tree = self.env.get_doctree(master) tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master]) @@ -974,6 +1027,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return tree def assemble_toc_secnumbers(self): + # type: () -> Dict[unicode, Dict[Tuple[unicode, unicode], Tuple[int, ...]]] # Assemble toc_secnumbers to resolve section numbers on SingleHTML. # Merge all secnumbers to single secnumber. # @@ -991,6 +1045,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return {self.config.master_doc: new_secnumbers} def assemble_toc_fignumbers(self): + # type: () -> Dict[unicode, Dict[Tuple[unicode, unicode], Dict[unicode, Tuple[int, ...]]]] # NOQA # Assemble toc_fignumbers to resolve figure numbers on SingleHTML. # Merge all fignumbers to single fignumber. # @@ -1000,7 +1055,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): # # There are related codes in inline_all_toctres() and # HTMLTranslter#add_fignumber(). - new_fignumbers = {} + new_fignumbers = {} # type: Dict[Tuple[unicode, unicode], Dict[unicode, Tuple[int, ...]]] # NOQA # {u'foo': {'figure': {'id2': (2,), 'id1': (1,)}}, u'bar': {'figure': {'id1': (3,)}}} for docname, fignumlist in iteritems(self.env.toc_fignumbers): for figtype, fignums in iteritems(fignumlist): @@ -1011,8 +1066,9 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return {self.config.master_doc: new_fignumbers} def get_doc_context(self, docname, body, metatags): + # type: (unicode, unicode, Dict) -> Dict # no relation links... - toc = self.env.get_toctree_for(self.config.master_doc, self, False) + toc = self.env.get_toctree_for(self.config.master_doc, self, False) # type: Any # if there is no toctree, toc is None if toc: self.fix_refuris(toc) @@ -1037,37 +1093,39 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): ) def write(self, *ignored): + # type: (Any) -> None docnames = self.env.all_docs - self.info(bold('preparing documents... '), nonl=True) + logger.info(bold('preparing documents... '), nonl=True) self.prepare_writing(docnames) - self.info('done') + logger.info('done') - self.info(bold('assembling single document... '), nonl=True) + logger.info(bold('assembling single document... '), nonl=True) doctree = self.assemble_doctree() self.env.toc_secnumbers = self.assemble_toc_secnumbers() self.env.toc_fignumbers = self.assemble_toc_fignumbers() - self.info() - self.info(bold('writing... '), nonl=True) + logger.info('') + logger.info(bold('writing... '), nonl=True) self.write_doc_serialized(self.config.master_doc, doctree) self.write_doc(self.config.master_doc, doctree) - self.info('done') + logger.info('done') def finish(self): + # type: () -> None # no indices or search pages are supported - self.info(bold('writing additional files...'), nonl=1) + logger.info(bold('writing additional files...'), nonl=1) # additional pages from conf.py for pagename, template in self.config.html_additional_pages.items(): - self.info(' '+pagename, nonl=1) + logger.info(' '+pagename, nonl=1) self.handle_page(pagename, {}, template) if self.config.html_use_opensearch: - self.info(' opensearch', nonl=1) + logger.info(' opensearch', nonl=1) fn = path.join(self.outdir, '_static', 'opensearch.xml') self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - self.info() + logger.info('') self.copy_image_files() self.copy_download_files() @@ -1084,18 +1142,19 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): #: the serializing implementation to use. Set this to a module that #: implements a `dump`, `load`, `dumps` and `loads` functions #: (pickle, simplejson etc.) - implementation = None + implementation = None # type: Any implementation_dumps_unicode = False #: additional arguments for dump() additional_dump_args = () #: the filename for the global context file - globalcontext_filename = None + globalcontext_filename = None # type: unicode supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg'] def init(self): + # type: () -> None self.config_hash = '' self.tags_hash = '' self.imagedir = '_images' @@ -1108,6 +1167,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): self.use_index = self.get_builder_config('use_index', 'html') def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if docname == 'index': return '' if docname.endswith(SEP + 'index'): @@ -1115,15 +1175,17 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): return docname + SEP def dump_context(self, context, filename): + # type: (Dict, unicode) -> None if self.implementation_dumps_unicode: - f = codecs.open(filename, 'w', encoding='utf-8') + f = codecs.open(filename, 'w', encoding='utf-8') # type: ignore else: - f = open(filename, 'wb') + f = open(filename, 'wb') # type: ignore with f: self.implementation.dump(context, f, *self.additional_dump_args) def handle_page(self, pagename, ctx, templatename='page.html', outfilename=None, event_arg=None): + # type: (unicode, Dict, unicode, unicode, Any) -> None ctx['current_page_name'] = pagename self.add_sidebars(pagename, ctx) @@ -1147,6 +1209,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): copyfile(self.env.doc2path(pagename), source_name) def handle_finish(self): + # type: () -> None # dump the global context outfilename = path.join(self.outdir, self.globalcontext_filename) self.dump_context(self.globalcontext, outfilename) @@ -1197,16 +1260,12 @@ class JSONHTMLBuilder(SerializingHTMLBuilder): searchindex_filename = 'searchindex.json' def init(self): + # type: () -> None SerializingHTMLBuilder.init(self) -def validate_config_values(app): - if app.config.html_translator_class: - app.warn('html_translator_class is deprecated. ' - 'Use Sphinx.set_translator() API instead.') - - def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] # builders app.add_builder(StandaloneHTMLBuilder) app.add_builder(DirectoryHTMLBuilder) @@ -1214,8 +1273,6 @@ def setup(app): app.add_builder(PickleHTMLBuilder) app.add_builder(JSONHTMLBuilder) - app.connect('builder-inited', validate_config_values) - # config values app.add_config_value('html_theme', 'alabaster', 'html') app.add_config_value('html_theme_path', [], 'html') @@ -1233,7 +1290,6 @@ def setup(app): app.add_config_value('html_use_smartypants', True, 'html') app.add_config_value('html_sidebars', {}, 'html') app.add_config_value('html_additional_pages', {}, 'html') - app.add_config_value('html_use_modindex', True, 'html') # deprecated app.add_config_value('html_domain_indices', True, 'html', [list]) app.add_config_value('html_add_permalinks', u'\u00B6', 'html') app.add_config_value('html_use_index', True, 'html') diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 79268ab74..852700123 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -18,11 +18,15 @@ from os import path from docutils import nodes from sphinx import addnodes -from sphinx.util.osutil import make_filename from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.util import logging +from sphinx.util.osutil import make_filename from sphinx.util.pycompat import htmlescape +logger = logging.getLogger(__name__) + + # Project file (*.hhp) template. 'outname' is the file basename (like # the pythlp in pythlp.hhp); 'version' is the doc version number (like # the 2.2 in Python 2.2). @@ -195,6 +199,9 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): return codecs.open(path.join(outdir, basename), mode, self.encoding, 'xmlcharrefreplace') + def update_page_context(self, pagename, templatename, ctx, event_arg): + ctx['encoding'] = self.encoding + def handle_finish(self): self.build_hhx(self.outdir, self.config.htmlhelp_basename) @@ -207,12 +214,12 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): StandaloneHTMLBuilder.write_doc(self, docname, doctree) def build_hhx(self, outdir, outname): - self.info('dumping stopword list...') + logger.info('dumping stopword list...') with self.open_file(outdir, outname+'.stp') as f: for word in sorted(stopwords): print(word, file=f) - self.info('writing project file...') + logger.info('writing project file...') with self.open_file(outdir, outname+'.hhp') as f: f.write(project_template % { 'outname': outname, @@ -233,7 +240,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): print(path.join(root, fn)[olen:].replace(os.sep, '\\'), file=f) - self.info('writing TOC file...') + logger.info('writing TOC file...') with self.open_file(outdir, outname+'.hhc') as f: f.write(contents_header) # special books @@ -273,7 +280,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): write_toc(node) f.write(contents_footer) - self.info('writing index file...') + logger.info('writing index file...') index = self.env.create_index(self) with self.open_file(outdir, outname+'.hhk') as f: f.write('<UL>\n') diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index bfd002be5..d77fb999a 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -13,13 +13,14 @@ import os from os import path from six import iteritems + from docutils import nodes from docutils.io import FileOutput from docutils.utils import new_document from docutils.frontend import OptionParser from sphinx import package_dir, addnodes, highlighting -from sphinx.util import texescape +from sphinx.util import texescape, logging from sphinx.config import string_classes, ENUM from sphinx.errors import SphinxError from sphinx.locale import _ @@ -28,9 +29,17 @@ from sphinx.environment import NoUri from sphinx.util.nodes import inline_all_toctrees from sphinx.util.fileutil import copy_asset_file from sphinx.util.osutil import SEP, make_filename -from sphinx.util.console import bold, darkgreen +from sphinx.util.console import bold, darkgreen # type: ignore from sphinx.writers.latex import LaTeXWriter +if False: + # For type annotation + from typing import Any, Iterable, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) + class LaTeXBuilder(Builder): """ @@ -41,44 +50,50 @@ class LaTeXBuilder(Builder): supported_image_types = ['application/pdf', 'image/png', 'image/jpeg'] def init(self): - self.docnames = [] - self.document_data = [] - self.usepackages = [] + # type: () -> None + self.docnames = [] # type: Iterable[unicode] + self.document_data = [] # type: List[Tuple[unicode, unicode, unicode, unicode, unicode, bool]] # NOQA + self.usepackages = [] # type: List[unicode] texescape.init() def get_outdated_docs(self): + # type: () -> Union[unicode, List[unicode]] return 'all documents' # for now def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if docname not in self.docnames: raise NoUri else: return '%' + docname def get_relative_uri(self, from_, to, typ=None): + # type: (unicode, unicode, unicode) -> unicode # ignore source path return self.get_target_uri(to, typ) def init_document_data(self): + # type: () -> None preliminary_document_data = [list(x) for x in self.config.latex_documents] if not preliminary_document_data: - self.warn('no "latex_documents" config value found; no documents ' - 'will be written') + logger.warning('no "latex_documents" config value found; no documents ' + 'will be written') return # assign subdirs to titles - self.titles = [] + self.titles = [] # type: List[Tuple[unicode, unicode]] for entry in preliminary_document_data: docname = entry[0] if docname not in self.env.all_docs: - self.warn('"latex_documents" config value references unknown ' - 'document %s' % docname) + logger.warning('"latex_documents" config value references unknown ' + 'document %s', docname) continue - self.document_data.append(entry) + self.document_data.append(entry) # type: ignore if docname.endswith(SEP+'index'): docname = docname[:-5] self.titles.append((docname, entry[2])) def write_stylesheet(self): + # type: () -> None highlighter = highlighting.PygmentsBridge( 'latex', self.config.pygments_style, self.config.trim_doctest_flags) stylesheet = path.join(self.outdir, 'sphinxhighlight.sty') @@ -89,6 +104,7 @@ class LaTeXBuilder(Builder): f.write(highlighter.get_stylesheet()) def write(self, *ignored): + # type: (Any) -> None docwriter = LaTeXWriter(self) docsettings = OptionParser( defaults=self.env.settings, @@ -106,7 +122,7 @@ class LaTeXBuilder(Builder): destination = FileOutput( destination_path=path.join(self.outdir, targetname), encoding='utf-8') - self.info("processing " + targetname + "... ", nonl=1) + logger.info("processing %s...", targetname, nonl=1) toctrees = self.env.get_doctree(docname).traverse(addnodes.toctree) if toctrees: if toctrees[0].get('maxdepth') > 0: @@ -120,7 +136,7 @@ class LaTeXBuilder(Builder): appendices=((docclass != 'howto') and self.config.latex_appendices or [])) doctree['tocdepth'] = tocdepth self.post_process_images(doctree) - self.info("writing... ", nonl=1) + logger.info("writing... ", nonl=1) doctree.settings = docsettings doctree.settings.author = author doctree.settings.title = title @@ -128,9 +144,10 @@ class LaTeXBuilder(Builder): doctree.settings.docname = docname doctree.settings.docclass = docclass docwriter.write(doctree, destination) - self.info("done") + logger.info("done") def get_contentsname(self, indexfile): + # type: (unicode) -> unicode tree = self.env.get_doctree(indexfile) contentsname = None for toctree in tree.traverse(addnodes.toctree): @@ -141,8 +158,9 @@ class LaTeXBuilder(Builder): return contentsname def assemble_doctree(self, indexfile, toctree_only, appendices): + # type: (unicode, bool, List[unicode]) -> nodes.Node self.docnames = set([indexfile] + appendices) - self.info(darkgreen(indexfile) + " ", nonl=1) + logger.info(darkgreen(indexfile) + " ", nonl=1) tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: @@ -163,8 +181,8 @@ class LaTeXBuilder(Builder): appendix = self.env.get_doctree(docname) appendix['docname'] = docname largetree.append(appendix) - self.info() - self.info("resolving references...") + logger.info('') + logger.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) # resolve :ref:s to distant tex files -- we can't add a cross-reference, # but append the document name @@ -184,18 +202,19 @@ class LaTeXBuilder(Builder): return largetree def finish(self): + # type: () -> None # copy image files if self.images: - self.info(bold('copying images...'), nonl=1) + logger.info(bold('copying images...'), nonl=1) for src, dest in iteritems(self.images): - self.info(' '+src, nonl=1) + logger.info(' '+src, nonl=1) copy_asset_file(path.join(self.srcdir, src), path.join(self.outdir, dest)) - self.info() + logger.info('') # copy TeX support files from texinputs context = {'latex_engine': self.config.latex_engine} - self.info(bold('copying TeX support files...')) + logger.info(bold('copying TeX support files...')) staticdirname = path.join(package_dir, 'texinputs') for filename in os.listdir(staticdirname): if not filename.startswith('.'): @@ -204,11 +223,11 @@ class LaTeXBuilder(Builder): # copy additional files if self.config.latex_additional_files: - self.info(bold('copying additional files...'), nonl=1) + logger.info(bold('copying additional files...'), nonl=1) for filename in self.config.latex_additional_files: - self.info(' '+filename, nonl=1) + logger.info(' '+filename, nonl=1) copy_asset_file(path.join(self.confdir, filename), self.outdir) - self.info() + logger.info('') # the logo is handled differently if self.config.latex_logo: @@ -216,55 +235,23 @@ class LaTeXBuilder(Builder): raise SphinxError('logo file %r does not exist' % self.config.latex_logo) else: copy_asset_file(path.join(self.confdir, self.config.latex_logo), self.outdir) - self.info('done') + logger.info('done') def validate_config_values(app): + # type: (Sphinx) -> None if app.config.latex_toplevel_sectioning not in (None, 'part', 'chapter', 'section'): - app.warn('invalid latex_toplevel_sectioning, ignored: %s' % - app.config.latex_toplevel_sectioning) - app.config.latex_toplevel_sectioning = None - - if app.config.latex_use_parts: - if app.config.latex_toplevel_sectioning: - app.warn('latex_use_parts conflicts with latex_toplevel_sectioning, ignored.') - else: - app.warn('latex_use_parts is deprecated. Use latex_toplevel_sectioning instead.') - app.config.latex_toplevel_sectioning = 'part' - - if app.config.latex_use_modindex is not True: # changed by user - app.warn('latex_use_modindex is deprecated. Use latex_domain_indices instead.') - - if app.config.latex_preamble: - if app.config.latex_elements.get('preamble'): - app.warn("latex_preamble conflicts with latex_elements['preamble'], ignored.") - else: - app.warn("latex_preamble is deprecated. Use latex_elements['preamble'] instead.") - app.config.latex_elements['preamble'] = app.config.latex_preamble - - if app.config.latex_paper_size != 'letter': - if app.config.latex_elements.get('papersize'): - app.warn("latex_paper_size conflicts with latex_elements['papersize'], ignored.") - else: - app.warn("latex_paper_size is deprecated. " - "Use latex_elements['papersize'] instead.") - if app.config.latex_paper_size: - app.config.latex_elements['papersize'] = app.config.latex_paper_size + 'paper' - - if app.config.latex_font_size != '10pt': - if app.config.latex_elements.get('pointsize'): - app.warn("latex_font_size conflicts with latex_elements['pointsize'], ignored.") - else: - app.warn("latex_font_size is deprecated. Use latex_elements['pointsize'] instead.") - app.config.latex_elements['pointsize'] = app.config.latex_font_size + logger.warning('invalid latex_toplevel_sectioning, ignored: %s', + app.config.latex_toplevel_sectioning) + app.config.latex_toplevel_sectioning = None # type: ignore if 'footer' in app.config.latex_elements: if 'postamble' in app.config.latex_elements: - app.warn("latex_elements['footer'] conflicts with " - "latex_elements['postamble'], ignored.") + logger.warning("latex_elements['footer'] conflicts with " + "latex_elements['postamble'], ignored.") else: - app.warn("latex_elements['footer'] is deprecated. " - "Use latex_elements['preamble'] instead.") + logger.warning("latex_elements['footer'] is deprecated. " + "Use latex_elements['preamble'] instead.") app.config.latex_elements['postamble'] = app.config.latex_elements['footer'] @@ -286,6 +273,7 @@ def default_latex_docclass(config): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(LaTeXBuilder) app.connect('builder-inited', validate_config_values) @@ -298,23 +286,14 @@ def setup(app): app.add_config_value('latex_logo', None, None, string_classes) app.add_config_value('latex_appendices', [], None) app.add_config_value('latex_keep_old_macro_names', True, None) - # now deprecated - use latex_toplevel_sectioning - app.add_config_value('latex_use_parts', False, None) app.add_config_value('latex_toplevel_sectioning', None, None, [str]) - app.add_config_value('latex_use_modindex', True, None) # deprecated app.add_config_value('latex_domain_indices', True, None, [list]) app.add_config_value('latex_show_urls', 'no', None) app.add_config_value('latex_show_pagerefs', False, None) - # paper_size and font_size are still separate values - # so that you can give them easily on the command line - app.add_config_value('latex_paper_size', 'letter', None) - app.add_config_value('latex_font_size', '10pt', None) app.add_config_value('latex_elements', {}, None) app.add_config_value('latex_additional_files', [], None) app.add_config_value('latex_docclass', default_latex_docclass, None) - # now deprecated - use latex_elements - app.add_config_value('latex_preamble', '', None) return { 'version': 'builtin', diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index 3ca13d023..d9e5d5696 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -16,7 +16,7 @@ import threading from os import path from requests.exceptions import HTTPError -from six.moves import queue +from six.moves import queue # type: ignore from six.moves.urllib.parse import unquote from six.moves.html_parser import HTMLParser from docutils import nodes @@ -26,28 +26,40 @@ from docutils import nodes # going to just remove it. If it doesn't exist, define an exception that will # never be caught but leaves the code in check_anchor() intact. try: - from six.moves.html_parser import HTMLParseError + from six.moves.html_parser import HTMLParseError # type: ignore except ImportError: - class HTMLParseError(Exception): + class HTMLParseError(Exception): # type: ignore pass from sphinx.builders import Builder -from sphinx.util import encode_uri, requests -from sphinx.util.console import purple, red, darkgreen, darkgray, \ - darkred, turquoise +from sphinx.util import encode_uri, requests, logging +from sphinx.util.console import ( # type: ignore + purple, red, darkgreen, darkgray, darkred, turquoise +) from sphinx.util.requests import is_ssl_error +if False: + # For type annotation + from typing import Any, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.util.requests.requests import Response # NOQA + + +logger = logging.getLogger(__name__) + class AnchorCheckParser(HTMLParser): """Specialized HTML parser that looks for a specific anchor.""" def __init__(self, search_anchor): + # type: (unicode) -> None HTMLParser.__init__(self) self.search_anchor = search_anchor self.found = False def handle_starttag(self, tag, attrs): + # type: (Any, Dict[unicode, unicode]) -> None for key, value in attrs: if key in ('id', 'name') and value == self.search_anchor: self.found = True @@ -55,6 +67,7 @@ class AnchorCheckParser(HTMLParser): def check_anchor(response, anchor): + # type: (Response, unicode) -> bool """Reads HTML data from a response object `response` searching for `anchor`. Returns True if anchor was found, False otherwise. """ @@ -81,12 +94,13 @@ class CheckExternalLinksBuilder(Builder): name = 'linkcheck' def init(self): + # type: () -> None self.to_ignore = [re.compile(x) for x in self.app.config.linkcheck_ignore] self.anchors_ignore = [re.compile(x) for x in self.app.config.linkcheck_anchors_ignore] - self.good = set() - self.broken = {} - self.redirected = {} + self.good = set() # type: Set[unicode] + self.broken = {} # type: Dict[unicode, unicode] + self.redirected = {} # type: Dict[unicode, Tuple[unicode, int]] # set a timeout for non-responding servers socket.setdefaulttimeout(5.0) # create output file @@ -95,7 +109,7 @@ class CheckExternalLinksBuilder(Builder): # create queues and worker threads self.wqueue = queue.Queue() self.rqueue = queue.Queue() - self.workers = [] + self.workers = [] # type: List[threading.Thread] for i in range(self.app.config.linkcheck_workers): thread = threading.Thread(target=self.check_thread) thread.setDaemon(True) @@ -103,6 +117,7 @@ class CheckExternalLinksBuilder(Builder): self.workers.append(thread) def check_thread(self): + # type: () -> None kwargs = {} if self.app.config.linkcheck_timeout: kwargs['timeout'] = self.app.config.linkcheck_timeout @@ -110,6 +125,7 @@ class CheckExternalLinksBuilder(Builder): kwargs['allow_redirects'] = True def check_uri(): + # type: () -> Tuple[unicode, unicode, int] # split off anchor if '#' in uri: req_url, anchor = uri.split('#', 1) @@ -171,6 +187,7 @@ class CheckExternalLinksBuilder(Builder): return 'redirected', new_url, code def check(): + # type: () -> Tuple[unicode, unicode, int] # check for various conditions without bothering the network if len(uri) == 0 or uri.startswith(('#', 'mailto:', 'ftp:')): return 'unchecked', '', 0 @@ -209,30 +226,31 @@ class CheckExternalLinksBuilder(Builder): self.rqueue.put((uri, docname, lineno, status, info, code)) def process_result(self, result): + # type: (Tuple[unicode, unicode, int, unicode, unicode, int]) -> None uri, docname, lineno, status, info, code = result if status == 'unchecked': return if status == 'working' and info == 'old': return if lineno: - self.info('(line %4d) ' % lineno, nonl=1) + logger.info('(line %4d) ', lineno, nonl=1) if status == 'ignored': if info: - self.info(darkgray('-ignored- ') + uri + ': ' + info) + logger.info(darkgray('-ignored- ') + uri + ': ' + info) else: - self.info(darkgray('-ignored- ') + uri) + logger.info(darkgray('-ignored- ') + uri) elif status == 'local': - self.info(darkgray('-local- ') + uri) + logger.info(darkgray('-local- ') + uri) self.write_entry('local', docname, lineno, uri) elif status == 'working': - self.info(darkgreen('ok ') + uri + info) + logger.info(darkgreen('ok ') + uri + info) elif status == 'broken': self.write_entry('broken', docname, lineno, uri + ': ' + info) if self.app.quiet or self.app.warningiserror: - self.warn('broken link: %s (%s)' % (uri, info), - '%s:%s' % (self.env.doc2path(docname), lineno)) + logger.warning('broken link: %s (%s)', uri, info, + location=(self.env.doc2path(docname), lineno)) else: - self.info(red('broken ') + uri + red(' - ' + info)) + logger.info(red('broken ') + uri + red(' - ' + info)) elif status == 'redirected': text, color = { 301: ('permanently', darkred), @@ -243,19 +261,23 @@ class CheckExternalLinksBuilder(Builder): }[code] self.write_entry('redirected ' + text, docname, lineno, uri + ' to ' + info) - self.info(color('redirect ') + uri + color(' - ' + text + ' to ' + info)) + logger.info(color('redirect ') + uri + color(' - ' + text + ' to ' + info)) def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode return '' def get_outdated_docs(self): + # type: () -> Set[unicode] return self.env.found_docs def prepare_writing(self, docnames): + # type: (nodes.Node) -> None return def write_doc(self, docname, doctree): - self.info() + # type: (unicode, nodes.Node) -> None + logger.info('') n = 0 for node in doctree.traverse(nodes.reference): if 'refuri' not in node: @@ -278,17 +300,19 @@ class CheckExternalLinksBuilder(Builder): self.app.statuscode = 1 def write_entry(self, what, docname, line, uri): - output = codecs.open(path.join(self.outdir, 'output.txt'), 'a', 'utf-8') - output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), - line, what, uri)) - output.close() + # type: (unicode, unicode, int, unicode) -> None + with codecs.open(path.join(self.outdir, 'output.txt'), 'a', 'utf-8') as output: # type: ignore # NOQA + output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), + line, what, uri)) def finish(self): + # type: () -> None for worker in self.workers: self.wqueue.put((None, None, None), False) def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(CheckExternalLinksBuilder) app.add_config_value('linkcheck_ignore', [], None) diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py index 7b2fcf1d8..20034b3f8 100644 --- a/sphinx/builders/manpage.py +++ b/sphinx/builders/manpage.py @@ -12,17 +12,27 @@ from os import path from six import string_types + from docutils.io import FileOutput from docutils.frontend import OptionParser from sphinx import addnodes from sphinx.builders import Builder from sphinx.environment import NoUri +from sphinx.util import logging from sphinx.util.nodes import inline_all_toctrees from sphinx.util.osutil import make_filename -from sphinx.util.console import bold, darkgreen +from sphinx.util.console import bold, darkgreen # type: ignore from sphinx.writers.manpage import ManualPageWriter +if False: + # For type annotation + from typing import Any, Union # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) + class ManualPageBuilder(Builder): """ @@ -30,29 +40,33 @@ class ManualPageBuilder(Builder): """ name = 'man' format = 'man' - supported_image_types = [] + supported_image_types = [] # type: List[unicode] def init(self): + # type: () -> None if not self.config.man_pages: - self.warn('no "man_pages" config value found; no manual pages ' - 'will be written') + logger.warning('no "man_pages" config value found; no manual pages ' + 'will be written') def get_outdated_docs(self): + # type: () -> Union[unicode, List[unicode]] return 'all manpages' # for now def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if typ == 'token': return '' raise NoUri def write(self, *ignored): + # type: (Any) -> None docwriter = ManualPageWriter(self) docsettings = OptionParser( defaults=self.env.settings, components=(docwriter,), read_config_files=True).get_default_values() - self.info(bold('writing... '), nonl=True) + logger.info(bold('writing... '), nonl=True) for info in self.config.man_pages: docname, name, description, authors, section = info @@ -63,16 +77,16 @@ class ManualPageBuilder(Builder): authors = [] targetname = '%s.%s' % (name, section) - self.info(darkgreen(targetname) + ' { ', nonl=True) + logger.info(darkgreen(targetname) + ' { ', nonl=True) destination = FileOutput( destination_path=path.join(self.outdir, targetname), encoding='utf-8') tree = self.env.get_doctree(docname) - docnames = set() + docnames = set() # type: Set[unicode] largetree = inline_all_toctrees(self, docnames, docname, tree, darkgreen, [docname]) - self.info('} ', nonl=True) + logger.info('} ', nonl=True) self.env.resolve_references(largetree, docname, self) # remove pending_xref nodes for pendingnode in largetree.traverse(addnodes.pending_xref): @@ -85,13 +99,15 @@ class ManualPageBuilder(Builder): largetree.settings.section = section docwriter.write(largetree, destination) - self.info() + logger.info('') def finish(self): + # type: () -> None pass def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(ManualPageBuilder) app.add_config_value('man_pages', diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 23bc24ce8..6ed9c6b7e 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -16,14 +16,23 @@ import posixpath from os import path from six import text_type + from docutils import nodes from sphinx import addnodes from sphinx.builders.html import StandaloneHTMLBuilder -from sphinx.util import force_decode +from sphinx.util import force_decode, logging from sphinx.util.osutil import make_filename from sphinx.util.pycompat import htmlescape +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + + +logger = logging.getLogger(__name__) + _idpattern = re.compile( r'(?P<title>.+) (\((class in )?(?P<id>[\w\.]+)( (?P<descr>\w+))?\))$') @@ -115,6 +124,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): search = False def init(self): + # type: () -> None StandaloneHTMLBuilder.init(self) # the output files for HTML help must be .html only self.out_suffix = '.html' @@ -122,13 +132,16 @@ class QtHelpBuilder(StandaloneHTMLBuilder): # self.config.html_style = 'traditional.css' def get_theme_config(self): + # type: () -> Tuple[unicode, Dict] return self.config.qthelp_theme, self.config.qthelp_theme_options def handle_finish(self): + # type: () -> None self.build_qhp(self.outdir, self.config.qthelp_basename) def build_qhp(self, outdir, outname): - self.info('writing project file...') + # type: (unicode, unicode) -> None + logger.info('writing project file...') # sections tocdoc = self.env.get_and_resolve_doctree(self.config.master_doc, self, @@ -153,7 +166,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): new_sections.append(force_decode(section, None)) else: new_sections.append(section) - sections = u'\n'.join(new_sections) + sections = u'\n'.join(new_sections) # type: ignore # keywords keywords = [] @@ -161,7 +174,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): for (key, group) in index: for title, (refs, subitems, key_) in group: keywords.extend(self.build_keywords(title, refs, subitems)) - keywords = u'\n'.join(keywords) + keywords = u'\n'.join(keywords) # type: ignore # files if not outdir.endswith(os.sep): @@ -179,7 +192,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): filename = path.join(root, fn)[olen:] projectfiles.append(file_template % {'filename': htmlescape(filename)}) - projectfiles = '\n'.join(projectfiles) + projectfiles = '\n'.join(projectfiles) # type: ignore # it seems that the "namespace" may not contain non-alphanumeric # characters, and more than one successive dot, or leading/trailing @@ -190,8 +203,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): nspace = nspace.lower() # write the project file - with codecs.open(path.join(outdir, outname+'.qhp'), 'w', 'utf-8') as f: - f.write(project_template % { + with codecs.open(path.join(outdir, outname+'.qhp'), 'w', 'utf-8') as f: # type: ignore + f.write(project_template % { # type: ignore 'outname': htmlescape(outname), 'title': htmlescape(self.config.html_title), 'version': htmlescape(self.config.version), @@ -206,15 +219,16 @@ class QtHelpBuilder(StandaloneHTMLBuilder): nspace, 'doc', self.get_target_uri(self.config.master_doc)) startpage = 'qthelp://' + posixpath.join(nspace, 'doc', 'index.html') - self.info('writing collection project file...') - with codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8') as f: - f.write(collection_template % { + logger.info('writing collection project file...') + with codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8') as f: # type: ignore # NOQA + f.write(collection_template % { # type: ignore 'outname': htmlescape(outname), 'title': htmlescape(self.config.html_short_title), 'homepage': htmlescape(homepage), 'startpage': htmlescape(startpage)}) def isdocnode(self, node): + # type: (nodes.Node) -> bool if not isinstance(node, nodes.list_item): return False if len(node.children) != 2: @@ -228,8 +242,9 @@ class QtHelpBuilder(StandaloneHTMLBuilder): return True def write_toc(self, node, indentlevel=4): + # type: (nodes.Node, int) -> List[unicode] # XXX this should return a Unicode string, not a bytestring - parts = [] + parts = [] # type: List[unicode] if self.isdocnode(node): refnode = node.children[0][0] link = refnode['refuri'] @@ -247,7 +262,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): link = node['refuri'] title = htmlescape(node.astext()).replace('"', '"') item = section_template % {'title': title, 'ref': link} - item = u' ' * 4 * indentlevel + item + item = u' ' * 4 * indentlevel + item # type: ignore parts.append(item.encode('ascii', 'xmlcharrefreplace')) elif isinstance(node, nodes.bullet_list): for subnode in node: @@ -259,7 +274,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): return parts def keyword_item(self, name, ref): - matchobj = _idpattern.match(name) + # type: (unicode, Any) -> unicode + matchobj = _idpattern.match(name) # type: ignore if matchobj: groupdict = matchobj.groupdict() shortname = groupdict['title'] @@ -280,7 +296,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): return item def build_keywords(self, title, refs, subitems): - keywords = [] + # type: (unicode, List[Any], Any) -> List[unicode] + keywords = [] # type: List[unicode] title = htmlescape(title) # if len(refs) == 0: # XXX @@ -304,6 +321,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.setup_extension('sphinx.builders.html') app.add_builder(QtHelpBuilder) diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py index cdba3df55..804fd9587 100644 --- a/sphinx/builders/texinfo.py +++ b/sphinx/builders/texinfo.py @@ -12,6 +12,7 @@ from os import path from six import iteritems + from docutils import nodes from docutils.io import FileOutput from docutils.utils import new_document @@ -21,11 +22,19 @@ from sphinx import addnodes from sphinx.locale import _ from sphinx.builders import Builder from sphinx.environment import NoUri +from sphinx.util import logging from sphinx.util.nodes import inline_all_toctrees from sphinx.util.osutil import SEP, copyfile, make_filename -from sphinx.util.console import bold, darkgreen +from sphinx.util.console import bold, darkgreen # type: ignore from sphinx.writers.texinfo import TexinfoWriter +if False: + # For type annotation + from sphinx.application import Sphinx # NOQA + from typing import Any, Iterable, Tuple, Union # NOQA + + +logger = logging.getLogger(__name__) TEXINFO_MAKEFILE = '''\ # Makefile for Sphinx Texinfo output @@ -91,47 +100,53 @@ class TexinfoBuilder(Builder): 'image/gif'] def init(self): - self.docnames = [] - self.document_data = [] + # type: () -> None + self.docnames = [] # type: Iterable[unicode] + self.document_data = [] # type: List[Tuple[unicode, unicode, unicode, unicode, unicode, unicode, unicode, bool]] # NOQA def get_outdated_docs(self): + # type: () -> Union[unicode, List[unicode]] return 'all documents' # for now def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode if docname not in self.docnames: raise NoUri else: return '%' + docname def get_relative_uri(self, from_, to, typ=None): + # type: (unicode, unicode, unicode) -> unicode # ignore source path return self.get_target_uri(to, typ) def init_document_data(self): + # type: () -> None preliminary_document_data = [list(x) for x in self.config.texinfo_documents] if not preliminary_document_data: - self.warn('no "texinfo_documents" config value found; no documents ' - 'will be written') + logger.warning('no "texinfo_documents" config value found; no documents ' + 'will be written') return # assign subdirs to titles - self.titles = [] + self.titles = [] # type: List[Tuple[unicode, unicode]] for entry in preliminary_document_data: docname = entry[0] if docname not in self.env.all_docs: - self.warn('"texinfo_documents" config value references unknown ' - 'document %s' % docname) + logger.warning('"texinfo_documents" config value references unknown ' + 'document %s', docname) continue - self.document_data.append(entry) + self.document_data.append(entry) # type: ignore if docname.endswith(SEP+'index'): docname = docname[:-5] self.titles.append((docname, entry[2])) def write(self, *ignored): + # type: (Any) -> None self.init_document_data() for entry in self.document_data: docname, targetname, title, author = entry[:4] targetname += '.texi' - direntry = description = category = '' + direntry = description = category = '' # type: unicode if len(entry) > 6: direntry, description, category = entry[4:7] toctree_only = False @@ -140,11 +155,11 @@ class TexinfoBuilder(Builder): destination = FileOutput( destination_path=path.join(self.outdir, targetname), encoding='utf-8') - self.info("processing " + targetname + "... ", nonl=1) + logger.info("processing " + targetname + "... ", nonl=1) doctree = self.assemble_doctree( docname, toctree_only, appendices=(self.config.texinfo_appendices or [])) - self.info("writing... ", nonl=1) + logger.info("writing... ", nonl=1) self.post_process_images(doctree) docwriter = TexinfoWriter(self) settings = OptionParser( @@ -161,11 +176,12 @@ class TexinfoBuilder(Builder): settings.docname = docname doctree.settings = settings docwriter.write(doctree, destination) - self.info("done") + logger.info("done") def assemble_doctree(self, indexfile, toctree_only, appendices): + # type: (unicode, bool, List[unicode]) -> nodes.Node self.docnames = set([indexfile] + appendices) - self.info(darkgreen(indexfile) + " ", nonl=1) + logger.info(darkgreen(indexfile) + " ", nonl=1) tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: @@ -186,8 +202,8 @@ class TexinfoBuilder(Builder): appendix = self.env.get_doctree(docname) appendix['docname'] = docname largetree.append(appendix) - self.info() - self.info("resolving references...") + logger.info('') + logger.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) # TODO: add support for external :ref:s for pendingnode in largetree.traverse(addnodes.pending_xref): @@ -206,28 +222,30 @@ class TexinfoBuilder(Builder): return largetree def finish(self): + # type: () -> None # copy image files if self.images: - self.info(bold('copying images...'), nonl=1) + logger.info(bold('copying images...'), nonl=1) for src, dest in iteritems(self.images): - self.info(' '+src, nonl=1) + logger.info(' '+src, nonl=1) copyfile(path.join(self.srcdir, src), path.join(self.outdir, dest)) - self.info() + logger.info('') - self.info(bold('copying Texinfo support files... '), nonl=True) + logger.info(bold('copying Texinfo support files... '), nonl=True) # copy Makefile fn = path.join(self.outdir, 'Makefile') - self.info(fn, nonl=1) + logger.info(fn, nonl=1) try: with open(fn, 'w') as mkfile: mkfile.write(TEXINFO_MAKEFILE) except (IOError, OSError) as err: - self.warn("error writing file %s: %s" % (fn, err)) - self.info(' done') + logger.warning("error writing file %s: %s", fn, err) + logger.info(' done') def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(TexinfoBuilder) app.add_config_value('texinfo_documents', diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py index 25a0af6a0..7147baa5c 100644 --- a/sphinx/builders/text.py +++ b/sphinx/builders/text.py @@ -15,9 +15,12 @@ from os import path from docutils.io import StringOutput from sphinx.builders import Builder +from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path from sphinx.writers.text import TextWriter +logger = logging.getLogger(__name__) + class TextBuilder(Builder): name = 'text' @@ -25,6 +28,8 @@ class TextBuilder(Builder): out_suffix = '.txt' allow_parallel = True + current_docname = None # type: unicode + def init(self): pass @@ -63,7 +68,7 @@ class TextBuilder(Builder): with codecs.open(outfilename, 'w', 'utf-8') as f: f.write(self.writer.output) except (IOError, OSError) as err: - self.warn("error writing file %s: %s" % (outfilename, err)) + logger.warning("error writing file %s: %s", outfilename, err) def finish(self): pass diff --git a/sphinx/builders/xml.py b/sphinx/builders/xml.py index 73d9e72be..fc43b4c12 100644 --- a/sphinx/builders/xml.py +++ b/sphinx/builders/xml.py @@ -16,9 +16,12 @@ from docutils import nodes from docutils.io import StringOutput from sphinx.builders import Builder +from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path from sphinx.writers.xml import XMLWriter, PseudoXMLWriter +logger = logging.getLogger(__name__) + class XMLBuilder(Builder): """ @@ -80,7 +83,7 @@ class XMLBuilder(Builder): with codecs.open(outfilename, 'w', 'utf-8') as f: f.write(self.writer.output) except (IOError, OSError) as err: - self.warn("error writing file %s: %s" % (outfilename, err)) + logger.warning("error writing file %s: %s", outfilename, err) def finish(self): pass diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 0d85767e4..7a97e10e2 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -16,17 +16,22 @@ import traceback from os import path from six import text_type, binary_type + from docutils.utils import SystemMessage from sphinx import __display_version__ from sphinx.errors import SphinxError from sphinx.application import Sphinx from sphinx.util import Tee, format_exception_cut_frames, save_traceback -from sphinx.util.console import red, nocolor, color_terminal +from sphinx.util.console import red, nocolor, color_terminal # type: ignore from sphinx.util.docutils import docutils_namespace from sphinx.util.osutil import abspath, fs_encoding from sphinx.util.pycompat import terminal_safe +if False: + # For type annotation + from typing import Any, IO, Union # NOQA + USAGE = """\ Sphinx v%s @@ -45,18 +50,21 @@ For more information, visit <http://sphinx-doc.org/>. class MyFormatter(optparse.IndentedHelpFormatter): def format_usage(self, usage): + # type: (Any) -> Any return usage def format_help(self, formatter): - result = [] - if self.description: + # type: (Any) -> unicode + result = [] # type: List[unicode] + if self.description: # type: ignore result.append(self.format_description(formatter)) - if self.option_list: - result.append(self.format_option_help(formatter)) + if self.option_list: # type: ignore + result.append(self.format_option_help(formatter)) # type: ignore return "\n".join(result) def handle_exception(app, opts, exception, stderr=sys.stderr): + # type: (Sphinx, Any, Union[Exception, KeyboardInterrupt], IO) -> None if opts.pdb: import pdb print(red('Exception occurred while building, starting debugger:'), @@ -107,6 +115,7 @@ def handle_exception(app, opts, exception, stderr=sys.stderr): def main(argv): + # type: (List[unicode]) -> int if not color_terminal(): nocolor() @@ -210,11 +219,11 @@ def main(argv): # handle remaining filename arguments filenames = args[2:] - err = 0 + err = 0 # type: ignore for filename in filenames: if not path.isfile(filename): print('Error: Cannot find file %r.' % filename, file=sys.stderr) - err = 1 + err = 1 # type: ignore if err: return 1 @@ -249,7 +258,7 @@ def main(argv): print('Error: Cannot open warning file %r: %s' % (opts.warnfile, exc), file=sys.stderr) sys.exit(1) - warning = Tee(warning, warnfp) + warning = Tee(warning, warnfp) # type: ignore error = warning confoverrides = {} diff --git a/sphinx/config.py b/sphinx/config.py index 61516a1ff..c55660a5c 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -16,9 +16,17 @@ from six import PY2, PY3, iteritems, string_types, binary_type, text_type, integ from sphinx.errors import ConfigError from sphinx.locale import l_ +from sphinx.util import logging +from sphinx.util.i18n import format_date from sphinx.util.osutil import cd from sphinx.util.pycompat import execfile_, NoneType -from sphinx.util.i18n import format_date + +if False: + # For type annotation + from typing import Any, Callable, Tuple # NOQA + from sphinx.util.tags import Tags # NOQA + +logger = logging.getLogger(__name__) nonascii_re = re.compile(br'[\x80-\xff]') copyright_year_re = re.compile(r'^((\d{4}-)?)(\d{4})(?=[ ,])') @@ -43,13 +51,15 @@ class ENUM(object): app.add_config_value('latex_show_urls', 'no', ENUM('no', 'footnote', 'inline')) """ def __init__(self, *candidates): + # type: (unicode) -> None self.candidates = candidates def match(self, value): + # type: (unicode) -> bool return value in self.candidates -string_classes = [text_type] +string_classes = [text_type] # type: List if PY2: string_classes.append(binary_type) # => [str, unicode] @@ -114,15 +124,13 @@ class Config(object): tls_verify = (True, 'env'), tls_cacerts = (None, 'env'), - - # pre-initialized confval for HTML builder - html_translator_class = (None, 'html', string_classes), - ) + ) # type: Dict[unicode, Tuple] def __init__(self, dirname, filename, overrides, tags): + # type: (unicode, unicode, Dict, Tags) -> None self.overrides = overrides self.values = Config.config_values.copy() - config = {} + config = {} # type: Dict[unicode, Any] if dirname is not None: config_file = path.join(dirname, filename) config['__file__'] = config_file @@ -140,14 +148,14 @@ class Config(object): self._raw_config = config # these two must be preinitialized because extensions can add their # own config values - self.setup = config.get('setup', None) + self.setup = config.get('setup', None) # type: Callable if 'extensions' in overrides: if isinstance(overrides['extensions'], string_types): config['extensions'] = overrides.pop('extensions').split(',') else: config['extensions'] = overrides.pop('extensions') - self.extensions = config.get('extensions', []) + self.extensions = config.get('extensions', []) # type: List[unicode] # correct values of copyright year that are not coherent with # the SOURCE_DATE_EPOCH environment variable (if set) @@ -155,10 +163,11 @@ class Config(object): if getenv('SOURCE_DATE_EPOCH') is not None: for k in ('copyright', 'epub_copyright'): if k in config: - config[k] = copyright_year_re.sub('\g<1>%s' % format_date('%Y'), + config[k] = copyright_year_re.sub('\g<1>%s' % format_date('%Y'), # type: ignore # NOQA config[k]) - def check_types(self, warn): + def check_types(self): + # type: () -> None # check all values for deviation from the default value's type, since # that can result in TypeErrors all over the place # NB. since config values might use l_() we have to wait with calling @@ -177,7 +186,7 @@ class Config(object): current = self[name] if isinstance(permitted, ENUM): if not permitted.match(current): - warn(CONFIG_ENUM_WARNING.format( + logger.warning(CONFIG_ENUM_WARNING.format( name=name, current=current, candidates=permitted.candidates)) else: if type(current) is type(default): @@ -192,23 +201,25 @@ class Config(object): continue # at least we share a non-trivial base class if permitted: - warn(CONFIG_PERMITTED_TYPE_WARNING.format( + logger.warning(CONFIG_PERMITTED_TYPE_WARNING.format( name=name, current=type(current), permitted=str([cls.__name__ for cls in permitted]))) else: - warn(CONFIG_TYPE_WARNING.format( + logger.warning(CONFIG_TYPE_WARNING.format( name=name, current=type(current), default=type(default))) - def check_unicode(self, warn): + def check_unicode(self): + # type: () -> None # check all string values for non-ASCII characters in bytestrings, # since that can result in UnicodeErrors all over the place for name, value in iteritems(self._raw_config): - if isinstance(value, binary_type) and nonascii_re.search(value): - warn('the config value %r is set to a string with non-ASCII ' - 'characters; this can lead to Unicode errors occurring. ' - 'Please use Unicode strings, e.g. %r.' % (name, u'Content')) + if isinstance(value, binary_type) and nonascii_re.search(value): # type: ignore + logger.warning('the config value %r is set to a string with non-ASCII ' + 'characters; this can lead to Unicode errors occurring. ' + 'Please use Unicode strings, e.g. %r.', name, u'Content') def convert_overrides(self, name, value): + # type: (unicode, Any) -> Any if not isinstance(value, string_types): return value else: @@ -218,10 +229,10 @@ class Config(object): 'ignoring (use %r to set individual elements)' % (name, name + '.key=value')) elif isinstance(defvalue, list): - return value.split(',') + return value.split(',') # type: ignore elif isinstance(defvalue, integer_types): try: - return int(value) + return int(value) # type: ignore except ValueError: raise ValueError('invalid number %r for config value %r, ignoring' % (value, name)) @@ -233,9 +244,10 @@ class Config(object): else: return value - def pre_init_values(self, warn): + def pre_init_values(self): + # type: () -> None """Initialize some limited config variables before loading extensions""" - variables = ['needs_sphinx', 'suppress_warnings', 'html_translator_class'] + variables = ['needs_sphinx', 'suppress_warnings'] for name in variables: try: if name in self.overrides: @@ -243,32 +255,34 @@ class Config(object): elif name in self._raw_config: self.__dict__[name] = self._raw_config[name] except ValueError as exc: - warn(exc) + logger.warning("%s", exc) - def init_values(self, warn): + def init_values(self): + # type: () -> None config = self._raw_config for valname, value in iteritems(self.overrides): try: if '.' in valname: realvalname, key = valname.split('.', 1) - config.setdefault(realvalname, {})[key] = value + config.setdefault(realvalname, {})[key] = value # type: ignore continue elif valname not in self.values: - warn('unknown config value %r in override, ignoring' % valname) + logger.warning('unknown config value %r in override, ignoring', valname) continue if isinstance(value, string_types): config[valname] = self.convert_overrides(valname, value) else: config[valname] = value except ValueError as exc: - warn(exc) + logger.warning("%s", exc) for name in config: if name in self.values: self.__dict__[name] = config[name] - if isinstance(self.source_suffix, string_types): - self.source_suffix = [self.source_suffix] + if isinstance(self.source_suffix, string_types): # type: ignore + self.source_suffix = [self.source_suffix] # type: ignore def __getattr__(self, name): + # type: (unicode) -> Any if name.startswith('_'): raise AttributeError(name) if name not in self.values: @@ -279,13 +293,17 @@ class Config(object): return default def __getitem__(self, name): + # type: (unicode) -> unicode return getattr(self, name) def __setitem__(self, name, value): + # type: (unicode, Any) -> None setattr(self, name, value) def __delitem__(self, name): + # type: (unicode) -> None delattr(self, name) def __contains__(self, name): + # type: (unicode) -> bool return name in self.values diff --git a/sphinx/deprecation.py b/sphinx/deprecation.py index a5d14762f..9ea4ab1f3 100644 --- a/sphinx/deprecation.py +++ b/sphinx/deprecation.py @@ -14,8 +14,16 @@ class RemovedInSphinx16Warning(DeprecationWarning): pass -class RemovedInSphinx17Warning(PendingDeprecationWarning): +class RemovedInSphinx17Warning(DeprecationWarning): pass -RemovedInNextVersionWarning = RemovedInSphinx16Warning +class RemovedInSphinx18Warning(PendingDeprecationWarning): + pass + + +class RemovedInSphinx20Warning(PendingDeprecationWarning): + pass + + +RemovedInNextVersionWarning = RemovedInSphinx17Warning diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 9d4c6eba8..58efd68a5 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -29,6 +29,12 @@ from sphinx.directives.patches import ( # noqa Figure, Meta ) +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.environment import BuildEnvironment # NOQA + # RE to strip backslash escapes nl_escape_re = re.compile(r'\\\n') @@ -51,9 +57,13 @@ class ObjectDescription(Directive): } # types of doc fields that this directive handles, see sphinx.util.docfields - doc_field_types = [] + doc_field_types = [] # type: List[Any] + domain = None # type: unicode + objtype = None # type: unicode + indexnode = None # type: addnodes.index def get_signatures(self): + # type: () -> List[unicode] """ Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line. @@ -65,6 +75,7 @@ class ObjectDescription(Directive): return [strip_backslash_re.sub(r'\1', line.strip()) for line in lines] def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> Any """ Parse the signature *sig* into individual nodes and append them to *signode*. If ValueError is raised, parsing is aborted and the whole @@ -77,6 +88,7 @@ class ObjectDescription(Directive): raise ValueError def add_target_and_index(self, name, sig, signode): + # type: (Any, unicode, addnodes.desc_signature) -> None """ Add cross-reference IDs and entries to self.indexnode, if applicable. @@ -85,6 +97,7 @@ class ObjectDescription(Directive): return # do nothing by default def before_content(self): + # type: () -> None """ Called before parsing content. Used to set information about the current directive context on the build environment. @@ -92,6 +105,7 @@ class ObjectDescription(Directive): pass def after_content(self): + # type: () -> None """ Called after parsing content. Used to reset information about the current directive context on the build environment. @@ -99,6 +113,7 @@ class ObjectDescription(Directive): pass def run(self): + # type: () -> List[nodes.Node] """ Main directive entry function, called by docutils upon encountering the directive. @@ -120,7 +135,7 @@ class ObjectDescription(Directive): self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = '', self.name - self.env = self.state.document.settings.env + self.env = self.state.document.settings.env # type: BuildEnvironment self.indexnode = addnodes.index(entries=[]) node = addnodes.desc() @@ -130,7 +145,7 @@ class ObjectDescription(Directive): node['objtype'] = node['desctype'] = self.objtype node['noindex'] = noindex = ('noindex' in self.options) - self.names = [] + self.names = [] # type: List[unicode] signatures = self.get_signatures() for i, sig in enumerate(signatures): # add a signature node for each signature in the current unit @@ -181,6 +196,7 @@ class DefaultRole(Directive): final_argument_whitespace = False def run(self): + # type: () -> List[nodes.Node] if not self.arguments: if '' in roles._roles: # restore the "default" default role @@ -209,9 +225,10 @@ class DefaultDomain(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env domain_name = self.arguments[0].lower() # if domain_name not in env.domains: @@ -225,6 +242,7 @@ class DefaultDomain(Directive): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] directives.register_directive('default-role', DefaultRole) directives.register_directive('default-domain', DefaultDomain) directives.register_directive('describe', ObjectDescription) diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 519a32577..03936f4e8 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -11,17 +11,22 @@ import sys import codecs from difflib import unified_diff +from six import string_types + from docutils import nodes from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList -from six import string_types - from sphinx import addnodes from sphinx.locale import _ from sphinx.util import parselinenos from sphinx.util.nodes import set_source_info +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA + class Highlight(Directive): """ @@ -38,6 +43,7 @@ class Highlight(Directive): } def run(self): + # type: () -> List[nodes.Node] if 'linenothreshold' in self.options: try: linenothreshold = int(self.options['linenothreshold']) @@ -50,6 +56,7 @@ class Highlight(Directive): def dedent_lines(lines, dedent): + # type: (List[unicode], int) -> List[unicode] if not dedent: return lines @@ -64,6 +71,7 @@ def dedent_lines(lines, dedent): def container_wrapper(directive, literal_node, caption): + # type: (Directive, nodes.Node, unicode) -> nodes.container container_node = nodes.container('', literal_block=True, classes=['literal-block-wrapper']) parsed = nodes.Element() @@ -101,6 +109,7 @@ class CodeBlock(Directive): } def run(self): + # type: () -> List[nodes.Node] code = u'\n'.join(self.content) linespec = self.options.get('emphasize-lines') @@ -137,7 +146,7 @@ class CodeBlock(Directive): literal = container_wrapper(self, literal, caption) except ValueError as exc: document = self.state.document - errmsg = _('Invalid caption: %s' % exc[0][0].astext()) + errmsg = _('Invalid caption: %s' % exc[0][0].astext()) # type: ignore return [document.reporter.warning(errmsg, line=self.lineno)] # literal will be note_implicit_target that is linked from caption and numref. @@ -182,11 +191,12 @@ class LiteralInclude(Directive): } def read_with_encoding(self, filename, document, codec_info, encoding): + # type: (unicode, nodes.Node, Any, unicode) -> List try: with codecs.StreamReaderWriter(open(filename, 'rb'), codec_info[2], codec_info[3], 'strict') as f: lines = f.readlines() - lines = dedent_lines(lines, self.options.get('dedent')) + lines = dedent_lines(lines, self.options.get('dedent')) # type: ignore return lines except (IOError, OSError): return [document.reporter.warning( @@ -199,6 +209,7 @@ class LiteralInclude(Directive): (encoding, filename))] def run(self): + # type: () -> List[nodes.Node] document = self.state.document if not document.settings.file_insertion_enabled: return [document.reporter.warning('File insertion disabled', @@ -367,7 +378,7 @@ class LiteralInclude(Directive): retnode = container_wrapper(self, retnode, caption) except ValueError as exc: document = self.state.document - errmsg = _('Invalid caption: %s' % exc[0][0].astext()) + errmsg = _('Invalid caption: %s' % exc[0][0].astext()) # type: ignore return [document.reporter.warning(errmsg, line=self.lineno)] # retnode will be note_implicit_target that is linked from caption and numref. @@ -378,6 +389,7 @@ class LiteralInclude(Directive): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] directives.register_directive('highlight', Highlight) directives.register_directive('highlightlang', Highlight) # old directives.register_directive('code-block', CodeBlock) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index b6d9f8129..06a3f745d 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -8,6 +8,7 @@ """ from six.moves import range + from docutils import nodes from docutils.parsers.rst import Directive, directives from docutils.parsers.rst.directives.admonitions import BaseAdmonition @@ -21,8 +22,14 @@ from sphinx.util.nodes import explicit_title_re, set_source_info, \ process_index_entry from sphinx.util.matching import patfilter +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + def int_or_nothing(argument): + # type: (unicode) -> int if not argument: return 999 return int(argument) @@ -50,6 +57,7 @@ class TocTree(Directive): } def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env suffixes = env.config.source_suffix glob = 'glob' in self.options @@ -57,7 +65,7 @@ class TocTree(Directive): ret = [] # (title, ref) pairs, where ref may be a document, or an external link, # and title may be None if the document's title is to be used - entries = [] + entries = [] # type: List[Tuple[unicode, unicode]] includefiles = [] all_docnames = env.found_docs.copy() # don't add the currently visited file in catch-all patterns @@ -136,9 +144,10 @@ class Author(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env if not env.config.show_authors: return [] @@ -168,20 +177,21 @@ class Index(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] arguments = self.arguments[0].split('\n') env = self.state.document.settings.env targetid = 'index-%s' % env.new_serialno('index') targetnode = nodes.target('', '', ids=[targetid]) self.state.document.note_explicit_target(targetnode) indexnode = addnodes.index() - indexnode['entries'] = ne = [] + indexnode['entries'] = [] indexnode['inline'] = False set_source_info(self, indexnode) for entry in arguments: - ne.extend(process_index_entry(entry, targetid)) + indexnode['entries'].extend(process_index_entry(entry, targetid)) return [indexnode, targetnode] @@ -193,9 +203,10 @@ class VersionChange(Directive): required_arguments = 1 optional_arguments = 1 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] node = addnodes.versionmodified() node.document = self.state.document set_source_info(self, node) @@ -248,9 +259,10 @@ class TabularColumns(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] node = addnodes.tabular_col_spec() node['spec'] = self.arguments[0] set_source_info(self, node) @@ -265,9 +277,10 @@ class Centered(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] if not self.arguments: return [] subnode = addnodes.centered() @@ -285,9 +298,10 @@ class Acks(Directive): required_arguments = 0 optional_arguments = 0 final_argument_whitespace = False - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] node = addnodes.acks() node.document = self.state.document self.state.nested_parse(self.content, self.content_offset, node) @@ -311,6 +325,7 @@ class HList(Directive): } def run(self): + # type: () -> List[nodes.Node] ncolumns = self.options.get('columns', 2) node = nodes.paragraph() node.document = self.state.document @@ -342,9 +357,10 @@ class Only(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] node = addnodes.only() node.document = self.state.document set_source_info(self, node) @@ -398,6 +414,7 @@ class Include(BaseInclude): """ def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env if self.arguments[0].startswith('<') and \ self.arguments[0].endswith('>'): @@ -410,6 +427,7 @@ class Include(BaseInclude): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] directives.register_directive('toctree', TocTree) directives.register_directive('sectionauthor', Author) directives.register_directive('moduleauthor', Author) diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py index da7e5d9ae..2389e342c 100644 --- a/sphinx/domains/__init__.py +++ b/sphinx/domains/__init__.py @@ -17,6 +17,13 @@ from six import iteritems from sphinx.errors import SphinxError from sphinx.locale import _ +if False: + # For type annotation + from typing import Any, Callable, Iterable, Tuple, Type, Union # NOQA + from docutils import nodes # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + class ObjType(object): """ @@ -38,9 +45,10 @@ class ObjType(object): } def __init__(self, lname, *roles, **attrs): - self.lname = lname - self.roles = roles - self.attrs = self.known_attrs.copy() + # type: (unicode, Any, Any) -> None + self.lname = lname # type: unicode + self.roles = roles # type: Tuple + self.attrs = self.known_attrs.copy() # type: Dict self.attrs.update(attrs) @@ -59,17 +67,19 @@ class Index(object): domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`. """ - name = None - localname = None - shortname = None + name = None # type: unicode + localname = None # type: unicode + shortname = None # type: unicode def __init__(self, domain): + # type: (Domain) -> None if self.name is None or self.localname is None: raise SphinxError('Index subclass %s has no valid name or localname' % self.__class__.__name__) self.domain = domain def generate(self, docnames=None): + # type: (Iterable[unicode]) -> Tuple[List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool] # NOQA """Return entries for the index given by *name*. If *docnames* is given, restrict to entries referring to these docnames. @@ -97,7 +107,7 @@ class Index(object): Qualifier and description are not rendered e.g. in LaTeX output. """ - return [] + return tuple() class Domain(object): @@ -128,23 +138,26 @@ class Domain(object): #: domain label: longer, more descriptive (used in messages) label = '' #: type (usually directive) name -> ObjType instance - object_types = {} + object_types = {} # type: Dict[unicode, Any] #: directive name -> directive class - directives = {} + directives = {} # type: Dict[unicode, Any] #: role name -> role callable - roles = {} + roles = {} # type: Dict[unicode, Callable] #: a list of Index subclasses - indices = [] + indices = [] # type: List[Type[Index]] #: role name -> a warning message if reference is missing - dangling_warnings = {} + dangling_warnings = {} # type: Dict[unicode, unicode] #: data value for a fresh environment - initial_data = {} + initial_data = {} # type: Dict + #: data value + data = None # type: Dict #: data version, bump this when the format of `self.data` changes data_version = 0 def __init__(self, env): - self.env = env + # type: (BuildEnvironment) -> None + self.env = env # type: BuildEnvironment if self.name not in env.domaindata: assert isinstance(self.initial_data, dict) new_data = copy.deepcopy(self.initial_data) @@ -154,18 +167,19 @@ class Domain(object): self.data = env.domaindata[self.name] if self.data['version'] != self.data_version: raise IOError('data of %r domain out of date' % self.label) - self._role_cache = {} - self._directive_cache = {} - self._role2type = {} - self._type2role = {} + self._role_cache = {} # type: Dict[unicode, Callable] + self._directive_cache = {} # type: Dict[unicode, Callable] + self._role2type = {} # type: Dict[unicode, List[unicode]] + self._type2role = {} # type: Dict[unicode, unicode] for name, obj in iteritems(self.object_types): for rolename in obj.roles: self._role2type.setdefault(rolename, []).append(name) self._type2role[name] = obj.roles[0] if obj.roles else '' - self.objtypes_for_role = self._role2type.get - self.role_for_objtype = self._type2role.get + self.objtypes_for_role = self._role2type.get # type: Callable[[unicode], List[unicode]] # NOQA + self.role_for_objtype = self._type2role.get # type: Callable[[unicode], unicode] def role(self, name): + # type: (unicode) -> Callable """Return a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. """ @@ -183,6 +197,7 @@ class Domain(object): return role_adapter def directive(self, name): + # type: (unicode) -> Callable """Return a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. """ @@ -193,7 +208,7 @@ class Domain(object): fullname = '%s:%s' % (self.name, name) BaseDirective = self.directives[name] - class DirectiveAdapter(BaseDirective): + class DirectiveAdapter(BaseDirective): # type: ignore def run(self): self.name = fullname return BaseDirective.run(self) @@ -203,10 +218,12 @@ class Domain(object): # methods that should be overwritten def clear_doc(self, docname): + # type: (unicode) -> None """Remove traces of a document in the domain-specific inventories.""" pass def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None """Merge in data regarding *docnames* from a different domaindata inventory (coming from a subprocess in parallel builds). """ @@ -215,11 +232,13 @@ class Domain(object): self.__class__) def process_doc(self, env, docname, document): + # type: (BuildEnvironment, unicode, nodes.Node) -> None """Process a document after it is read by the environment.""" pass def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA """Resolve the pending_xref *node* with the given *typ* and *target*. This method should return a new node, to replace the xref node, @@ -236,6 +255,7 @@ class Domain(object): pass def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA """Resolve the pending_xref *node* with the given *target*. The reference comes from an "any" or similar role, which means that we @@ -252,6 +272,7 @@ class Domain(object): raise NotImplementedError def get_objects(self): + # type: () -> Iterable[Tuple[unicode, unicode, unicode, unicode, unicode, int]] """Return an iterable of "object descriptions", which are tuples with five items: @@ -271,6 +292,7 @@ class Domain(object): return [] def get_type_name(self, type, primary=False): + # type: (ObjType, bool) -> unicode """Return full name for given ObjType.""" if primary: return type.lname diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index a50af9ae6..22b221318 100644 --- a/sphinx/domains/c.py +++ b/sphinx/domains/c.py @@ -22,6 +22,13 @@ from sphinx.directives import ObjectDescription from sphinx.util.nodes import make_refnode from sphinx.util.docfields import Field, TypedField +if False: + # For type annotation + from typing import Any, Iterator, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + # RE to split at word boundaries wsplit_re = re.compile(r'(\W+)') @@ -74,8 +81,9 @@ class CObject(ObjectDescription): )) def _parse_type(self, node, ctype): + # type: (nodes.Node, unicode) -> None # add cross-ref nodes for all words - for part in [_f for _f in wsplit_re.split(ctype) if _f]: + for part in [_f for _f in wsplit_re.split(ctype) if _f]: # type: ignore tnode = nodes.Text(part, part) if part[0] in string.ascii_letters+'_' and \ part not in self.stopwords: @@ -88,11 +96,12 @@ class CObject(ObjectDescription): node += tnode def _parse_arglist(self, arglist): + # type: (unicode) -> Iterator[unicode] while True: - m = c_funcptr_arg_sig_re.match(arglist) + m = c_funcptr_arg_sig_re.match(arglist) # type: ignore if m: yield m.group() - arglist = c_funcptr_arg_sig_re.sub('', arglist) + arglist = c_funcptr_arg_sig_re.sub('', arglist) # type: ignore if ',' in arglist: _, arglist = arglist.split(',', 1) else: @@ -106,11 +115,12 @@ class CObject(ObjectDescription): break def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode """Transform a C signature into RST nodes.""" # first try the function pointer signature regex, it's more specific - m = c_funcptr_sig_re.match(sig) + m = c_funcptr_sig_re.match(sig) # type: ignore if m is None: - m = c_sig_re.match(sig) + m = c_sig_re.match(sig) # type: ignore if m is None: raise ValueError('no match') rettype, name, arglist, const = m.groups() @@ -151,7 +161,7 @@ class CObject(ObjectDescription): arg = arg.strip() param = addnodes.desc_parameter('', '', noemph=True) try: - m = c_funcptr_arg_sig_re.match(arg) + m = c_funcptr_arg_sig_re.match(arg) # type: ignore if m: self._parse_type(param, m.group(1) + '(') param += nodes.emphasis(m.group(2), m.group(2)) @@ -173,6 +183,7 @@ class CObject(ObjectDescription): return fullname def get_index_text(self, name): + # type: (unicode) -> unicode if self.objtype == 'function': return _('%s (C function)') % name elif self.objtype == 'member': @@ -187,6 +198,7 @@ class CObject(ObjectDescription): return '' def add_target_and_index(self, name, sig, signode): + # type: (unicode, unicode, addnodes.desc_signature) -> None # for C API items we add a prefix since names are usually not qualified # by a module name and so easily clash with e.g. section titles targetname = 'c.' + name @@ -209,6 +221,7 @@ class CObject(ObjectDescription): targetname, '', None)) def before_content(self): + # type: () -> None self.typename_set = False if self.name == 'c:type': if self.names: @@ -216,12 +229,14 @@ class CObject(ObjectDescription): self.typename_set = True def after_content(self): + # type: () -> None if self.typename_set: self.env.ref_context.pop('c:type', None) class CXRefRole(XRefRole): def process_link(self, env, refnode, has_explicit_title, title, target): + # type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA if not has_explicit_title: target = target.lstrip('~') # only has a meaning for the title # if the first character is a tilde, don't display the module/class @@ -262,14 +277,16 @@ class CDomain(Domain): } initial_data = { 'objects': {}, # fullname -> docname, objtype - } + } # type: Dict[unicode, Dict[unicode, Tuple[unicode, Any]]] def clear_doc(self, docname): + # type: (unicode) -> None for fullname, (fn, _l) in list(self.data['objects'].items()): if fn == docname: del self.data['objects'][fullname] def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None # XXX check duplicates for fullname, (fn, objtype) in otherdata['objects'].items(): if fn in docnames: @@ -277,6 +294,7 @@ class CDomain(Domain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA # strip pointer asterisk target = target.rstrip(' *') # becase TypedField can generate xrefs @@ -290,6 +308,7 @@ class CDomain(Domain): def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA # strip pointer asterisk target = target.rstrip(' *') if target not in self.data['objects']: @@ -300,11 +319,13 @@ class CDomain(Domain): contnode, target))] def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] for refname, (docname, type) in list(self.data['objects'].items()): yield (refname, refname, type, docname, 'c.' + refname, 1) def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(CDomain) return { diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py index 98e584546..cfdbc99d9 100644 --- a/sphinx/domains/cpp.py +++ b/sphinx/domains/cpp.py @@ -13,18 +13,30 @@ import re from copy import deepcopy from six import iteritems, text_type + from docutils import nodes +from docutils.parsers.rst import Directive from sphinx import addnodes from sphinx.roles import XRefRole from sphinx.locale import l_, _ from sphinx.domains import Domain, ObjType from sphinx.directives import ObjectDescription +from sphinx.util import logging from sphinx.util.nodes import make_refnode -from sphinx.util.compat import Directive from sphinx.util.pycompat import UnicodeMixin from sphinx.util.docfields import Field, GroupedField +if False: + # For type annotation + from typing import Any, Iterator, Match, Pattern, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.config import Config # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + """ Important note on ids ---------------------------------------------------------------------------- @@ -86,9 +98,9 @@ from sphinx.util.docfields import Field, GroupedField attribute-specifier-seq[opt] decl-specifier-seq[opt] init-declarator-list[opt] ; # Drop the semi-colon. For now: drop the attributes (TODO). - # Use at most 1 init-declerator. - -> decl-specifier-seq init-declerator - -> decl-specifier-seq declerator initializer + # Use at most 1 init-declarator. + -> decl-specifier-seq init-declarator + -> decl-specifier-seq declarator initializer decl-specifier -> storage-class-specifier -> @@ -149,22 +161,22 @@ from sphinx.util.docfields import Field, GroupedField | template-argument-list "," template-argument "..."[opt] template-argument -> constant-expression - | type-specifier-seq abstract-declerator + | type-specifier-seq abstract-declarator | id-expression - declerator -> - ptr-declerator + declarator -> + ptr-declarator | noptr-declarator parameters-and-qualifiers trailing-return-type (TODO: for now we don't support trailing-eturn-type) - ptr-declerator -> - noptr-declerator + ptr-declarator -> + noptr-declarator | ptr-operator ptr-declarator - noptr-declerator -> + noptr-declarator -> declarator-id attribute-specifier-seq[opt] -> "..."[opt] id-expression | rest-of-trailing - | noptr-declerator parameters-and-qualifiers + | noptr-declarator parameters-and-qualifiers | noptr-declarator "[" constant-expression[opt] "]" attribute-specifier-seq[opt] | "(" ptr-declarator ")" @@ -226,20 +238,20 @@ from sphinx.util.docfields import Field, GroupedField # Drop the attributes -> decl-specifier-seq abstract-declarator[opt] grammar, typedef-like: no initilizer - decl-specifier-seq declerator + decl-specifier-seq declarator Can start with a templateDeclPrefix. member_object: - goal: as a type_object which must have a declerator, and optionally + goal: as a type_object which must have a declarator, and optionally with a initializer grammar: - decl-specifier-seq declerator initializer + decl-specifier-seq declarator initializer Can start with a templateDeclPrefix. function_object: goal: a function declaration, TODO: what about templates? for now: skip grammar: no initializer - decl-specifier-seq declerator + decl-specifier-seq declarator Can start with a templateDeclPrefix. class_object: @@ -317,7 +329,7 @@ _id_fundamental_v1 = { 'signed long': 'l', 'unsigned long': 'L', 'bool': 'b' -} +} # type: Dict[unicode, unicode] _id_shorthands_v1 = { 'std::string': 'ss', 'std::ostream': 'os', @@ -325,7 +337,7 @@ _id_shorthands_v1 = { 'std::iostream': 'ios', 'std::vector': 'v', 'std::map': 'm' -} +} # type: Dict[unicode, unicode] _id_operator_v1 = { 'new': 'new-operator', 'new[]': 'new-array-operator', @@ -374,7 +386,7 @@ _id_operator_v1 = { '->': 'pointer-operator', '()': 'call-operator', '[]': 'subscript-operator' -} +} # type: Dict[unicode, unicode] # ------------------------------------------------------------------------------ # Id v2 constants @@ -420,7 +432,7 @@ _id_fundamental_v2 = { 'auto': 'Da', 'decltype(auto)': 'Dc', 'std::nullptr_t': 'Dn' -} +} # type: Dict[unicode, unicode] _id_operator_v2 = { 'new': 'nw', 'new[]': 'na', @@ -469,43 +481,50 @@ _id_operator_v2 = { '->': 'pt', '()': 'cl', '[]': 'ix' -} +} # type: Dict[unicode, unicode] class NoOldIdError(UnicodeMixin, Exception): # Used to avoid implementing unneeded id generation for old id schmes. def __init__(self, description=""): + # type: (unicode) -> None self.description = description def __unicode__(self): + # type: () -> unicode return self.description class DefinitionError(UnicodeMixin, Exception): def __init__(self, description): + # type: (unicode) -> None self.description = description def __unicode__(self): + # type: () -> unicode return self.description class _DuplicateSymbolError(UnicodeMixin, Exception): def __init__(self, symbol, candSymbol): + # type: (Symbol, Symbol) -> None assert symbol assert candSymbol self.symbol = symbol self.candSymbol = candSymbol def __unicode__(self): + # type: () -> unicode return "Internal C++ duplicate symbol error:\n%s" % self.symbol.dump(0) class ASTBase(UnicodeMixin): def __eq__(self, other): + # type: (Any) -> bool if type(self) is not type(other): return False try: - for key, value in iteritems(self.__dict__): + for key, value in iteritems(self.__dict__): # type: ignore if value != getattr(other, key): return False except AttributeError: @@ -513,23 +532,28 @@ class ASTBase(UnicodeMixin): return True def __ne__(self, other): + # type: (Any) -> bool return not self.__eq__(other) - __hash__ = None + __hash__ = None # type: None def clone(self): + # type: () -> ASTBase """Clone a definition expression node.""" return deepcopy(self) def get_id_v1(self): + # type: () -> unicode """Return the v1 id for the node.""" raise NotImplementedError(repr(self)) def get_id_v2(self): + # type: () -> unicode """Return the v2 id for the node.""" raise NotImplementedError(repr(self)) def get_name(self): + # type: () -> unicode """Return the name. Returns either `None` or a node with a name you might call @@ -538,10 +562,12 @@ class ASTBase(UnicodeMixin): raise NotImplementedError(repr(self)) def prefix_nested_name(self, prefix): + # type: (unicode) -> unicode """Prefix a name node (a node returned by :meth:`get_name`).""" raise NotImplementedError(repr(self)) def __unicode__(self): + # type: () -> unicode raise NotImplementedError(repr(self)) def __repr__(self): @@ -549,29 +575,35 @@ class ASTBase(UnicodeMixin): def _verify_description_mode(mode): + # type: (unicode) -> None if mode not in ('lastIsName', 'noneIsName', 'markType', 'param'): raise Exception("Description mode '%s' is invalid." % mode) class ASTCPPAttribute(ASTBase): def __init__(self, arg): + # type: (unicode) -> None self.arg = arg def __unicode__(self): + # type: () -> unicode return "[[" + self.arg + "]]" def describe_signature(self, signode): + # type: (addnodes.desc_signature) -> None txt = text_type(self) signode.append(nodes.Text(txt, txt)) class ASTGnuAttribute(ASTBase): def __init__(self, name, args): + # type: (unicode, Any) -> None self.name = name self.args = args def __unicode__(self): - res = [self.name] + # type: () -> unicode + res = [self.name] # type: List[unicode] if self.args: res.append('(') res.append(text_type(self.args)) @@ -581,10 +613,12 @@ class ASTGnuAttribute(ASTBase): class ASTGnuAttributeList(ASTBase): def __init__(self, attrs): + # type: (List[Any]) -> None self.attrs = attrs def __unicode__(self): - res = ['__attribute__(('] + # type: () -> unicode + res = ['__attribute__(('] # type: List[unicode] first = True for attr in self.attrs: if not first: @@ -595,6 +629,7 @@ class ASTGnuAttributeList(ASTBase): return ''.join(res) def describe_signature(self, signode): + # type: (addnodes.desc_signature) -> None txt = text_type(self) signode.append(nodes.Text(txt, txt)) @@ -603,12 +638,15 @@ class ASTIdAttribute(ASTBase): """For simple attributes defined by the user.""" def __init__(self, id): + # type: (unicode) -> None self.id = id def __unicode__(self): + # type: () -> unicode return self.id def describe_signature(self, signode): + # type: (addnodes.desc_signature) -> None signode.append(nodes.Text(self.id, self.id)) @@ -616,29 +654,35 @@ class ASTParenAttribute(ASTBase): """For paren attributes defined by the user.""" def __init__(self, id, arg): + # type: (unicode, unicode) -> None self.id = id self.arg = arg def __unicode__(self): + # type: () -> unicode return self.id + '(' + self.arg + ')' def describe_signature(self, signode): + # type: (addnodes.desc_signature) -> None txt = text_type(self) signode.append(nodes.Text(txt, txt)) class ASTIdentifier(ASTBase): def __init__(self, identifier): + # type: (unicode) -> None assert identifier is not None self.identifier = identifier def get_id_v1(self): + # type: () -> unicode if self.identifier == 'size_t': return 's' else: return self.identifier def get_id_v2(self): + # type: () -> unicode if self.identifier == "std": return 'St' elif self.identifier[0] == "~": @@ -648,9 +692,11 @@ class ASTIdentifier(ASTBase): return text_type(len(self.identifier)) + self.identifier def __unicode__(self): + # type: () -> unicode return self.identifier def describe_signature(self, signode, mode, env, prefix, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, unicode, Symbol) -> None _verify_description_mode(mode) if mode == 'markType': targetText = prefix + self.identifier @@ -673,6 +719,7 @@ class ASTIdentifier(ASTBase): class ASTTemplateKeyParamPackIdDefault(ASTBase): def __init__(self, key, identifier, parameterPack, default): + # type: (unicode, Any, bool, Any) -> None assert key if parameterPack: assert default is None @@ -682,9 +729,11 @@ class ASTTemplateKeyParamPackIdDefault(ASTBase): self.default = default def get_identifier(self): + # type: () -> unicode return self.identifier def get_id_v2(self): + # type: () -> unicode # this is not part of the normal name mangling in C++ res = [] if self.parameterPack: @@ -694,7 +743,8 @@ class ASTTemplateKeyParamPackIdDefault(ASTBase): return ''.join(res) def __unicode__(self): - res = [self.key] + # type: () -> unicode + res = [self.key] # type: List[unicode] if self.parameterPack: if self.identifier: res.append(' ') @@ -709,6 +759,7 @@ class ASTTemplateKeyParamPackIdDefault(ASTBase): return ''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None signode += nodes.Text(self.key) if self.parameterPack: if self.identifier: @@ -725,18 +776,22 @@ class ASTTemplateKeyParamPackIdDefault(ASTBase): class ASTTemplateParamType(ASTBase): def __init__(self, data): + # type: (Any) -> None assert data self.data = data @property def name(self): + # type: () -> ASTNestedName id = self.get_identifier() return ASTNestedName([ASTNestedNameElement(id, None)], rooted=False) def get_identifier(self): + # type: () -> unicode return self.data.get_identifier() def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode # this is not part of the normal name mangling in C++ if symbol: # the anchor will be our parent @@ -745,14 +800,17 @@ class ASTTemplateParamType(ASTBase): return self.data.get_id_v2() def __unicode__(self): + # type: () -> unicode return text_type(self.data) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None self.data.describe_signature(signode, mode, env, symbol) class ASTTemplateParamTemplateType(ASTBase): def __init__(self, nestedParams, data): + # type: (Any, Any) -> None assert nestedParams assert data self.nestedParams = nestedParams @@ -760,13 +818,16 @@ class ASTTemplateParamTemplateType(ASTBase): @property def name(self): + # type: () -> ASTNestedName id = self.get_identifier() return ASTNestedName([ASTNestedNameElement(id, None)], rooted=False) def get_identifier(self): + # type: () -> unicode return self.data.get_identifier() def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode # this is not part of the normal name mangling in C++ if symbol: # the anchor will be our parent @@ -775,9 +836,11 @@ class ASTTemplateParamTemplateType(ASTBase): return self.nestedParams.get_id_v2() + self.data.get_id_v2() def __unicode__(self): + # type: () -> unicode return text_type(self.nestedParams) + text_type(self.data) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None self.nestedParams.describe_signature(signode, 'noneIsName', env, symbol) signode += nodes.Text(' ') self.data.describe_signature(signode, mode, env, symbol) @@ -785,15 +848,18 @@ class ASTTemplateParamTemplateType(ASTBase): class ASTTemplateParamNonType(ASTBase): def __init__(self, param): + # type: (Any) -> None assert param self.param = param @property def name(self): + # type: () -> ASTNestedName id = self.get_identifier() return ASTNestedName([ASTNestedNameElement(id, None)], rooted=False) def get_identifier(self): + # type: () -> unicode name = self.param.name if name: assert len(name.names) == 1 @@ -804,6 +870,7 @@ class ASTTemplateParamNonType(ASTBase): return None def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode # this is not part of the normal name mangling in C++ if symbol: # the anchor will be our parent @@ -812,18 +879,22 @@ class ASTTemplateParamNonType(ASTBase): return '_' + self.param.get_id_v2() def __unicode__(self): + # type: () -> unicode return text_type(self.param) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None self.param.describe_signature(signode, mode, env, symbol) class ASTTemplateParams(ASTBase): def __init__(self, params): + # type: (Any) -> None assert params is not None self.params = params def get_id_v2(self): + # type: () -> unicode res = [] res.append("I") for param in self.params: @@ -832,6 +903,7 @@ class ASTTemplateParams(ASTBase): return ''.join(res) def __unicode__(self): + # type: () -> unicode res = [] res.append(u"template<") res.append(u", ".join(text_type(a) for a in self.params)) @@ -839,6 +911,7 @@ class ASTTemplateParams(ASTBase): return ''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None signode.sphinx_cpp_tagname = 'templateParams' signode += nodes.Text("template<") first = True @@ -852,13 +925,16 @@ class ASTTemplateParams(ASTBase): class ASTTemplateIntroductionParameter(ASTBase): def __init__(self, identifier, parameterPack): + # type: (Any, Any) -> None self.identifier = identifier self.parameterPack = parameterPack def get_identifier(self): + # type: () -> unicode return self.identifier def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode # this is not part of the normal name mangling in C++ if symbol: # the anchor will be our parent @@ -870,6 +946,7 @@ class ASTTemplateIntroductionParameter(ASTBase): return '0' # we need to put something def get_id_v2_as_arg(self): + # type: () -> unicode # used for the implicit requires clause res = self.identifier.get_id_v2() if self.parameterPack: @@ -878,13 +955,15 @@ class ASTTemplateIntroductionParameter(ASTBase): return res def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.parameterPack: res.append('...') res.append(text_type(self.identifier)) return ''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None if self.parameterPack: signode += nodes.Text('...') self.identifier.describe_signature(signode, mode, env, '', symbol) @@ -892,6 +971,7 @@ class ASTTemplateIntroductionParameter(ASTBase): class ASTTemplateIntroduction(ASTBase): def __init__(self, concept, params): + # type: (Any, List[Any]) -> None assert len(params) > 0 self.concept = concept self.params = params @@ -899,6 +979,7 @@ class ASTTemplateIntroduction(ASTBase): # id_v1 does not exist def get_id_v2(self): + # type: () -> unicode # first do the same as a normal template parameter list res = [] res.append("I") @@ -916,6 +997,7 @@ class ASTTemplateIntroduction(ASTBase): return ''.join(res) def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.concept)) res.append('{') @@ -924,6 +1006,7 @@ class ASTTemplateIntroduction(ASTBase): return ''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None signode.sphinx_cpp_tagname = 'templateIntroduction' self.concept.describe_signature(signode, 'markType', env, symbol) signode += nodes.Text('{') @@ -938,6 +1021,7 @@ class ASTTemplateIntroduction(ASTBase): class ASTTemplateDeclarationPrefix(ASTBase): def __init__(self, templates): + # type: (List[Any]) -> None assert templates is not None assert len(templates) > 0 self.templates = templates @@ -945,6 +1029,7 @@ class ASTTemplateDeclarationPrefix(ASTBase): # id_v1 does not exist def get_id_v2(self): + # type: () -> unicode # this is not part of a normal name mangling system res = [] for t in self.templates: @@ -952,12 +1037,14 @@ class ASTTemplateDeclarationPrefix(ASTBase): return u''.join(res) def __unicode__(self): + # type: () -> unicode res = [] for t in self.templates: res.append(text_type(t)) return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) for t in self.templates: templateNode = addnodes.desc_signature_line() @@ -967,30 +1054,36 @@ class ASTTemplateDeclarationPrefix(ASTBase): class ASTOperatorBuildIn(ASTBase): def __init__(self, op): + # type: (unicode) -> None self.op = op def is_operator(self): + # type: () -> bool return True def get_id_v1(self): + # type: () -> unicode if self.op not in _id_operator_v1: raise Exception('Internal error: Build-in operator "%s" can not ' 'be mapped to an id.' % self.op) return _id_operator_v1[self.op] def get_id_v2(self): + # type: () -> unicode if self.op not in _id_operator_v2: raise Exception('Internal error: Build-in operator "%s" can not ' 'be mapped to an id.' % self.op) return _id_operator_v2[self.op] def __unicode__(self): + # type: () -> unicode if self.op in ('new', 'new[]', 'delete', 'delete[]'): return u'operator ' + self.op else: return u'operator' + self.op def describe_signature(self, signode, mode, env, prefix, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, unicode, Symbol) -> None _verify_description_mode(mode) identifier = text_type(self) if mode == 'lastIsName': @@ -1001,24 +1094,31 @@ class ASTOperatorBuildIn(ASTBase): class ASTOperatorType(ASTBase): def __init__(self, type): + # type: (Any) -> None self.type = type def is_operator(self): + # type: () -> bool return True def get_id_v1(self): + # type: () -> unicode return u'castto-%s-operator' % self.type.get_id_v1() def get_id_v2(self): + # type: () -> unicode return u'cv' + self.type.get_id_v2() def __unicode__(self): + # type: () -> unicode return u''.join(['operator ', text_type(self.type)]) def get_name_no_template(self): + # type: () -> unicode return text_type(self) def describe_signature(self, signode, mode, env, prefix, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, unicode, Symbol) -> None _verify_description_mode(mode) identifier = text_type(self) if mode == 'lastIsName': @@ -1029,21 +1129,27 @@ class ASTOperatorType(ASTBase): class ASTOperatorLiteral(ASTBase): def __init__(self, identifier): + # type: (Any) -> None self.identifier = identifier def is_operator(self): + # type: () -> bool return True def get_id_v1(self): + # type: () -> unicode raise NoOldIdError() def get_id_v2(self): + # type: () -> unicode return u'li' + self.identifier.get_id_v2() def __unicode__(self): + # type: () -> unicode return u'operator""' + text_type(self.identifier) def describe_signature(self, signode, mode, env, prefix, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, unicode, Symbol) -> None _verify_description_mode(mode) identifier = text_type(self) if mode == 'lastIsName': @@ -1054,38 +1160,46 @@ class ASTOperatorLiteral(ASTBase): class ASTTemplateArgConstant(ASTBase): def __init__(self, value): + # type: (Any) -> None self.value = value def __unicode__(self): + # type: () -> unicode return text_type(self.value) def get_id_v1(self): + # type: () -> unicode return text_type(self).replace(u' ', u'-') def get_id_v2(self): + # type: () -> unicode # TODO: doing this properly needs parsing of expressions, let's just # juse it verbatim for now return u'X' + text_type(self) + u'E' def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text(text_type(self)) class ASTTemplateArgs(ASTBase): def __init__(self, args): + # type: (List[Any]) -> None assert args is not None assert len(args) > 0 self.args = args def get_id_v1(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] res.append(':') res.append(u'.'.join(a.get_id_v1() for a in self.args)) res.append(':') return u''.join(res) def get_id_v2(self): + # type: () -> unicode res = [] res.append('I') for a in self.args: @@ -1094,10 +1208,12 @@ class ASTTemplateArgs(ASTBase): return u''.join(res) def __unicode__(self): + # type: () -> unicode res = ', '.join(text_type(a) for a in self.args) return '<' + res + '>' def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text('<') first = True @@ -1111,31 +1227,37 @@ class ASTTemplateArgs(ASTBase): class ASTNestedNameElement(ASTBase): def __init__(self, identifier, templateArgs): + # type: (Any, Any) -> None self.identifier = identifier self.templateArgs = templateArgs def is_operator(self): + # type: () -> bool return False def get_id_v1(self): + # type: () -> unicode res = self.identifier.get_id_v1() if self.templateArgs: res += self.templateArgs.get_id_v1() return res def get_id_v2(self): + # type: () -> unicode res = self.identifier.get_id_v2() if self.templateArgs: res += self.templateArgs.get_id_v2() return res def __unicode__(self): + # type: () -> unicode res = text_type(self.identifier) if self.templateArgs: res += text_type(self.templateArgs) return res def describe_signature(self, signode, mode, env, prefix, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, unicode, Symbol) -> None self.identifier.describe_signature(signode, mode, env, prefix, symbol) if self.templateArgs: self.templateArgs.describe_signature(signode, mode, env, symbol) @@ -1143,15 +1265,18 @@ class ASTNestedNameElement(ASTBase): class ASTNestedName(ASTBase): def __init__(self, names, rooted): + # type: (List[Any], bool) -> None assert len(names) > 0 self.names = names self.rooted = rooted @property def name(self): + # type: () -> ASTNestedName return self def num_templates(self): + # type: () -> int count = 0 for n in self.names: if n.is_operator(): @@ -1161,6 +1286,7 @@ class ASTNestedName(ASTBase): return count def get_id_v1(self): + # type: () -> unicode tt = text_type(self) if tt in _id_shorthands_v1: return _id_shorthands_v1[tt] @@ -1168,7 +1294,8 @@ class ASTNestedName(ASTBase): return u'::'.join(n.get_id_v1() for n in self.names) def get_id_v2(self, modifiers=""): - res = [] + # type: (unicode) -> unicode + res = [] # type: List[unicode] if len(self.names) > 1 or len(modifiers) > 0: res.append('N') res.append(modifiers) @@ -1179,7 +1306,8 @@ class ASTNestedName(ASTBase): return u''.join(res) def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.rooted: res.append('') for n in self.names: @@ -1187,15 +1315,16 @@ class ASTNestedName(ASTBase): return '::'.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) # just print the name part, with template args, not template params if mode == 'lastIsName': - addname = [] + addname = [] # type: List[unicode] if self.rooted: addname.append('') for n in self.names[:-1]: addname.append(text_type(n)) - addname = '::'.join(addname) + addname = '::'.join(addname) # type: ignore if len(self.names) > 1: addname += '::' signode += addnodes.desc_addname(addname, addname) @@ -1209,7 +1338,7 @@ class ASTNestedName(ASTBase): # each element should be a pending xref targeting the complete # prefix. however, only the identifier part should be a link, such # that template args can be a link as well. - prefix = '' + prefix = '' # type: unicode first = True for name in self.names: if not first: @@ -1217,7 +1346,7 @@ class ASTNestedName(ASTBase): prefix += '::' first = False if name != '': - name.describe_signature(signode, mode, env, prefix, symbol) + name.describe_signature(signode, mode, env, prefix, symbol) # type: ignore prefix += text_type(name) else: raise Exception('Unknown description mode: %s' % mode) @@ -1225,12 +1354,15 @@ class ASTNestedName(ASTBase): class ASTTrailingTypeSpecFundamental(ASTBase): def __init__(self, name): + # type: (unicode) -> None self.name = name def __unicode__(self): + # type: () -> unicode return self.name def get_id_v1(self): + # type: () -> unicode res = [] for a in self.name.split(' '): if a in _id_fundamental_v1: @@ -1240,6 +1372,7 @@ class ASTTrailingTypeSpecFundamental(ASTBase): return u'-'.join(res) def get_id_v2(self): + # type: () -> unicode if self.name not in _id_fundamental_v2: raise Exception( 'Semi-internal error: Fundamental type "%s" can not be mapped ' @@ -1248,26 +1381,32 @@ class ASTTrailingTypeSpecFundamental(ASTBase): return _id_fundamental_v2[self.name] def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None signode += nodes.Text(text_type(self.name)) class ASTTrailingTypeSpecName(ASTBase): def __init__(self, prefix, nestedName): + # type: (unicode, Any) -> None self.prefix = prefix self.nestedName = nestedName @property def name(self): + # type: () -> Any return self.nestedName def get_id_v1(self): + # type: () -> unicode return self.nestedName.get_id_v1() def get_id_v2(self): + # type: () -> unicode return self.nestedName.get_id_v2() def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.prefix: res.append(self.prefix) res.append(' ') @@ -1275,36 +1414,42 @@ class ASTTrailingTypeSpecName(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None if self.prefix: signode += addnodes.desc_annotation(self.prefix, self.prefix) signode += nodes.Text(' ') self.nestedName.describe_signature(signode, mode, env, symbol=symbol) -class ASTFunctinoParameter(ASTBase): +class ASTFunctionParameter(ASTBase): def __init__(self, arg, ellipsis=False): + # type: (Any, bool) -> None self.arg = arg self.ellipsis = ellipsis def get_id_v1(self): + # type: () -> unicode if self.ellipsis: return 'z' else: return self.arg.get_id_v1() def get_id_v2(self): + # type: () -> unicode if self.ellipsis: return 'z' else: return self.arg.get_id_v2() def __unicode__(self): + # type: () -> unicode if self.ellipsis: return '...' else: return text_type(self.arg) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) if self.ellipsis: signode += nodes.Text('...') @@ -1315,6 +1460,7 @@ class ASTFunctinoParameter(ASTBase): class ASTParametersQualifiers(ASTBase): def __init__(self, args, volatile, const, refQual, exceptionSpec, override, final, initializer): + # type: (List[Any], bool, bool, unicode, unicode, bool, bool, unicode) -> None self.args = args self.volatile = volatile self.const = const @@ -1327,6 +1473,7 @@ class ASTParametersQualifiers(ASTBase): # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode res = [] if self.volatile: res.append('V') @@ -1339,6 +1486,7 @@ class ASTParametersQualifiers(ASTBase): return u''.join(res) def get_param_id_v1(self): + # type: () -> unicode if len(self.args) == 0: return '' else: @@ -1347,6 +1495,7 @@ class ASTParametersQualifiers(ASTBase): # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode res = [] if self.volatile: res.append('V') @@ -1359,13 +1508,15 @@ class ASTParametersQualifiers(ASTBase): return u''.join(res) def get_param_id_v2(self): + # type: () -> unicode if len(self.args) == 0: return 'v' else: return u''.join(a.get_id_v2() for a in self.args) def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] res.append('(') first = True for a in self.args: @@ -1394,6 +1545,7 @@ class ASTParametersQualifiers(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) paramlist = addnodes.desc_parameterlist() for arg in self.args: @@ -1431,6 +1583,7 @@ class ASTParametersQualifiers(ASTBase): class ASTDeclSpecsSimple(ASTBase): def __init__(self, storage, threadLocal, inline, virtual, explicit, constexpr, volatile, const, friend, attrs): + # type: (unicode, bool, bool, bool, bool, bool, bool, bool, bool, List[Any]) -> None self.storage = storage self.threadLocal = threadLocal self.inline = inline @@ -1443,6 +1596,7 @@ class ASTDeclSpecsSimple(ASTBase): self.attrs = attrs def mergeWith(self, other): + # type: (ASTDeclSpecsSimple) -> ASTDeclSpecsSimple if not other: return self return ASTDeclSpecsSimple(self.storage or other.storage, @@ -1457,7 +1611,8 @@ class ASTDeclSpecsSimple(ASTBase): self.attrs + other.attrs) def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] res.extend(text_type(attr) for attr in self.attrs) if self.storage: res.append(self.storage) @@ -1480,6 +1635,7 @@ class ASTDeclSpecsSimple(ASTBase): return u' '.join(res) def describe_signature(self, modifiers): + # type: (List[nodes.Node]) -> None def _add(modifiers, text): if len(modifiers) > 0: modifiers.append(nodes.Text(' ')) @@ -1520,9 +1676,11 @@ class ASTDeclSpecs(ASTBase): @property def name(self): + # type: () -> unicode return self.trailingTypeSpec.name def get_id_v1(self): + # type: () -> unicode res = [] res.append(self.trailingTypeSpec.get_id_v1()) if self.allSpecs.volatile: @@ -1532,6 +1690,7 @@ class ASTDeclSpecs(ASTBase): return u''.join(res) def get_id_v2(self): + # type: () -> unicode res = [] if self.leftSpecs.volatile or self.rightSpecs.volatile: res.append('V') @@ -1541,7 +1700,8 @@ class ASTDeclSpecs(ASTBase): return u''.join(res) def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] l = text_type(self.leftSpecs) if len(l) > 0: if len(res) > 0: @@ -1559,8 +1719,9 @@ class ASTDeclSpecs(ASTBase): return "".join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) - modifiers = [] + modifiers = [] # type: List[nodes.Node] def _add(modifiers, text): if len(modifiers) > 0: @@ -1586,15 +1747,19 @@ class ASTDeclSpecs(ASTBase): class ASTArray(ASTBase): def __init__(self, size): + # type: (unicode) -> None self.size = size def __unicode__(self): + # type: () -> unicode return u''.join(['[', text_type(self.size), ']']) def get_id_v1(self): + # type: () -> unicode return u'A' def get_id_v2(self): + # type: () -> unicode # TODO: this should maybe be done differently return u'A' + text_type(self.size) + u'_' @@ -1605,6 +1770,7 @@ class ASTArray(ASTBase): class ASTDeclaratorPtr(ASTBase): def __init__(self, next, volatile, const): + # type: (Any, bool, bool) -> None assert next self.next = next self.volatile = volatile @@ -1612,14 +1778,17 @@ class ASTDeclaratorPtr(ASTBase): @property def name(self): + # type: () -> unicode return self.next.name def require_space_after_declSpecs(self): + # type: () -> bool # TODO: if has paramPack, then False ? return True def __unicode__(self): - res = ['*'] + # type: () -> unicode + res = ['*'] # type: List[unicode] if self.volatile: res.append('volatile') if self.const: @@ -1635,12 +1804,15 @@ class ASTDeclaratorPtr(ASTBase): # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode return self.next.get_modifiers_id_v1() def get_param_id_v1(self): + # type: () -> unicode return self.next.get_param_id_v1() def get_ptr_suffix_id_v1(self): + # type: () -> unicode res = 'P' if self.volatile: res += 'V' @@ -1651,13 +1823,16 @@ class ASTDeclaratorPtr(ASTBase): # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode return self.next.get_modifiers_id_v2() def get_param_id_v2(self): + # type: () -> unicode return self.next.get_param_id_v2() def get_ptr_suffix_id_v2(self): - res = [self.next.get_ptr_suffix_id_v2()] + # type: () -> unicode + res = [self.next.get_ptr_suffix_id_v2()] # type: List[unicode] res.append('P') if self.volatile: res.append('V') @@ -1666,8 +1841,9 @@ class ASTDeclaratorPtr(ASTBase): return u''.join(res) def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode # ReturnType *next, so we are part of the return type of 'next - res = ['P'] + res = ['P'] # type: List[unicode] if self.volatile: res.append('V') if self.const: @@ -1678,9 +1854,11 @@ class ASTDeclaratorPtr(ASTBase): # ------------------------------------------------------------------------ def is_function_type(self): + # type: () -> bool return self.next.is_function_type() def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text("*") @@ -1700,51 +1878,64 @@ class ASTDeclaratorPtr(ASTBase): class ASTDeclaratorRef(ASTBase): def __init__(self, next): + # type: (Any) -> None assert next self.next = next @property def name(self): + # type: () -> unicode return self.next.name def require_space_after_declSpecs(self): + # type: () -> bool return self.next.require_space_after_declSpecs() def __unicode__(self): + # type: () -> unicode return '&' + text_type(self.next) # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode return self.next.get_modifiers_id_v1() def get_param_id_v1(self): # only the parameters (if any) + # type: () -> unicode return self.next.get_param_id_v1() def get_ptr_suffix_id_v1(self): + # type: () -> unicode return u'R' + self.next.get_ptr_suffix_id_v1() # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode return self.next.get_modifiers_id_v2() def get_param_id_v2(self): # only the parameters (if any) + # type: () -> unicode return self.next.get_param_id_v2() def get_ptr_suffix_id_v2(self): + # type: () -> unicode return self.next.get_ptr_suffix_id_v2() + u'R' def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode # ReturnType &next, so we are part of the return type of 'next return self.next.get_type_id_v2(returnTypeId=u'R' + returnTypeId) # ------------------------------------------------------------------------ def is_function_type(self): + # type: () -> bool return self.next.is_function_type() def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text("&") self.next.describe_signature(signode, mode, env, symbol) @@ -1752,17 +1943,21 @@ class ASTDeclaratorRef(ASTBase): class ASTDeclaratorParamPack(ASTBase): def __init__(self, next): + # type: (Any) -> None assert next self.next = next @property def name(self): + # type: () -> unicode return self.next.name def require_space_after_declSpecs(self): + # type: () -> bool return False def __unicode__(self): + # type: () -> unicode res = text_type(self.next) if self.next.name: res = ' ' + res @@ -1771,35 +1966,43 @@ class ASTDeclaratorParamPack(ASTBase): # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode return self.next.get_modifiers_id_v1() def get_param_id_v1(self): # only the parameters (if any) + # type: () -> unicode return self.next.get_param_id_v1() def get_ptr_suffix_id_v1(self): + # type: () -> unicode return 'Dp' + self.next.get_ptr_suffix_id_v2() # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode return self.next.get_modifiers_id_v2() def get_param_id_v2(self): # only the parameters (if any) return self.next.get_param_id_v2() def get_ptr_suffix_id_v2(self): + # type: () -> unicode return self.next.get_ptr_suffix_id_v2() + u'Dp' def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode # ReturnType... next, so we are part of the return type of 'next return self.next.get_type_id_v2(returnTypeId=u'Dp' + returnTypeId) # ------------------------------------------------------------------------ def is_function_type(self): + # type: () -> bool return self.next.is_function_type() def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text("...") if self.next.name: @@ -1809,6 +2012,7 @@ class ASTDeclaratorParamPack(ASTBase): class ASTDeclaratorMemPtr(ASTBase): def __init__(self, className, const, volatile, next): + # type: (Any, bool, bool, Any) -> None assert className assert next self.className = className @@ -1818,12 +2022,15 @@ class ASTDeclaratorMemPtr(ASTBase): @property def name(self): + # type: () -> unicode return self.next.name def require_space_after_declSpecs(self): + # type: () -> bool return True def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.className)) res.append('::*') @@ -1839,29 +2046,36 @@ class ASTDeclaratorMemPtr(ASTBase): # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode raise NoOldIdError() def get_param_id_v1(self): # only the parameters (if any) + # type: () -> unicode raise NoOldIdError() def get_ptr_suffix_id_v1(self): + # type: () -> unicode raise NoOldIdError() # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode return self.next.get_modifiers_id_v2() def get_param_id_v2(self): # only the parameters (if any) + # type: () -> unicode return self.next.get_param_id_v2() def get_ptr_suffix_id_v2(self): + # type: () -> unicode raise NotImplementedError() return self.next.get_ptr_suffix_id_v2() + u'Dp' def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode # ReturnType name::* next, so we are part of the return type of next - nextReturnTypeId = '' + nextReturnTypeId = '' # type: unicode if self.volatile: nextReturnTypeId += 'V' if self.const: @@ -1874,9 +2088,11 @@ class ASTDeclaratorMemPtr(ASTBase): # ------------------------------------------------------------------------ def is_function_type(self): + # type: () -> bool return self.next.is_function_type() def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.className.describe_signature(signode, mode, env, symbol) signode += nodes.Text('::*') @@ -1897,6 +2113,7 @@ class ASTDeclaratorMemPtr(ASTBase): class ASTDeclaratorParen(ASTBase): def __init__(self, inner, next): + # type: (Any, Any) -> None assert inner assert next self.inner = inner @@ -1905,13 +2122,16 @@ class ASTDeclaratorParen(ASTBase): @property def name(self): + # type: () -> unicode return self.inner.name def require_space_after_declSpecs(self): + # type: () -> bool return True def __unicode__(self): - res = ['('] + # type: () -> unicode + res = ['('] # type: List[unicode] res.append(text_type(self.inner)) res.append(')') res.append(text_type(self.next)) @@ -1920,12 +2140,15 @@ class ASTDeclaratorParen(ASTBase): # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): + # type: () -> unicode return self.inner.get_modifiers_id_v1() def get_param_id_v1(self): # only the parameters (if any) + # type: () -> unicode return self.inner.get_param_id_v1() def get_ptr_suffix_id_v1(self): + # type: () -> unicode raise NoOldIdError() # TODO: was this implemented before? return self.next.get_ptr_suffix_id_v2() + \ self.inner.get_ptr_suffix_id_v2() @@ -1933,16 +2156,20 @@ class ASTDeclaratorParen(ASTBase): # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): + # type: () -> unicode return self.inner.get_modifiers_id_v2() def get_param_id_v2(self): # only the parameters (if any) + # type: () -> unicode return self.inner.get_param_id_v2() def get_ptr_suffix_id_v2(self): + # type: () -> unicode return self.inner.get_ptr_suffix_id_v2() + \ self.next.get_ptr_suffix_id_v2() def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode # ReturnType (inner)next, so 'inner' returns everything outside nextId = self.next.get_type_id_v2(returnTypeId) return self.inner.get_type_id_v2(returnTypeId=nextId) @@ -1950,9 +2177,11 @@ class ASTDeclaratorParen(ASTBase): # ------------------------------------------------------------------------ def is_function_type(self): + # type: () -> bool return self.inner.is_function_type() def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) signode += nodes.Text('(') self.inner.describe_signature(signode, mode, env, symbol) @@ -1960,19 +2189,22 @@ class ASTDeclaratorParen(ASTBase): self.next.describe_signature(signode, "noneIsName", env, symbol) -class ASTDecleratorNameParamQual(ASTBase): +class ASTDeclaratorNameParamQual(ASTBase): def __init__(self, declId, arrayOps, paramQual): + # type: (Any, List[Any], Any) -> None self.declId = declId self.arrayOps = arrayOps self.paramQual = paramQual @property def name(self): + # type: () -> unicode return self.declId # Id v1 ------------------------------------------------------------------ def get_modifiers_id_v1(self): # only the modifiers for a function, e.g., + # type: () -> unicode # cv-qualifiers if self.paramQual: return self.paramQual.get_modifiers_id_v1() @@ -1980,17 +2212,20 @@ class ASTDecleratorNameParamQual(ASTBase): "This should only be called on a function: %s" % text_type(self)) def get_param_id_v1(self): # only the parameters (if any) + # type: () -> unicode if self.paramQual: return self.paramQual.get_param_id_v1() else: return '' def get_ptr_suffix_id_v1(self): # only the array specifiers + # type: () -> unicode return u''.join(a.get_id_v1() for a in self.arrayOps) # Id v2 ------------------------------------------------------------------ def get_modifiers_id_v2(self): # only the modifiers for a function, e.g., + # type: () -> unicode # cv-qualifiers if self.paramQual: return self.paramQual.get_modifiers_id_v2() @@ -1998,15 +2233,18 @@ class ASTDecleratorNameParamQual(ASTBase): "This should only be called on a function: %s" % text_type(self)) def get_param_id_v2(self): # only the parameters (if any) + # type: () -> unicode if self.paramQual: return self.paramQual.get_param_id_v2() else: return '' def get_ptr_suffix_id_v2(self): # only the array specifiers + # type: () -> unicode return u''.join(a.get_id_v2() for a in self.arrayOps) def get_type_id_v2(self, returnTypeId): + # type: (unicode) -> unicode res = [] # TOOD: can we actually have both array ops and paramQual? res.append(self.get_ptr_suffix_id_v2()) @@ -2023,12 +2261,15 @@ class ASTDecleratorNameParamQual(ASTBase): # ------------------------------------------------------------------------ def require_space_after_declSpecs(self): + # type: () -> bool return self.declId is not None def is_function_type(self): + # type: () -> bool return self.paramQual is not None def __unicode__(self): + # type: () -> unicode res = [] if self.declId: res.append(text_type(self.declId)) @@ -2039,6 +2280,7 @@ class ASTDecleratorNameParamQual(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) if self.declId: self.declId.describe_signature(signode, mode, env, symbol) @@ -2050,18 +2292,22 @@ class ASTDecleratorNameParamQual(ASTBase): class ASTInitializer(ASTBase): def __init__(self, value): + # type: (unicode) -> None self.value = value def __unicode__(self): + # type: () -> unicode return u''.join([' = ', text_type(self.value)]) def describe_signature(self, signode, mode): + # type: (addnodes.desc_signature, unicode) -> None _verify_description_mode(mode) signode += nodes.Text(text_type(self)) class ASTType(ASTBase): def __init__(self, declSpecs, decl): + # type: (Any, Any) -> None assert declSpecs assert decl self.declSpecs = declSpecs @@ -2069,10 +2315,12 @@ class ASTType(ASTBase): @property def name(self): + # type: () -> unicode name = self.decl.name return name def get_id_v1(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode res = [] if objectType: # needs the name if objectType == 'function': # also modifiers @@ -2097,6 +2345,7 @@ class ASTType(ASTBase): return u''.join(res) def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode res = [] if objectType: # needs the name if objectType == 'function': # also modifiers @@ -2117,6 +2366,7 @@ class ASTType(ASTBase): return u''.join(res) def __unicode__(self): + # type: () -> unicode res = [] declSpecs = text_type(self.declSpecs) res.append(declSpecs) @@ -2126,12 +2376,14 @@ class ASTType(ASTBase): return u''.join(res) def get_type_declaration_prefix(self): + # type: () -> unicode if self.declSpecs.trailingTypeSpec: return 'typedef' else: return 'type' def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.declSpecs.describe_signature(signode, 'markType', env, symbol) if (self.decl.require_space_after_declSpecs() and @@ -2142,14 +2394,17 @@ class ASTType(ASTBase): class ASTTypeWithInit(ASTBase): def __init__(self, type, init): + # type: (Any, Any) -> None self.type = type self.init = init @property def name(self): + # type: () -> unicode return self.type.name def get_id_v1(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode if objectType == 'member': return symbol.get_full_nested_name().get_id_v1() + u'__' \ + self.type.get_id_v1() @@ -2157,12 +2412,14 @@ class ASTTypeWithInit(ASTBase): return self.type.get_id_v1(objectType) def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode if objectType == 'member': return symbol.get_full_nested_name().get_id_v2() else: return self.type.get_id_v2() def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.type)) if self.init: @@ -2170,6 +2427,7 @@ class ASTTypeWithInit(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.type.describe_signature(signode, mode, env, symbol=symbol) if self.init: @@ -2178,16 +2436,20 @@ class ASTTypeWithInit(ASTBase): class ASTTypeUsing(ASTBase): def __init__(self, name, type): + # type: (Any, Any) -> None self.name = name self.type = type def get_id_v1(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode raise NoOldIdError() def get_id_v2(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v2() def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.name)) if self.type: @@ -2196,9 +2458,11 @@ class ASTTypeUsing(ASTBase): return u''.join(res) def get_type_declaration_prefix(self): + # type: () -> unicode return 'using' def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.name.describe_signature(signode, mode, env, symbol=symbol) if self.type: @@ -2208,21 +2472,26 @@ class ASTTypeUsing(ASTBase): class ASTConcept(ASTBase): def __init__(self, nestedName, isFunction, initializer): + # type: (Any, bool, Any) -> None self.nestedName = nestedName self.isFunction = isFunction # otherwise it's a variable concept self.initializer = initializer @property def name(self): + # type: () -> unicode return self.nestedName def get_id_v1(self, objectType=None, symbol=None): + # type: (unicode, Symbol) -> unicode raise NoOldIdError() - def get_id_v2(self, objectType, symbol): + def get_id_v2(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v2() def __unicode__(self): + # type: () -> unicode res = text_type(self.nestedName) if self.isFunction: res += "()" @@ -2231,6 +2500,7 @@ class ASTConcept(ASTBase): return res def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None signode += nodes.Text(text_type("bool ")) self.nestedName.describe_signature(signode, mode, env, symbol) if self.isFunction: @@ -2241,13 +2511,15 @@ class ASTConcept(ASTBase): class ASTBaseClass(ASTBase): def __init__(self, name, visibility, virtual, pack): + # type: (Any, unicode, bool, bool) -> None self.name = name self.visibility = visibility self.virtual = virtual self.pack = pack def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.visibility != 'private': res.append(self.visibility) res.append(' ') @@ -2259,6 +2531,7 @@ class ASTBaseClass(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) if self.visibility != 'private': signode += addnodes.desc_annotation(self.visibility, @@ -2274,17 +2547,21 @@ class ASTBaseClass(ASTBase): class ASTClass(ASTBase): def __init__(self, name, final, bases): + # type: (Any, bool, List[Any]) -> None self.name = name self.final = final self.bases = bases - def get_id_v1(self, objectType, symbol): + def get_id_v1(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v1() - def get_id_v2(self, objectType, symbol): + def get_id_v2(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v2() def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.name)) if self.final: @@ -2300,6 +2577,7 @@ class ASTClass(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.name.describe_signature(signode, mode, env, symbol=symbol) if self.final: @@ -2315,18 +2593,22 @@ class ASTClass(ASTBase): class ASTEnum(ASTBase): def __init__(self, name, scoped, underlyingType): + # type: (Any, unicode, Any) -> None self.name = name self.scoped = scoped self.underlyingType = underlyingType - def get_id_v1(self, objectType, symbol): + def get_id_v1(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode raise NoOldIdError() - def get_id_v2(self, objectType, symbol): + def get_id_v2(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v2() def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.scoped: res.append(self.scoped) res.append(' ') @@ -2337,6 +2619,7 @@ class ASTEnum(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) # self.scoped has been done by the CPPEnumObject self.name.describe_signature(signode, mode, env, symbol=symbol) @@ -2348,16 +2631,20 @@ class ASTEnum(ASTBase): class ASTEnumerator(ASTBase): def __init__(self, name, init): + # type: (Any, Any) -> None self.name = name self.init = init - def get_id_v1(self, objectType, symbol): + def get_id_v1(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode raise NoOldIdError() - def get_id_v2(self, objectType, symbol): + def get_id_v2(self, objectType, symbol): # type: ignore + # type: (unicode, Symbol) -> unicode return symbol.get_full_nested_name().get_id_v2() def __unicode__(self): + # type: () -> unicode res = [] res.append(text_type(self.name)) if self.init: @@ -2365,6 +2652,7 @@ class ASTEnumerator(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env, symbol): + # type: (addnodes.desc_signature, unicode, BuildEnvironment, Symbol) -> None _verify_description_mode(mode) self.name.describe_signature(signode, mode, env, symbol=symbol) if self.init: @@ -2373,16 +2661,18 @@ class ASTEnumerator(ASTBase): class ASTDeclaration(ASTBase): def __init__(self, objectType, visibility, templatePrefix, declaration): + # type: (unicode, unicode, Any, Any) -> None self.objectType = objectType self.visibility = visibility self.templatePrefix = templatePrefix self.declaration = declaration - self.symbol = None + self.symbol = None # type: Symbol # set by CPPObject._add_enumerator_to_parent - self.enumeratorScopedSymbol = None + self.enumeratorScopedSymbol = None # type: Any def clone(self): + # type: () -> ASTDeclaration if self.templatePrefix: templatePrefixClone = self.templatePrefix.clone() else: @@ -2393,9 +2683,11 @@ class ASTDeclaration(ASTBase): @property def name(self): + # type: () -> unicode return self.declaration.name def get_id_v1(self): + # type: () -> unicode if self.templatePrefix: raise NoOldIdError() if self.objectType == 'enumerator' and self.enumeratorScopedSymbol: @@ -2403,6 +2695,7 @@ class ASTDeclaration(ASTBase): return self.declaration.get_id_v1(self.objectType, self.symbol) def get_id_v2(self, prefixed=True): + # type: (bool) -> unicode if self.objectType == 'enumerator' and self.enumeratorScopedSymbol: return self.enumeratorScopedSymbol.declaration.get_id_v2(prefixed) if prefixed: @@ -2415,10 +2708,12 @@ class ASTDeclaration(ASTBase): return u''.join(res) def get_newest_id(self): + # type: () -> unicode return self.get_id_v2() def __unicode__(self): - res = [] + # type: () -> unicode + res = [] # type: List[unicode] if self.visibility and self.visibility != "public": res.append(self.visibility) res.append(u' ') @@ -2428,6 +2723,7 @@ class ASTDeclaration(ASTBase): return u''.join(res) def describe_signature(self, signode, mode, env): + # type: (addnodes.desc_signature, unicode, BuildEnvironment) -> None _verify_description_mode(mode) # The caller of the domain added a desc_signature node. # Always enable multiline: @@ -2459,8 +2755,8 @@ class ASTDeclaration(ASTBase): mainDeclNode += addnodes.desc_annotation('class ', 'class ') elif self.objectType == 'enum': prefix = 'enum ' - if self.scoped: - prefix += self.scoped + if self.scoped: # type: ignore + prefix += self.scoped # type: ignore prefix += ' ' mainDeclNode += addnodes.desc_annotation(prefix, prefix) elif self.objectType == 'enumerator': @@ -2473,12 +2769,14 @@ class ASTDeclaration(ASTBase): class ASTNamespace(ASTBase): def __init__(self, nestedName, templatePrefix): + # type: (Any, Any) -> None self.nestedName = nestedName self.templatePrefix = templatePrefix class Symbol(object): def _assert_invariants(self): + # type: () -> None if not self.parent: # parent == None means global scope, so declaration means a parent assert not self.identifier @@ -2495,6 +2793,7 @@ class Symbol(object): def __init__(self, parent, identifier, templateParams, templateArgs, declaration, docname): + # type: (Any, Any, Any, Any, Any, unicode) -> None self.parent = parent self.identifier = identifier self.templateParams = templateParams # template<templateParams> @@ -2503,7 +2802,7 @@ class Symbol(object): self.docname = docname self._assert_invariants() - self.children = [] + self.children = [] # type: List[Any] if self.parent: self.parent.children.append(self) if self.declaration: @@ -2524,6 +2823,7 @@ class Symbol(object): self._add_symbols(nn, [], decl, docname) def _fill_empty(self, declaration, docname): + # type: (Any, unicode) -> None self._assert_invariants() assert not self.declaration assert not self.docname @@ -2535,6 +2835,7 @@ class Symbol(object): self._assert_invariants() def clear_doc(self, docname): + # type: (unicode) -> None newChildren = [] for sChild in self.children: sChild.clear_doc(docname) @@ -2550,12 +2851,14 @@ class Symbol(object): self.children = newChildren def get_all_symbols(self): + # type: () -> Iterator[Any] yield self for sChild in self.children: for s in sChild.get_all_symbols(): yield s def get_lookup_key(self): + # type: () -> List[Tuple[ASTNestedNameElement, Any]] if not self.parent: # specialise for the root return None @@ -2576,6 +2879,7 @@ class Symbol(object): return key def get_full_nested_name(self): + # type: () -> ASTNestedName names = [] for nne, templateParams in self.get_lookup_key(): names.append(nne) @@ -2584,6 +2888,7 @@ class Symbol(object): def _find_named_symbol(self, identifier, templateParams, templateArgs, operator, templateShorthand, matchSelf): + # type: (Any, Any, Any, Any, Any, bool) -> Symbol assert (identifier is None) != (operator is None) def matches(s): @@ -2624,6 +2929,7 @@ class Symbol(object): return None def _add_symbols(self, nestedName, templateDecls, declaration, docname): + # type: (Any, List[Any], Any, unicode) -> Symbol # This condition should be checked at the parser level. # Each template argument list must have a template parameter list. # But to declare a template there must be an additional template parameter list. @@ -2722,6 +3028,7 @@ class Symbol(object): return symbol def merge_with(self, other, docnames, env): + # type: (Any, List[unicode], BuildEnvironment) -> None assert other is not None for otherChild in other.children: if not otherChild.identifier: @@ -2756,7 +3063,7 @@ class Symbol(object): msg = "Duplicate declaration, also defined in '%s'.\n" msg += "Declaration is '%s'." msg = msg % (ourChild.docname, name) - env.warn(otherChild.docname, msg) + logger.warning(msg, location=otherChild.docname) else: # Both have declarations, and in the same docname. # This can apparently happen, it should be safe to @@ -2765,6 +3072,7 @@ class Symbol(object): ourChild.merge_with(otherChild, docnames, env) def add_name(self, nestedName, templatePrefix=None): + # type: (unicode, Any) -> Symbol if templatePrefix: templateDecls = templatePrefix.templates else: @@ -2773,6 +3081,7 @@ class Symbol(object): declaration=None, docname=None) def add_declaration(self, declaration, docname): + # type: (Any, unicode) -> Symbol assert declaration assert docname nestedName = declaration.name @@ -2783,6 +3092,7 @@ class Symbol(object): return self._add_symbols(nestedName, templateDecls, declaration, docname) def find_identifier(self, identifier, matchSelf): + # type: (Any, bool) -> Symbol if matchSelf and self.identifier and self.identifier == identifier: return self for s in self.children: @@ -2791,6 +3101,7 @@ class Symbol(object): return None def direct_lookup(self, key): + # type: (List[Tuple[Any, Any]]) -> Symbol s = self for name, templateParams in key: if name.is_operator(): @@ -2810,6 +3121,7 @@ class Symbol(object): return s def find_name(self, nestedName, templateDecls, templateShorthand, matchSelf): + # type: (Any, Any, Any, bool) -> Symbol # templateShorthand: missing template parameter lists for templates is ok # TODO: unify this with the _add_symbols @@ -2885,7 +3197,8 @@ class Symbol(object): assert False # should have returned in the loop def to_string(self, indent): - res = ['\t'*indent] + # type: (int) -> unicode + res = ['\t'*indent] # type: List[unicode] if not self.parent: res.append('::') else: @@ -2910,6 +3223,7 @@ class Symbol(object): return ''.join(res) def dump(self, indent): + # type: (int) -> unicode res = [self.to_string(indent)] for c in self.children: res.append(c.dump(indent + 1)) @@ -2927,16 +3241,18 @@ class DefinitionParser(object): _prefix_keys = ('class', 'struct', 'enum', 'union', 'typename') def __init__(self, definition, warnEnv, config): + # type: (Any, Any, Config) -> None self.definition = definition.strip() self.pos = 0 self.end = len(self.definition) - self.last_match = None - self._previous_state = (0, None) + self.last_match = None # type: Match + self._previous_state = (0, None) # type: Tuple[int, Match] self.warnEnv = warnEnv self.config = config def _make_multi_error(self, errors, header): + # type: (List[Any], unicode) -> DefinitionError if len(errors) == 1: return DefinitionError(header + '\n' + errors[0][0].description) result = [header, '\n'] @@ -2956,23 +3272,27 @@ class DefinitionParser(object): return DefinitionError(''.join(result)) def status(self, msg): + # type: (unicode) -> unicode # for debugging indicator = '-' * self.pos + '^' print("%s\n%s\n%s" % (msg, self.definition, indicator)) def fail(self, msg): + # type: (unicode) -> None indicator = '-' * self.pos + '^' raise DefinitionError( 'Invalid definition: %s [error at %d]\n %s\n %s' % (msg, self.pos, self.definition, indicator)) def warn(self, msg): + # type: (unicode) -> None if self.warnEnv: self.warnEnv.warn(msg) else: print("Warning: %s" % msg) def match(self, regex): + # type: (Pattern) -> bool match = regex.match(self.definition, self.pos) if match is not None: self._previous_state = (self.pos, self.last_match) @@ -2982,9 +3302,11 @@ class DefinitionParser(object): return False def backout(self): + # type: () -> None self.pos, self.last_match = self._previous_state def skip_string(self, string): + # type: (unicode) -> bool strlen = len(string) if self.definition[self.pos:self.pos + strlen] == string: self.pos += strlen @@ -2992,18 +3314,22 @@ class DefinitionParser(object): return False def skip_word(self, word): + # type: (unicode) -> bool return self.match(re.compile(r'\b%s\b' % re.escape(word))) def skip_ws(self): + # type: () -> bool return self.match(_whitespace_re) def skip_word_and_ws(self, word): + # type: (unicode) -> bool if self.skip_word(word): self.skip_ws() return True return False def skip_string_and_ws(self, string): + # type: (unicode) -> bool if self.skip_string(string): self.skip_ws() return True @@ -3011,10 +3337,12 @@ class DefinitionParser(object): @property def eof(self): + # type: () -> bool return self.pos >= self.end @property def current_char(self): + # type: () -> unicode try: return self.definition[self.pos] except IndexError: @@ -3022,24 +3350,28 @@ class DefinitionParser(object): @property def matched_text(self): + # type: () -> unicode if self.last_match is not None: return self.last_match.group() def read_rest(self): + # type: () -> unicode rv = self.definition[self.pos:] self.pos = self.end return rv def assert_end(self): + # type: () -> None self.skip_ws() if not self.eof: self.fail('Expected end of definition.') def _parse_balanced_token_seq(self, end): + # type: (List[unicode]) -> unicode # TODO: add handling of string literals and similar - brackets = {'(': ')', '[': ']', '{': '}'} + brackets = {'(': ')', '[': ']', '{': '}'} # type: Dict[unicode, unicode] startPos = self.pos - symbols = [] + symbols = [] # type: List[unicode] while not self.eof: if len(symbols) == 0 and self.current_char in end: break @@ -3056,6 +3388,7 @@ class DefinitionParser(object): return self.definition[startPos:self.pos] def _parse_attribute(self): + # type: () -> Any self.skip_ws() # try C++11 style startPos = self.pos @@ -3115,6 +3448,7 @@ class DefinitionParser(object): return None def _parse_expression(self, end): + # type: (List[unicode]) -> unicode # Stupidly "parse" an expression. # 'end' should be a list of characters which ends the expression. assert end @@ -3124,8 +3458,8 @@ class DefinitionParser(object): value = self.matched_text else: # TODO: add handling of more bracket-like things, and quote handling - brackets = {'(': ')', '[': ']'} - symbols = [] + brackets = {'(': ')', '[': ']'} # type: Dict[unicode, unicode] + symbols = [] # type: List[unicode] while not self.eof: if (len(symbols) == 0 and self.current_char in end): break @@ -3141,6 +3475,7 @@ class DefinitionParser(object): return value.strip() def _parse_operator(self): + # type: () -> Any self.skip_ws() # adapted from the old code # thank god, a regular operator definition @@ -3173,11 +3508,12 @@ class DefinitionParser(object): return ASTOperatorType(type) def _parse_template_argument_list(self): + # type: () -> ASTTemplateArgs self.skip_ws() if not self.skip_string('<'): return None prevErrors = [] - templateArgs = [] + templateArgs = [] # type: List while 1: pos = self.pos parsedComma = False @@ -3216,6 +3552,7 @@ class DefinitionParser(object): return ASTTemplateArgs(templateArgs) def _parse_nested_name(self, memberPointer=False): + # type: (bool) -> ASTNestedName names = [] self.skip_ws() @@ -3240,7 +3577,7 @@ class DefinitionParser(object): self.fail("Expected identifier in nested name, " "got keyword: %s" % identifier) templateArgs = self._parse_template_argument_list() - identifier = ASTIdentifier(identifier) + identifier = ASTIdentifier(identifier) # type: ignore names.append(ASTNestedNameElement(identifier, templateArgs)) self.skip_ws() @@ -3251,6 +3588,7 @@ class DefinitionParser(object): return ASTNestedName(names, rooted) def _parse_trailing_type_spec(self): + # type: () -> Any # fundemental types self.skip_ws() for t in self._simple_fundemental_types: @@ -3296,6 +3634,7 @@ class DefinitionParser(object): return ASTTrailingTypeSpecName(prefix, nestedName) def _parse_parameters_and_qualifiers(self, paramMode): + # type: (unicode) -> ASTParametersQualifiers self.skip_ws() if not self.skip_string('('): if paramMode == 'function': @@ -3308,7 +3647,7 @@ class DefinitionParser(object): while 1: self.skip_ws() if self.skip_string('...'): - args.append(ASTFunctinoParameter(None, True)) + args.append(ASTFunctionParameter(None, True)) self.skip_ws() if not self.skip_string(')'): self.fail('Expected ")" after "..." in ' @@ -3318,7 +3657,7 @@ class DefinitionParser(object): # even in function pointers and similar. arg = self._parse_type_with_init(outer=None, named='single') # TODO: parse default parameters # TODO: didn't we just do that? - args.append(ASTFunctinoParameter(arg)) + args.append(ASTFunctionParameter(arg)) self.skip_ws() if self.skip_string(','): @@ -3385,6 +3724,7 @@ class DefinitionParser(object): initializer) def _parse_decl_specs_simple(self, outer, typed): + # type: (unicode, bool) -> ASTDeclSpecsSimple """Just parse the simple ones.""" storage = None threadLocal = None @@ -3459,6 +3799,7 @@ class DefinitionParser(object): friend, attrs) def _parse_decl_specs(self, outer, typed=True): + # type: (unicode, bool) -> ASTDeclSpecs if outer: if outer not in ('type', 'member', 'function', 'templateParam'): raise Exception('Internal error, unknown outer "%s".' % outer) @@ -3486,6 +3827,7 @@ class DefinitionParser(object): return ASTDeclSpecs(outer, leftSpecs, rightSpecs, trailing) def _parse_declarator_name_param_qual(self, named, paramMode, typed): + # type: (Union[bool, unicode], unicode, bool) -> ASTDeclaratorNameParamQual # now we should parse the name, and then suffixes if named == 'maybe': pos = self.pos @@ -3521,10 +3863,11 @@ class DefinitionParser(object): else: break paramQual = self._parse_parameters_and_qualifiers(paramMode) - return ASTDecleratorNameParamQual(declId=declId, arrayOps=arrayOps, + return ASTDeclaratorNameParamQual(declId=declId, arrayOps=arrayOps, paramQual=paramQual) - def _parse_declerator(self, named, paramMode, typed=True): + def _parse_declarator(self, named, paramMode, typed=True): + # type: (Union[bool, unicode], unicode, bool) -> Any # 'typed' here means 'parse return type stuff' if paramMode not in ('type', 'function', 'operatorCast'): raise Exception( @@ -3545,14 +3888,14 @@ class DefinitionParser(object): if const: continue break - next = self._parse_declerator(named, paramMode, typed) + next = self._parse_declarator(named, paramMode, typed) return ASTDeclaratorPtr(next=next, volatile=volatile, const=const) # TODO: shouldn't we parse an R-value ref here first? if typed and self.skip_string("&"): - next = self._parse_declerator(named, paramMode, typed) + next = self._parse_declarator(named, paramMode, typed) return ASTDeclaratorRef(next=next) if typed and self.skip_string("..."): - next = self._parse_declerator(named, paramMode, False) + next = self._parse_declarator(named, paramMode, False) return ASTDeclaratorParamPack(next=next) if typed: # pointer to member pos = self.pos @@ -3578,13 +3921,13 @@ class DefinitionParser(object): if const: continue break - next = self._parse_declerator(named, paramMode, typed) + next = self._parse_declarator(named, paramMode, typed) return ASTDeclaratorMemPtr(name, const, volatile, next=next) if typed and self.current_char == '(': # note: peeking, not skipping if paramMode == "operatorCast": # TODO: we should be able to parse cast operators which return # function pointers. For now, just hax it and ignore. - return ASTDecleratorNameParamQual(declId=None, arrayOps=[], + return ASTDeclaratorNameParamQual(declId=None, arrayOps=[], paramQual=None) # maybe this is the beginning of params and quals,try that first, # otherwise assume it's noptr->declarator > ( ptr-declarator ) @@ -3603,10 +3946,10 @@ class DefinitionParser(object): # TODO: hmm, if there is a name, it must be in inner, right? # TODO: hmm, if there must be parameters, they must b # inside, right? - inner = self._parse_declerator(named, paramMode, typed) + inner = self._parse_declarator(named, paramMode, typed) if not self.skip_string(')'): self.fail("Expected ')' in \"( ptr-declarator )\"") - next = self._parse_declerator(named=False, + next = self._parse_declarator(named=False, paramMode="type", typed=typed) return ASTDeclaratorParen(inner=inner, next=next) @@ -3625,13 +3968,14 @@ class DefinitionParser(object): raise self._make_multi_error(prevErrors, header) def _parse_initializer(self, outer=None): + # type: (unicode) -> ASTInitializer self.skip_ws() # TODO: support paren and brace initialization for memberObject if not self.skip_string('='): return None else: if outer == 'member': - value = self.read_rest().strip() + value = self.read_rest().strip() # type: unicode elif outer == 'templateParam': value = self._parse_expression(end=[',', '>']) elif outer is None: # function parameter @@ -3642,6 +3986,7 @@ class DefinitionParser(object): return ASTInitializer(value) def _parse_type(self, named, outer=None): + # type: (Union[bool, unicode], unicode) -> ASTType """ named=False|'maybe'|True: 'maybe' is e.g., for function objects which doesn't need to name the arguments @@ -3664,7 +4009,7 @@ class DefinitionParser(object): # first try without the type try: declSpecs = self._parse_decl_specs(outer=outer, typed=False) - decl = self._parse_declerator(named=True, paramMode=outer, + decl = self._parse_declarator(named=True, paramMode=outer, typed=False) self.assert_end() except DefinitionError as exUntyped: @@ -3678,7 +4023,7 @@ class DefinitionParser(object): self.pos = startPos try: declSpecs = self._parse_decl_specs(outer=outer) - decl = self._parse_declerator(named=True, paramMode=outer) + decl = self._parse_declarator(named=True, paramMode=outer) except DefinitionError as exTyped: self.pos = startPos if outer == 'type': @@ -3709,7 +4054,7 @@ class DefinitionParser(object): self.pos = startPos typed = True declSpecs = self._parse_decl_specs(outer=outer, typed=typed) - decl = self._parse_declerator(named=True, paramMode=outer, + decl = self._parse_declarator(named=True, paramMode=outer, typed=typed) else: paramMode = 'type' @@ -3721,10 +4066,11 @@ class DefinitionParser(object): elif outer == 'templateParam': named = 'single' declSpecs = self._parse_decl_specs(outer=outer) - decl = self._parse_declerator(named=named, paramMode=paramMode) + decl = self._parse_declarator(named=named, paramMode=paramMode) return ASTType(declSpecs, decl) def _parse_type_with_init(self, named, outer): + # type: (Union[bool, unicode], unicode) -> ASTTypeWithInit if outer: assert outer in ('type', 'member', 'function', 'templateParam') type = self._parse_type(outer=outer, named=named) @@ -3732,6 +4078,7 @@ class DefinitionParser(object): return ASTTypeWithInit(type, init) def _parse_type_using(self): + # type: () -> ASTTypeUsing name = self._parse_nested_name() self.skip_ws() if not self.skip_string('='): @@ -3740,6 +4087,7 @@ class DefinitionParser(object): return ASTTypeUsing(name, type) def _parse_concept(self): + # type: () -> ASTConcept nestedName = self._parse_nested_name() isFunction = False @@ -3757,6 +4105,7 @@ class DefinitionParser(object): return ASTConcept(nestedName, isFunction, initializer) def _parse_class(self): + # type: () -> ASTClass name = self._parse_nested_name() self.skip_ws() final = self.skip_word_and_ws('final') @@ -3765,7 +4114,7 @@ class DefinitionParser(object): if self.skip_string(':'): while 1: self.skip_ws() - visibility = 'private' + visibility = 'private' # type: unicode virtual = False pack = False if self.skip_word_and_ws('virtual'): @@ -3787,7 +4136,8 @@ class DefinitionParser(object): return ASTClass(name, final, bases) def _parse_enum(self): - scoped = None # is set by CPPEnumObject + # type: () -> ASTEnum + scoped = None # type: unicode # is set by CPPEnumObject self.skip_ws() name = self._parse_nested_name() self.skip_ws() @@ -3797,6 +4147,7 @@ class DefinitionParser(object): return ASTEnum(name, scoped, underlyingType) def _parse_enumerator(self): + # type: () -> ASTEnumerator name = self._parse_nested_name() self.skip_ws() init = None @@ -3806,9 +4157,10 @@ class DefinitionParser(object): return ASTEnumerator(name, init) def _parse_template_parameter_list(self): + # type: () -> ASTTemplateParams # only: '<' parameter-list '>' # we assume that 'template' has just been parsed - templateParams = [] + templateParams = [] # type: List self.skip_ws() if not self.skip_string("<"): self.fail("Expected '<' after 'template'") @@ -3847,7 +4199,7 @@ class DefinitionParser(object): parameterPack, default) if nestedParams: # template type - param = ASTTemplateParamTemplateType(nestedParams, data) + param = ASTTemplateParamTemplateType(nestedParams, data) # type: Any else: # type param = ASTTemplateParamType(data) @@ -3875,6 +4227,7 @@ class DefinitionParser(object): raise self._make_multi_error(prevErrors, header) def _parse_template_introduction(self): + # type: () -> ASTTemplateIntroduction pos = self.pos try: concept = self._parse_nested_name() @@ -3899,7 +4252,7 @@ class DefinitionParser(object): if identifier in _keywords: self.fail("Expected identifier in template introduction list, " "got keyword: %s" % identifier) - identifier = ASTIdentifier(identifier) + identifier = ASTIdentifier(identifier) # type: ignore params.append(ASTTemplateIntroductionParameter(identifier, parameterPack)) self.skip_ws() @@ -3913,13 +4266,14 @@ class DefinitionParser(object): return ASTTemplateIntroduction(concept, params) def _parse_template_declaration_prefix(self, objectType): - templates = [] + # type: (unicode) -> ASTTemplateDeclarationPrefix + templates = [] # type: List while 1: self.skip_ws() # the saved position is only used to provide a better error message pos = self.pos if self.skip_word("template"): - params = self._parse_template_parameter_list() + params = self._parse_template_parameter_list() # type: Any else: params = self._parse_template_introduction() if not params: @@ -3937,6 +4291,7 @@ class DefinitionParser(object): def _check_template_consistency(self, nestedName, templatePrefix, fullSpecShorthand): + # type: (Any, Any, bool) -> ASTTemplateDeclarationPrefix numArgs = nestedName.num_templates() if not templatePrefix: numParams = 0 @@ -3952,7 +4307,7 @@ class DefinitionParser(object): msg = "Too many template argument lists compared to parameter" \ " lists. Argument lists: %d, Parameter lists: %d," \ " Extra empty parameters lists prepended: %d." \ - % (numArgs, numParams, numExtra) + % (numArgs, numParams, numExtra) # type: unicode msg += " Declaration:\n\t" if templatePrefix: msg += "%s\n\t" % text_type(templatePrefix) @@ -3968,12 +4323,13 @@ class DefinitionParser(object): return templatePrefix def parse_declaration(self, objectType): + # type: (unicode) -> ASTDeclaration if objectType not in ('type', 'concept', 'member', 'function', 'class', 'enum', 'enumerator'): raise Exception('Internal error, unknown objectType "%s".' % objectType) visibility = None templatePrefix = None - declaration = None + declaration = None # type: Any self.skip_ws() if self.match(_visibility_re): @@ -4021,6 +4377,7 @@ class DefinitionParser(object): templatePrefix, declaration) def parse_namespace_object(self): + # type: () -> ASTNamespace templatePrefix = self._parse_template_declaration_prefix(objectType="namespace") name = self._parse_nested_name() templatePrefix = self._check_template_consistency(name, templatePrefix, @@ -4030,6 +4387,7 @@ class DefinitionParser(object): return res def parse_xref_object(self): + # type: () -> ASTNamespace templatePrefix = self._parse_template_declaration_prefix(objectType="xref") name = self._parse_nested_name() templatePrefix = self._check_template_consistency(name, templatePrefix, @@ -4040,6 +4398,7 @@ class DefinitionParser(object): def _make_phony_error_name(): + # type: () -> ASTNestedName nne = ASTNestedNameElement(ASTIdentifier("PhonyNameDueToError"), None) return ASTNestedName([nne], rooted=False) @@ -4062,9 +4421,11 @@ class CPPObject(ObjectDescription): ] def warn(self, msg): + # type: (unicode) -> None self.state_machine.reporter.warning(msg, line=self.lineno) def _add_enumerator_to_parent(self, ast): + # type: (Any) -> None assert ast.objectType == 'enumerator' # find the parent, if it exists && is an enum # && it's unscoped, @@ -4106,6 +4467,7 @@ class CPPObject(ObjectDescription): docname=self.env.docname) def add_target_and_index(self, ast, sig, signode): + # type: (Any, unicode, addnodes.desc_signature) -> None # general note: name must be lstrip(':')'ed, to remove "::" try: id_v1 = ast.get_id_v1() @@ -4152,12 +4514,15 @@ class CPPObject(ObjectDescription): self.state.document.note_explicit_target(signode) def parse_definition(self, parser): + # type: (Any) -> Any raise NotImplementedError() def describe_signature(self, signode, ast, parentScope): + # type: (addnodes.desc_signature, Any, Any) -> None raise NotImplementedError() def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> Any if 'cpp:parent_symbol' not in self.env.ref_context: root = self.env.domaindata['cpp']['root_symbol'] self.env.ref_context['cpp:parent_symbol'] = root @@ -4191,75 +4556,94 @@ class CPPObject(ObjectDescription): return ast def before_content(self): + # type: () -> None lastSymbol = self.env.ref_context['cpp:last_symbol'] assert lastSymbol self.oldParentSymbol = self.env.ref_context['cpp:parent_symbol'] self.env.ref_context['cpp:parent_symbol'] = lastSymbol def after_content(self): + # type: () -> None self.env.ref_context['cpp:parent_symbol'] = self.oldParentSymbol class CPPTypeObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ type)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("type") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPConceptObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ concept)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("concept") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPMemberObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ member)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("member") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPFunctionObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ function)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("function") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPClassObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ class)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("class") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPEnumObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ enum)') % name def parse_definition(self, parser): + # type: (Any) -> Any ast = parser.parse_declaration("enum") # self.objtype is set by ObjectDescription in run() if self.objtype == "enum": @@ -4272,18 +4656,22 @@ class CPPEnumObject(CPPObject): assert False return ast - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) class CPPEnumeratorObject(CPPObject): def get_index_text(self, name): + # type: (unicode) -> unicode return _('%s (C++ enumerator)') % name def parse_definition(self, parser): + # type: (Any) -> Any return parser.parse_declaration("enumerator") - def describe_signature(self, signode, ast): + def describe_signature(self, signode, ast): # type: ignore + # type: (addnodes.desc_signature, Any) -> None ast.describe_signature(signode, 'lastIsName', self.env) @@ -4297,17 +4685,19 @@ class CPPNamespaceObject(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def warn(self, msg): + # type: (unicode) -> None self.state_machine.reporter.warning(msg, line=self.lineno) def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env rootSymbol = env.domaindata['cpp']['root_symbol'] if self.arguments[0].strip() in ('NULL', '0', 'nullptr'): symbol = rootSymbol - stack = [] + stack = [] # type: List[Symbol] else: parser = DefinitionParser(self.arguments[0], self, env.config) try: @@ -4329,12 +4719,14 @@ class CPPNamespacePushObject(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def warn(self, msg): + # type: (unicode) -> None self.state_machine.reporter.warning(msg, line=self.lineno) def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env if self.arguments[0].strip() in ('NULL', '0', 'nullptr'): return @@ -4362,12 +4754,14 @@ class CPPNamespacePopObject(Directive): required_arguments = 0 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def warn(self, msg): + # type: (unicode) -> None self.state_machine.reporter.warning(msg, line=self.lineno) def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env stack = env.temp_data.get('cpp:namespace_stack', None) if not stack or len(stack) == 0: @@ -4386,6 +4780,7 @@ class CPPNamespacePopObject(Directive): class CPPXRefRole(XRefRole): def process_link(self, env, refnode, has_explicit_title, title, target): + # type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA parent = env.ref_context.get('cpp:parent_symbol', None) if parent: refnode['cpp:parent_key'] = parent.get_lookup_key() @@ -4455,6 +4850,7 @@ class CPPDomain(Domain): } def clear_doc(self, docname): + # type: (unicode) -> None rootSymbol = self.data['root_symbol'] rootSymbol.clear_doc(docname) for name, nDocname in list(self.data['names'].items()): @@ -4462,12 +4858,14 @@ class CPPDomain(Domain): del self.data['names'][name] def process_doc(self, env, docname, document): + # type: (BuildEnvironment, unicode, nodes.Node) -> None # just for debugging # print(docname) # print(self.data['root_symbol'].dump(0)) pass def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None self.data['root_symbol'].merge_with(otherdata['root_symbol'], docnames, self.env) ourNames = self.data['names'] @@ -4477,16 +4875,17 @@ class CPPDomain(Domain): msg = "Duplicate declaration, also defined in '%s'.\n" msg += "Name of declaration is '%s'." msg = msg % (ourNames[name], name) - self.env.warn(docname, msg) + logger.warning(msg, docname) else: ourNames[name] = docname def _resolve_xref_inner(self, env, fromdocname, builder, typ, target, node, contnode, emitWarnings=True): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node, bool) -> nodes.Node # NOQA class Warner(object): def warn(self, msg): if emitWarnings: - env.warn_node(msg, node) + logger.warning(msg, location=node) warner = Warner() parser = DefinitionParser(target, warner, env.config) try: @@ -4562,11 +4961,13 @@ class CPPDomain(Domain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA return self._resolve_xref_inner(env, fromdocname, builder, typ, target, node, contnode)[0] def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA node, objtype = self._resolve_xref_inner(env, fromdocname, builder, 'any', target, node, contnode, emitWarnings=False) @@ -4575,6 +4976,7 @@ class CPPDomain(Domain): return [] def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] rootSymbol = self.data['root_symbol'] for symbol in rootSymbol.get_all_symbols(): if symbol.declaration is None: @@ -4588,6 +4990,7 @@ class CPPDomain(Domain): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(CPPDomain) app.add_config_value("cpp_index_common_prefix", [], 'env') app.add_config_value("cpp_id_attributes", [], 'env') diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index f0b78589e..6d7920411 100644 --- a/sphinx/domains/javascript.py +++ b/sphinx/domains/javascript.py @@ -18,6 +18,14 @@ from sphinx.domains.python import _pseudo_parse_arglist from sphinx.util.nodes import make_refnode from sphinx.util.docfields import Field, GroupedField, TypedField +if False: + # For type annotation + from typing import Any, Iterator, Tuple # NOQA + from docutils import nodes # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + class JSObject(ObjectDescription): """ @@ -28,9 +36,10 @@ class JSObject(ObjectDescription): has_arguments = False #: what is displayed right before the documentation entry - display_prefix = None + display_prefix = None # type: unicode def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> Tuple[unicode, unicode] sig = sig.strip() if '(' in sig and sig[-1:] == ')': prefix, arglist = sig.split('(', 1) @@ -76,6 +85,7 @@ class JSObject(ObjectDescription): return fullname, nameprefix def add_target_and_index(self, name_obj, sig, signode): + # type: (Tuple[unicode, unicode], unicode, addnodes.desc_signature) -> None objectname = self.options.get( 'object', self.env.ref_context.get('js:object')) fullname = name_obj[0] @@ -100,6 +110,7 @@ class JSObject(ObjectDescription): '', None)) def get_index_text(self, objectname, name_obj): + # type: (unicode, Tuple[unicode, unicode]) -> unicode name, obj = name_obj if self.objtype == 'function': if not obj: @@ -139,6 +150,7 @@ class JSConstructor(JSCallable): class JSXRefRole(XRefRole): def process_link(self, env, refnode, has_explicit_title, title, target): + # type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA # basically what sphinx.domains.python.PyXRefRole does refnode['js:object'] = env.ref_context.get('js:object') if not has_explicit_title: @@ -180,20 +192,23 @@ class JavaScriptDomain(Domain): } initial_data = { 'objects': {}, # fullname -> docname, objtype - } + } # type: Dict[unicode, Dict[unicode, Tuple[unicode, unicode]]] def clear_doc(self, docname): + # type: (unicode) -> None for fullname, (fn, _l) in list(self.data['objects'].items()): if fn == docname: del self.data['objects'][fullname] def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None # XXX check duplicates for fullname, (fn, objtype) in otherdata['objects'].items(): if fn in docnames: self.data['objects'][fullname] = (fn, objtype) def find_obj(self, env, obj, name, typ, searchorder=0): + # type: (BuildEnvironment, unicode, unicode, unicode, int) -> Tuple[unicode, Tuple[unicode, unicode]] # NOQA if name[-2:] == '()': name = name[:-2] objects = self.data['objects'] @@ -212,6 +227,7 @@ class JavaScriptDomain(Domain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA objectname = node.get('js:object') searchorder = node.hasattr('refspecific') and 1 or 0 name, obj = self.find_obj(env, objectname, target, typ, searchorder) @@ -222,6 +238,7 @@ class JavaScriptDomain(Domain): def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA objectname = node.get('js:object') name, obj = self.find_obj(env, objectname, target, None, 1) if not obj: @@ -231,12 +248,14 @@ class JavaScriptDomain(Domain): name.replace('$', '_S_'), contnode, name))] def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] for refname, (docname, type) in list(self.data['objects'].items()): yield refname, refname, type, docname, \ refname.replace('$', '_S_'), 1 def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(JavaScriptDomain) return { diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index a7e2bb8f6..2efc6db0b 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -12,18 +12,28 @@ import re from six import iteritems + from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from sphinx import addnodes from sphinx.roles import XRefRole from sphinx.locale import l_, _ from sphinx.domains import Domain, ObjType, Index from sphinx.directives import ObjectDescription +from sphinx.util import logging from sphinx.util.nodes import make_refnode -from sphinx.util.compat import Directive from sphinx.util.docfields import Field, GroupedField, TypedField +if False: + # For type annotation + from typing import Any, Iterable, Iterator, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + # REs for Python signatures py_sig_re = re.compile( @@ -36,6 +46,7 @@ py_sig_re = re.compile( def _pseudo_parse_arglist(signode, arglist): + # type: (addnodes.desc_signature, unicode) -> None """"Parse" a list of arguments separated by commas. Arguments can have "optional" annotations given by enclosing them in @@ -87,7 +98,8 @@ def _pseudo_parse_arglist(signode, arglist): class PyXrefMixin(object): def make_xref(self, rolename, domain, target, innernode=nodes.emphasis, contnode=None): - result = super(PyXrefMixin, self).make_xref(rolename, domain, target, + # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node + result = super(PyXrefMixin, self).make_xref(rolename, domain, target, # type: ignore innernode, contnode) result['refspecific'] = True if target.startswith(('.', '~')): @@ -103,6 +115,7 @@ class PyXrefMixin(object): def make_xrefs(self, rolename, domain, target, innernode=nodes.emphasis, contnode=None): + # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] delims = '(\s*[\[\]\(\),](?:\s*or\s)?\s*|\s+or\s+)' delims_re = re.compile(delims) sub_targets = re.split(delims, target) @@ -114,7 +127,7 @@ class PyXrefMixin(object): if split_contnode: contnode = nodes.Text(sub_target) - if delims_re.match(sub_target): + if delims_re.match(sub_target): # type: ignore results.append(contnode or innernode(sub_target, sub_target)) else: results.append(self.make_xref(rolename, domain, sub_target, @@ -165,18 +178,21 @@ class PyObject(ObjectDescription): ] def get_signature_prefix(self, sig): + # type: (unicode) -> unicode """May return a prefix to put before the object name in the signature. """ return '' def needs_arglist(self): + # type: () -> bool """May return true if an empty argument list is to be generated even if the document contains none. """ return False - def handle_signature(self, sig, signode): + def handle_signature(self, sig, signode): # type: ignore + # type: (unicode, addnodes.desc_signature) -> Tuple[unicode, unicode] """Transform a Python signature into RST nodes. Return (fully qualified name of the thing, classname if any). @@ -185,7 +201,7 @@ class PyObject(ObjectDescription): * it is stripped from the displayed name if present * it is added to the full name (return value) if not present """ - m = py_sig_re.match(sig) + m = py_sig_re.match(sig) # type: ignore if m is None: raise ValueError name_prefix, name, arglist, retann = m.groups() @@ -256,10 +272,12 @@ class PyObject(ObjectDescription): return fullname, name_prefix def get_index_text(self, modname, name): + # type: (unicode, unicode) -> unicode """Return the text for the index entry of the object.""" raise NotImplementedError('must be implemented in subclasses') def add_target_and_index(self, name_cls, sig, signode): + # type: (unicode, unicode, addnodes.desc_signature) -> None modname = self.options.get( 'module', self.env.ref_context.get('py:module')) fullname = (modname and modname + '.' or '') + name_cls[0] @@ -285,10 +303,12 @@ class PyObject(ObjectDescription): fullname, '', None)) def before_content(self): + # type: () -> None # needed for automatic qualification of members (reset in subclasses) self.clsname_set = False def after_content(self): + # type: () -> None if self.clsname_set: self.env.ref_context.pop('py:class', None) @@ -299,9 +319,11 @@ class PyModulelevel(PyObject): """ def needs_arglist(self): + # type: () -> bool return self.objtype == 'function' def get_index_text(self, modname, name_cls): + # type: (unicode, unicode) -> unicode if self.objtype == 'function': if not modname: return _('%s() (built-in function)') % name_cls[0] @@ -320,9 +342,11 @@ class PyClasslike(PyObject): """ def get_signature_prefix(self, sig): + # type: (unicode) -> unicode return self.objtype + ' ' def get_index_text(self, modname, name_cls): + # type: (unicode, unicode) -> unicode if self.objtype == 'class': if not modname: return _('%s (built-in class)') % name_cls[0] @@ -333,6 +357,7 @@ class PyClasslike(PyObject): return '' def before_content(self): + # type: () -> None PyObject.before_content(self) if self.names: self.env.ref_context['py:class'] = self.names[0][0] @@ -345,9 +370,11 @@ class PyClassmember(PyObject): """ def needs_arglist(self): + # type: () -> bool return self.objtype.endswith('method') def get_signature_prefix(self, sig): + # type: (unicode) -> unicode if self.objtype == 'staticmethod': return 'static ' elif self.objtype == 'classmethod': @@ -355,6 +382,7 @@ class PyClassmember(PyObject): return '' def get_index_text(self, modname, name_cls): + # type: (unicode, unicode) -> unicode name, cls = name_cls add_modules = self.env.config.add_module_names if self.objtype == 'method': @@ -411,6 +439,7 @@ class PyClassmember(PyObject): return '' def before_content(self): + # type: () -> None PyObject.before_content(self) lastname = self.names and self.names[-1][1] if lastname and not self.env.ref_context.get('py:class'): @@ -423,11 +452,13 @@ class PyDecoratorMixin(object): Mixin for decorator directives. """ def handle_signature(self, sig, signode): - ret = super(PyDecoratorMixin, self).handle_signature(sig, signode) + # type: (unicode, addnodes.desc_signature) -> Tuple[unicode, unicode] + ret = super(PyDecoratorMixin, self).handle_signature(sig, signode) # type: ignore signode.insert(0, addnodes.desc_addname('@', '@')) return ret def needs_arglist(self): + # type: () -> bool return False @@ -436,6 +467,7 @@ class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel): Directive to mark functions meant to be used as decorators. """ def run(self): + # type: () -> List[nodes.Node] # a decorator function is a function after all self.name = 'py:function' return PyModulelevel.run(self) @@ -446,6 +478,7 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember): Directive to mark methods meant to be used as decorators. """ def run(self): + # type: () -> List[nodes.Node] self.name = 'py:method' return PyClassmember.run(self) @@ -467,6 +500,7 @@ class PyModule(Directive): } def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env modname = self.arguments[0].strip() noindex = 'noindex' in self.options @@ -502,9 +536,10 @@ class PyCurrentModule(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env modname = self.arguments[0].strip() if modname == 'None': @@ -516,6 +551,7 @@ class PyCurrentModule(Directive): class PyXRefRole(XRefRole): def process_link(self, env, refnode, has_explicit_title, title, target): + # type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA refnode['py:module'] = env.ref_context.get('py:module') refnode['py:class'] = env.ref_context.get('py:class') if not has_explicit_title: @@ -546,9 +582,11 @@ class PythonModuleIndex(Index): shortname = l_('modules') def generate(self, docnames=None): - content = {} + # type: (Iterable[unicode]) -> Tuple[List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool] # NOQA + content = {} # type: Dict[unicode, List] # list of prefixes to ignore - ignores = self.domain.env.config['modindex_common_prefix'] + ignores = None # type: List[unicode] + ignores = self.domain.env.config['modindex_common_prefix'] # type: ignore ignores = sorted(ignores, key=len, reverse=True) # list of all modules, sorted by module name modules = sorted(iteritems(self.domain.data['modules']), @@ -601,9 +639,9 @@ class PythonModuleIndex(Index): collapse = len(modules) - num_toplevels < num_toplevels # sort by first letter - content = sorted(iteritems(content)) + sorted_content = sorted(iteritems(content)) - return content, collapse + return sorted_content, collapse class PythonDomain(Domain): @@ -620,7 +658,7 @@ class PythonDomain(Domain): 'staticmethod': ObjType(l_('static method'), 'meth', 'obj'), 'attribute': ObjType(l_('attribute'), 'attr', 'obj'), 'module': ObjType(l_('module'), 'mod', 'obj'), - } + } # type: Dict[unicode, ObjType] directives = { 'function': PyModulelevel, @@ -650,12 +688,13 @@ class PythonDomain(Domain): initial_data = { 'objects': {}, # fullname -> docname, objtype 'modules': {}, # modname -> docname, synopsis, platform, deprecated - } + } # type: Dict[unicode, Dict[unicode, Tuple[Any]]] indices = [ PythonModuleIndex, ] def clear_doc(self, docname): + # type: (unicode) -> None for fullname, (fn, _l) in list(self.data['objects'].items()): if fn == docname: del self.data['objects'][fullname] @@ -664,6 +703,7 @@ class PythonDomain(Domain): del self.data['modules'][modname] def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None # XXX check duplicates? for fullname, (fn, objtype) in otherdata['objects'].items(): if fn in docnames: @@ -673,6 +713,7 @@ class PythonDomain(Domain): self.data['modules'][modname] = data def find_obj(self, env, modname, classname, name, type, searchmode=0): + # type: (BuildEnvironment, unicode, unicode, unicode, unicode, int) -> List[Tuple[unicode, Any]] # NOQA """Find a Python object for "name", perhaps using the given module and/or classname. Returns a list of (name, object entry) tuples. """ @@ -684,7 +725,7 @@ class PythonDomain(Domain): return [] objects = self.data['objects'] - matches = [] + matches = [] # type: List[Tuple[unicode, Any]] newname = None if searchmode == 1: @@ -737,6 +778,7 @@ class PythonDomain(Domain): def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA modname = node.get('py:module') clsname = node.get('py:class') searchmode = node.hasattr('refspecific') and 1 or 0 @@ -745,10 +787,9 @@ class PythonDomain(Domain): if not matches: return None elif len(matches) > 1: - env.warn_node( - 'more than one target found for cross-reference ' - '%r: %s' % (target, ', '.join(match[0] for match in matches)), - node) + logger.warning('more than one target found for cross-reference %r: %s', + target, ', '.join(match[0] for match in matches), + location=node) name, obj = matches[0] if obj[1] == 'module': @@ -760,9 +801,10 @@ class PythonDomain(Domain): def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA modname = node.get('py:module') clsname = node.get('py:class') - results = [] + results = [] # type: List[Tuple[unicode, nodes.Node]] # always search in "refspecific" mode with the :any: role matches = self.find_obj(env, modname, clsname, target, None, 1) @@ -778,6 +820,7 @@ class PythonDomain(Domain): return results def _make_module_refnode(self, builder, fromdocname, name, contnode): + # type: (Builder, unicode, unicode, nodes.Node) -> nodes.Node # get additional info for modules docname, synopsis, platform, deprecated = self.data['modules'][name] title = name @@ -791,6 +834,7 @@ class PythonDomain(Domain): 'module-' + name, contnode, title) def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] for modname, info in iteritems(self.data['modules']): yield (modname, modname, 'module', info[0], 'module-' + modname, 0) for refname, (docname, type) in iteritems(self.data['objects']): @@ -799,6 +843,7 @@ class PythonDomain(Domain): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(PythonDomain) return { diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py index d5c4427de..450b0faa2 100644 --- a/sphinx/domains/rst.py +++ b/sphinx/domains/rst.py @@ -20,6 +20,14 @@ from sphinx.directives import ObjectDescription from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode +if False: + # For type annotation + from typing import Any, Iterator, Tuple # NOQA + from docutils import nodes # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$') @@ -30,6 +38,7 @@ class ReSTMarkup(ObjectDescription): """ def add_target_and_index(self, name, sig, signode): + # type: (unicode, unicode, addnodes.desc_signature) -> None targetname = self.objtype + '-' + name if targetname not in self.state.document.ids: signode['names'].append(targetname) @@ -51,6 +60,7 @@ class ReSTMarkup(ObjectDescription): targetname, '', None)) def get_index_text(self, objectname, name): + # type: (unicode, unicode) -> unicode if self.objtype == 'directive': return _('%s (directive)') % name elif self.objtype == 'role': @@ -59,6 +69,7 @@ class ReSTMarkup(ObjectDescription): def parse_directive(d): + # type: (unicode) -> Tuple[unicode, unicode] """Parse a directive signature. Returns (directive, arguments) string tuple. If no arguments are given, @@ -68,7 +79,7 @@ def parse_directive(d): if not dir.startswith('.'): # Assume it is a directive without syntax return (dir, '') - m = dir_sig_re.match(dir) + m = dir_sig_re.match(dir) # type: ignore if not m: return (dir, '') parsed_dir, parsed_args = m.groups() @@ -80,6 +91,7 @@ class ReSTDirective(ReSTMarkup): Description of a reST directive. """ def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode name, args = parse_directive(sig) desc_name = '.. %s::' % name signode += addnodes.desc_name(desc_name, desc_name) @@ -93,6 +105,7 @@ class ReSTRole(ReSTMarkup): Description of a reST role. """ def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig) return sig @@ -116,14 +129,16 @@ class ReSTDomain(Domain): } initial_data = { 'objects': {}, # fullname -> docname, objtype - } + } # type: Dict[unicode, Dict[unicode, Tuple[unicode, ObjType]]] def clear_doc(self, docname): + # type: (unicode) -> None for (typ, name), doc in list(self.data['objects'].items()): if doc == docname: del self.data['objects'][typ, name] def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None # XXX check duplicates for (typ, name), doc in otherdata['objects'].items(): if doc in docnames: @@ -131,6 +146,7 @@ class ReSTDomain(Domain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA objects = self.data['objects'] objtypes = self.objtypes_for_role(typ) for objtype in objtypes: @@ -142,6 +158,7 @@ class ReSTDomain(Domain): def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] # NOQA objects = self.data['objects'] results = [] for objtype in self.object_types: @@ -154,11 +171,13 @@ class ReSTDomain(Domain): return results def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] for (typ, name), docname in iteritems(self.data['objects']): yield name, name, typ, docname, typ + '-' + name, 1 def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(ReSTDomain) return { diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 55d0ec1ef..9869f71aa 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -12,9 +12,10 @@ import re import unicodedata -from six import iteritems +from six import PY3, iteritems + from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList from sphinx import addnodes @@ -22,9 +23,25 @@ from sphinx.roles import XRefRole from sphinx.locale import l_, _ from sphinx.domains import Domain, ObjType from sphinx.directives import ObjectDescription -from sphinx.util import ws_re +from sphinx.util import ws_re, logging from sphinx.util.nodes import clean_astext, make_refnode -from sphinx.util.compat import Directive + +if False: + # For type annotation + from typing import Any, Callable, Dict, Iterator, List, Tuple, Type, Union # NOQA + from docutils.parsers.rst.states import Inliner # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + from sphinx.util.typing import Role # NOQA + + if PY3: + unicode = str + + RoleFunction = Callable[[unicode, unicode, unicode, int, Inliner, Dict, List[unicode]], + Tuple[List[nodes.Node], List[nodes.Node]]] + +logger = logging.getLogger(__name__) # RE for option descriptions @@ -38,9 +55,10 @@ class GenericObject(ObjectDescription): A generic x-ref directive registered with Sphinx.add_object_type(). """ indextemplate = '' - parse_node = None + parse_node = None # type: Callable[[GenericObject, BuildEnvironment, unicode, addnodes.desc_signature], unicode] # NOQA def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode if self.parse_node: name = self.parse_node(self.env, sig, signode) else: @@ -51,6 +69,7 @@ class GenericObject(ObjectDescription): return name def add_target_and_index(self, name, sig, signode): + # type: (unicode, unicode, addnodes.desc_signature) -> None targetname = '%s-%s' % (self.objtype, name) signode['ids'].append(targetname) self.state.document.note_explicit_target(signode) @@ -78,6 +97,7 @@ class EnvVarXRefRole(XRefRole): """ def result_nodes(self, document, env, node, is_ref): + # type: (nodes.Node, BuildEnvironment, nodes.Node, bool) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA if not is_ref: return [node], [] varname = node['reftarget'] @@ -102,9 +122,10 @@ class Target(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env # normalize whitespace in fullname like XRefRole does fullname = ws_re.sub(' ', self.arguments[0].strip()) @@ -136,19 +157,18 @@ class Cmdoption(ObjectDescription): """ def handle_signature(self, sig, signode): + # type: (unicode, addnodes.desc_signature) -> unicode """Transform an option description into RST nodes.""" count = 0 firstname = '' for potential_option in sig.split(', '): potential_option = potential_option.strip() - m = option_desc_re.match(potential_option) + m = option_desc_re.match(potential_option) # type: ignore if not m: - self.env.warn( - self.env.docname, - 'Malformed option description %r, should ' - 'look like "opt", "-opt args", "--opt args", ' - '"/opt args" or "+opt args"' % potential_option, - self.lineno) + logger.warning('Malformed option description %r, should ' + 'look like "opt", "-opt args", "--opt args", ' + '"/opt args" or "+opt args"', potential_option, + location=(self.env.docname, self.lineno)) continue optname, args = m.groups() if count: @@ -166,6 +186,7 @@ class Cmdoption(ObjectDescription): return firstname def add_target_and_index(self, firstname, sig, signode): + # type: (unicode, unicode, addnodes.desc_signature) -> None currprogram = self.env.ref_context.get('std:program') for optname in signode.get('allnames', []): targetname = optname.replace('/', '-') @@ -197,9 +218,10 @@ class Program(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env program = ws_re.sub('-', self.arguments[0].strip()) if program == 'None': @@ -211,17 +233,20 @@ class Program(Directive): class OptionXRefRole(XRefRole): def process_link(self, env, refnode, has_explicit_title, title, target): + # type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA refnode['std:program'] = env.ref_context.get('std:program') return title, target def split_term_classifiers(line): + # type: (unicode) -> List[Union[unicode, None]] # split line into a term and classifiers. if no classifier, None is used.. parts = re.split(' +: +', line) + [None] return parts def make_glossary_term(env, textnodes, index_key, source, lineno, new_id=None): + # type: (BuildEnvironment, List[nodes.Node], unicode, unicode, int, unicode) -> nodes.term # get a text-only representation of the term and register it # as a cross-reference target term = nodes.term('', '', *textnodes) @@ -265,6 +290,7 @@ class Glossary(Directive): } def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env node = addnodes.glossary() node.document = self.state.document @@ -275,7 +301,7 @@ class Glossary(Directive): # be* a definition list. # first, collect single entries - entries = [] + entries = [] # type: List[Tuple[List[Tuple[unicode, unicode, int]], ViewList]] in_definition = True was_empty = True messages = [] @@ -329,7 +355,7 @@ class Glossary(Directive): for terms, definition in entries: termtexts = [] termnodes = [] - system_messages = [] + system_messages = [] # type: List[unicode] for line, source, lineno in terms: parts = split_term_classifiers(line) # parse the term with inline markup @@ -365,9 +391,10 @@ class Glossary(Directive): def token_xrefs(text): + # type: (unicode) -> List[nodes.Node] retnodes = [] pos = 0 - for m in token_re.finditer(text): + for m in token_re.finditer(text): # type: ignore if m.start() > pos: txt = text[pos:m.start()] retnodes.append(nodes.Text(txt, txt)) @@ -390,13 +417,14 @@ class ProductionList(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] env = self.state.document.settings.env objects = env.domaindata['std']['objects'] node = addnodes.productionlist() - messages = [] + messages = [] # type: List[nodes.Node] i = 0 for rule in self.arguments[0].split('\n'): @@ -437,7 +465,7 @@ class StandardDomain(Domain): searchprio=-1), 'envvar': ObjType(l_('environment variable'), 'envvar'), 'cmdoption': ObjType(l_('program option'), 'option'), - } + } # type: Dict[unicode, ObjType] directives = { 'program': Program, @@ -446,7 +474,7 @@ class StandardDomain(Domain): 'envvar': EnvVar, 'glossary': Glossary, 'productionlist': ProductionList, - } + } # type: Dict[unicode, Type[Directive]] roles = { 'option': OptionXRefRole(warn_dangling=True), 'envvar': EnvVarXRefRole(), @@ -463,7 +491,7 @@ class StandardDomain(Domain): warn_dangling=True), # links to labels, without a different title 'keyword': XRefRole(warn_dangling=True), - } + } # type: Dict[unicode, Union[RoleFunction, XRefRole]] initial_data = { 'progoptions': {}, # (program, name) -> docname, labelid @@ -495,9 +523,10 @@ class StandardDomain(Domain): nodes.figure: ('figure', None), nodes.table: ('table', None), nodes.container: ('code-block', None), - } + } # type: Dict[nodes.Node, Tuple[unicode, Callable]] def clear_doc(self, docname): + # type: (unicode) -> None for key, (fn, _l) in list(self.data['progoptions'].items()): if fn == docname: del self.data['progoptions'][key] @@ -515,6 +544,7 @@ class StandardDomain(Domain): del self.data['anonlabels'][key] def merge_domaindata(self, docnames, otherdata): + # type: (List[unicode], Dict) -> None # XXX duplicates? for key, data in otherdata['progoptions'].items(): if data[0] in docnames: @@ -533,19 +563,22 @@ class StandardDomain(Domain): self.data['anonlabels'][key] = data def process_doc(self, env, docname, document): + # type: (BuildEnvironment, unicode, nodes.Node) -> None self.note_citations(env, docname, document) self.note_labels(env, docname, document) def note_citations(self, env, docname, document): + # type: (BuildEnvironment, unicode, nodes.Node) -> None for node in document.traverse(nodes.citation): label = node[0].astext() if label in self.data['citations']: path = env.doc2path(self.data['citations'][label][0]) - env.warn_node('duplicate citation %s, other instance in %s' % - (label, path), node) + logger.warning('duplicate citation %s, other instance in %s', label, path, + location=node) self.data['citations'][label] = (docname, node['ids'][0]) def note_labels(self, env, docname, document): + # type: (BuildEnvironment, unicode, nodes.Node) -> None labels, anonlabels = self.data['labels'], self.data['anonlabels'] for name, explicit in iteritems(document.nametypes): if not explicit: @@ -563,8 +596,9 @@ class StandardDomain(Domain): # link and object descriptions continue if name in labels: - env.warn_node('duplicate label %s, ' % name + 'other instance ' - 'in ' + env.doc2path(labels[name][0]), node) + logger.warning('duplicate label %s, ' % name + 'other instance ' + 'in ' + env.doc2path(labels[name][0]), + location=node) anonlabels[name] = docname, labelid if node.tagname == 'section': sectname = clean_astext(node[0]) # node[0] == title node @@ -585,6 +619,7 @@ class StandardDomain(Domain): def build_reference_node(self, fromdocname, builder, docname, labelid, sectname, rolename, **options): + # type: (unicode, Builder, unicode, unicode, unicode, unicode, Any) -> nodes.Node nodeclass = options.pop('nodeclass', nodes.reference) newnode = nodeclass('', '', internal=True, **options) innernode = nodes.inline(sectname, sectname) @@ -608,6 +643,7 @@ class StandardDomain(Domain): return newnode def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA if typ == 'ref': resolver = self._resolve_ref_xref elif typ == 'numref': @@ -624,6 +660,7 @@ class StandardDomain(Domain): return resolver(env, fromdocname, builder, typ, target, node, contnode) def _resolve_ref_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA if node['refexplicit']: # reference to anonymous label; the reference uses # the supplied link caption @@ -641,6 +678,7 @@ class StandardDomain(Domain): docname, labelid, sectname, 'ref') def _resolve_numref_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA if target in self.data['labels']: docname, labelid, figname = self.data['labels'].get(target, ('', '', '')) else: @@ -651,7 +689,7 @@ class StandardDomain(Domain): return None if env.config.numfig is False: - env.warn_node('numfig is disabled. :numref: is ignored.', node) + logger.warning('numfig is disabled. :numref: is ignored.', location=node) return contnode target_node = env.get_doctree(docname).ids.get(labelid) @@ -664,7 +702,8 @@ class StandardDomain(Domain): if fignumber is None: return contnode except ValueError: - env.warn_node("no number is assigned for %s: %s" % (figtype, labelid), node) + logger.warning("no number is assigned for %s: %s", figtype, labelid, + location=node) return contnode try: @@ -674,7 +713,7 @@ class StandardDomain(Domain): title = env.config.numfig_format.get(figtype, '') if figname is None and '{name}' in title: - env.warn_node('the link has no caption: %s' % title, node) + logger.warning('the link has no caption: %s', title, location=node) return contnode else: fignum = '.'.join(map(str, fignumber)) @@ -688,10 +727,10 @@ class StandardDomain(Domain): # old style format (cf. "Fig.%s") newtitle = title % fignum except KeyError as exc: - env.warn_node('invalid numfig_format: %s (%r)' % (title, exc), node) + logger.warning('invalid numfig_format: %s (%r)', title, exc, location=node) return contnode except TypeError: - env.warn_node('invalid numfig_format: %s' % title, node) + logger.warning('invalid numfig_format: %s', title, location=node) return contnode return self.build_reference_node(fromdocname, builder, @@ -700,6 +739,7 @@ class StandardDomain(Domain): title=title) def _resolve_keyword_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA # keywords are oddballs: they are referenced by named labels docname, labelid, _ = self.data['labels'].get(target, ('', '', '')) if not docname: @@ -708,13 +748,14 @@ class StandardDomain(Domain): labelid, contnode) def _resolve_option_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA progname = node.get('std:program') target = target.strip() docname, labelid = self.data['progoptions'].get((progname, target), ('', '')) if not docname: commands = [] - while ws_re.search(target): - subcommand, target = ws_re.split(target, 1) + while ws_re.search(target): # type: ignore + subcommand, target = ws_re.split(target, 1) # type: ignore commands.append(subcommand) progname = "-".join(commands) @@ -729,6 +770,7 @@ class StandardDomain(Domain): labelid, contnode) def _resolve_citation_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA from sphinx.environment import NoUri docname, labelid = self.data['citations'].get(target, ('', '')) @@ -751,6 +793,7 @@ class StandardDomain(Domain): raise def _resolve_obj_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA objtypes = self.objtypes_for_role(typ) or [] for objtype in objtypes: if (objtype, target) in self.data['objects']: @@ -764,7 +807,8 @@ class StandardDomain(Domain): labelid, contnode) def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): - results = [] + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA + results = [] # type: List[Tuple[unicode, nodes.Node]] ltarget = target.lower() # :ref: lowercases its target automatically for role in ('ref', 'option'): # do not try "keyword" res = self.resolve_xref(env, fromdocname, builder, role, @@ -785,6 +829,7 @@ class StandardDomain(Domain): return results def get_objects(self): + # type: () -> Iterator[Tuple[unicode, unicode, unicode, unicode, unicode, int]] # handle the special 'doc' reference here for doc in self.env.all_docs: yield (doc, clean_astext(self.env.titles[doc]), 'doc', doc, '', -1) @@ -802,13 +847,16 @@ class StandardDomain(Domain): yield (name, name, 'label', info[0], info[1], -1) def get_type_name(self, type, primary=False): + # type: (ObjType, bool) -> unicode # never prepend "Default" return type.lname def is_enumerable_node(self, node): + # type: (nodes.Node) -> bool return node.__class__ in self.enumerable_nodes def get_numfig_title(self, node): + # type: (nodes.Node) -> unicode """Get the title of enumerable nodes to refer them using its title""" if self.is_enumerable_node(node): _, title_getter = self.enumerable_nodes.get(node.__class__, (None, None)) @@ -822,6 +870,7 @@ class StandardDomain(Domain): return None def get_figtype(self, node): + # type: (nodes.Node) -> unicode """Get figure type of nodes.""" def has_child(node, cls): return any(isinstance(child, cls) for child in node) @@ -838,6 +887,7 @@ class StandardDomain(Domain): return figtype def get_fignumber(self, env, builder, figtype, docname, target_node): + # type: (BuildEnvironment, Builder, unicode, unicode, nodes.Node) -> Tuple[int, ...] if figtype == 'section': if builder.name == 'latex': return tuple() @@ -861,6 +911,7 @@ class StandardDomain(Domain): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(StandardDomain) return { diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index 0f978e42e..1fb9ec19e 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -18,9 +18,11 @@ import codecs import fnmatch from os import path from glob import glob +from collections import defaultdict from six import iteritems, itervalues, class_types, next from six.moves import cPickle as pickle + from docutils import nodes from docutils.io import NullOutput from docutils.core import Publisher @@ -31,14 +33,14 @@ from docutils.frontend import OptionParser from sphinx import addnodes from sphinx.io import SphinxStandaloneReader, SphinxDummyWriter, SphinxFileInput -from sphinx.util import get_matching_docs, docname_join, FilenameUniqDict +from sphinx.util import get_matching_docs, docname_join, FilenameUniqDict, logging from sphinx.util.nodes import clean_astext, WarningStream, is_translatable, \ process_only_nodes from sphinx.util.osutil import SEP, getcwd, fs_encoding, ensuredir from sphinx.util.images import guess_mimetype from sphinx.util.i18n import find_catalog_files, get_image_filename_for_language, \ search_image_for_language -from sphinx.util.console import bold, purple +from sphinx.util.console import bold, purple # type: ignore from sphinx.util.docutils import sphinx_domains from sphinx.util.matching import compile_matchers from sphinx.util.parallel import ParallelTasks, parallel_available, make_chunks @@ -49,6 +51,16 @@ from sphinx.transforms import SphinxContentsFilter from sphinx.environment.managers.indexentries import IndexEntries from sphinx.environment.managers.toctree import Toctree +if False: + # For type annotation + from typing import Any, Callable, Iterator, Pattern, Tuple, Type, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.config import Config # NOQA + from sphinx.domains import Domain # NOQA + from sphinx.environment.managers import EnvironmentManager # NOQA + +logger = logging.getLogger(__name__) default_settings = { 'embed_stylesheet': False, @@ -66,7 +78,7 @@ default_settings = { # or changed to properly invalidate pickle files. # # NOTE: increase base version by 2 to have distinct numbers for Py2 and 3 -ENV_VERSION = 50 + (sys.version_info[0] - 2) +ENV_VERSION = 51 + (sys.version_info[0] - 2) dummy_reporter = Reporter('', 4, 4) @@ -75,7 +87,7 @@ versioning_conditions = { 'none': False, 'text': is_translatable, 'commentable': is_commentable, -} +} # type: Dict[unicode, Union[bool, Callable]] class NoUri(Exception): @@ -90,10 +102,13 @@ class BuildEnvironment(object): transformations to resolve links to them. """ + domains = None # type: Dict[unicode, Domain] + # --------- ENVIRONMENT PERSISTENCE ---------------------------------------- @staticmethod def frompickle(srcdir, config, filename): + # type: (unicode, Config, unicode) -> BuildEnvironment with open(filename, 'rb') as picklefile: env = pickle.load(picklefile) if env.version != ENV_VERSION: @@ -104,6 +119,7 @@ class BuildEnvironment(object): return env def topickle(self, filename): + # type: (unicode) -> None # remove unpicklable attributes warnfunc = self._warnfunc self.set_warnfunc(None) @@ -130,16 +146,17 @@ class BuildEnvironment(object): # --------- ENVIRONMENT INITIALIZATION ------------------------------------- def __init__(self, srcdir, doctreedir, config): + # type: (unicode, unicode, Config) -> None self.doctreedir = doctreedir - self.srcdir = srcdir - self.config = config + self.srcdir = srcdir # type: unicode + self.config = config # type: Config # the method of doctree versioning; see set_versioning_method - self.versioning_condition = None - self.versioning_compare = None + self.versioning_condition = None # type: Union[bool, Callable] + self.versioning_compare = None # type: bool # the application object; only set while update() runs - self.app = None + self.app = None # type: Sphinx # all the registered domains, set by the application self.domains = {} @@ -149,7 +166,7 @@ class BuildEnvironment(object): self.settings['env'] = self # the function to write warning messages with - self._warnfunc = None + self._warnfunc = None # type: Callable # this is to invalidate old pickles self.version = ENV_VERSION @@ -157,43 +174,63 @@ class BuildEnvironment(object): # All "docnames" here are /-separated and relative and exclude # the source suffix. - self.found_docs = set() # contains all existing docnames - self.all_docs = {} # docname -> mtime at the time of reading + self.found_docs = set() # type: Set[unicode] + # contains all existing docnames + self.all_docs = {} # type: Dict[unicode, float] + # docname -> mtime at the time of reading # contains all read docnames - self.dependencies = {} # docname -> set of dependent file + self.dependencies = defaultdict(set) # type: Dict[unicode, Set[unicode]] + # docname -> set of dependent file # names, relative to documentation root - self.included = set() # docnames included from other documents - self.reread_always = set() # docnames to re-read unconditionally on + self.included = set() # type: Set[unicode] + # docnames included from other documents + self.reread_always = set() # type: Set[unicode] + # docnames to re-read unconditionally on # next build # File metadata - self.metadata = {} # docname -> dict of metadata items + self.metadata = {} # type: Dict[unicode, Dict[unicode, Any]] + # docname -> dict of metadata items # TOC inventory - self.titles = {} # docname -> title node - self.longtitles = {} # docname -> title node; only different if + self.titles = {} # type: Dict[unicode, nodes.Node] + # docname -> title node + self.longtitles = {} # type: Dict[unicode, nodes.Node] + # docname -> title node; only different if # set differently with title directive - self.tocs = {} # docname -> table of contents nodetree - self.toc_num_entries = {} # docname -> number of real entries + self.tocs = {} # type: Dict[unicode, nodes.Node] + # docname -> table of contents nodetree + self.toc_num_entries = {} # type: Dict[unicode, int] + # docname -> number of real entries + # used to determine when to show the TOC # in a sidebar (don't show if it's only one item) - self.toc_secnumbers = {} # docname -> dict of sectionid -> number - self.toc_fignumbers = {} # docname -> dict of figtype -> + self.toc_secnumbers = {} # type: Dict[unicode, Dict[unicode, Tuple[int, ...]]] + # docname -> dict of sectionid -> number + self.toc_fignumbers = {} # type: Dict[unicode, Dict[unicode, Dict[unicode, Tuple[int, ...]]]] # NOQA + # docname -> dict of figtype -> # dict of figureid -> number - self.toctree_includes = {} # docname -> list of toctree includefiles - self.files_to_rebuild = {} # docname -> set of files + self.toctree_includes = {} # type: Dict[unicode, List[unicode]] + # docname -> list of toctree includefiles + self.files_to_rebuild = {} # type: Dict[unicode, Set[unicode]] + # docname -> set of files # (containing its TOCs) to rebuild too - self.glob_toctrees = set() # docnames that have :glob: toctrees - self.numbered_toctrees = set() # docnames that have :numbered: toctrees + self.glob_toctrees = set() # type: Set[unicode] + # docnames that have :glob: toctrees + self.numbered_toctrees = set() # type: Set[unicode] + # docnames that have :numbered: toctrees # domain-specific inventories, here to be pickled - self.domaindata = {} # domainname -> domain-specific dict + self.domaindata = {} # type: Dict[unicode, Dict] + # domainname -> domain-specific dict # Other inventories - self.indexentries = {} # docname -> list of - # (type, string, target, aliasname) - self.versionchanges = {} # version -> list of (type, docname, + self.indexentries = {} # type: Dict[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]] # NOQA + # docname -> list of + # (type, unicode, target, aliasname) + self.versionchanges = {} # type: Dict[unicode, List[Tuple[unicode, unicode, int, unicode, unicode, unicode]]] # NOQA + # version -> list of (type, docname, # lineno, module, descname, content) # these map absolute path -> (docnames, unique filename) @@ -201,27 +238,31 @@ class BuildEnvironment(object): self.dlfiles = FilenameUniqDict() # temporary data storage while reading a document - self.temp_data = {} + self.temp_data = {} # type: Dict[unicode, Any] # context for cross-references (e.g. current module or class) # this is similar to temp_data, but will for example be copied to # attributes of "any" cross references - self.ref_context = {} + self.ref_context = {} # type: Dict[unicode, Any] - self.managers = {} + self.managers = {} # type: Dict[unicode, EnvironmentManager] self.init_managers() def init_managers(self): + # type: () -> None managers = {} - for manager_class in [IndexEntries, Toctree]: + manager_class = None # type: Type[EnvironmentManager] + for manager_class in [IndexEntries, Toctree]: # type: ignore managers[manager_class.name] = manager_class(self) self.attach_managers(managers) def attach_managers(self, managers): + # type: (Dict[unicode, EnvironmentManager]) -> None for name, manager in iteritems(managers): self.managers[name] = manager manager.attach(self) def detach_managers(self): + # type: () -> Dict[unicode, EnvironmentManager] managers = self.managers self.managers = {} for _, manager in iteritems(managers): @@ -229,10 +270,12 @@ class BuildEnvironment(object): return managers def set_warnfunc(self, func): + # type: (Callable) -> None self._warnfunc = func self.settings['warning_stream'] = WarningStream(func) def set_versioning_method(self, method, compare): + # type: (unicode, bool) -> None """This sets the doctree versioning method for this environment. Versioning methods are a builder property; only builders with the same @@ -251,6 +294,7 @@ class BuildEnvironment(object): self.versioning_compare = compare def warn(self, docname, msg, lineno=None, **kwargs): + # type: (unicode, unicode, int, Any) -> None """Emit a warning. This differs from using ``app.warn()`` in that the warning may not @@ -261,10 +305,12 @@ class BuildEnvironment(object): self._warnfunc(msg, (docname, lineno), **kwargs) def warn_node(self, msg, node, **kwargs): + # type: (unicode, nodes.Node, Any) -> None """Like :meth:`warn`, but with source information taken from *node*.""" self._warnfunc(msg, '%s:%s' % get_source_line(node), **kwargs) def clear_doc(self, docname): + # type: (unicode) -> None """Remove all traces of a source file in the inventory.""" if docname in self.all_docs: self.all_docs.pop(docname, None) @@ -287,12 +333,13 @@ class BuildEnvironment(object): domain.clear_doc(docname) def merge_info_from(self, docnames, other, app): + # type: (List[unicode], BuildEnvironment, Sphinx) -> None """Merge global information gathered about *docnames* while reading them from the *other* environment. This possibly comes from a parallel build process. """ - docnames = set(docnames) + docnames = set(docnames) # type: ignore for docname in docnames: self.all_docs[docname] = other.all_docs[docname] if docname in other.reread_always: @@ -317,6 +364,7 @@ class BuildEnvironment(object): app.emit('env-merge-info', self, docnames, other) def path2doc(self, filename): + # type: (unicode) -> unicode """Return the docname for the filename if the file is document. *filename* should be absolute or relative to the source directory. @@ -324,13 +372,14 @@ class BuildEnvironment(object): if filename.startswith(self.srcdir): filename = filename[len(self.srcdir) + 1:] for suffix in self.config.source_suffix: - if fnmatch.fnmatch(filename, '*' + suffix): - return filename[:-len(suffix)] + if fnmatch.fnmatch(filename, '*' + suffix): # type: ignore + return filename[:-len(suffix)] # type: ignore else: # the file does not have docname return None def doc2path(self, docname, base=True, suffix=None): + # type: (unicode, Union[bool, unicode], unicode) -> unicode """Return the filename for the document name. If *base* is True, return absolute path under self.srcdir. @@ -340,22 +389,24 @@ class BuildEnvironment(object): """ docname = docname.replace(SEP, path.sep) if suffix is None: - for candidate_suffix in self.config.source_suffix: + candidate_suffix = None # type: unicode + for candidate_suffix in self.config.source_suffix: # type: ignore if path.isfile(path.join(self.srcdir, docname) + candidate_suffix): suffix = candidate_suffix break else: # document does not exist - suffix = self.config.source_suffix[0] + suffix = self.config.source_suffix[0] # type: ignore if base is True: return path.join(self.srcdir, docname) + suffix elif base is None: return docname + suffix else: - return path.join(base, docname) + suffix + return path.join(base, docname) + suffix # type: ignore def relfn2path(self, filename, docname=None): + # type: (unicode, unicode) -> Tuple[unicode, unicode] """Return paths to a file referenced from a document, relative to documentation root and absolute. @@ -379,7 +430,8 @@ class BuildEnvironment(object): enc_rel_fn = rel_fn.encode(sys.getfilesystemencoding()) return rel_fn, path.abspath(path.join(self.srcdir, enc_rel_fn)) - def find_files(self, config, buildername=None): + def find_files(self, config, buildername): + # type: (Config, unicode) -> None """Find all source files in the source dir and put them in self.found_docs. """ @@ -390,12 +442,12 @@ class BuildEnvironment(object): ['**/_sources', '.#*', '**/.#*', '*.lproj/**'] ) self.found_docs = set() - for docname in get_matching_docs(self.srcdir, config.source_suffix, + for docname in get_matching_docs(self.srcdir, config.source_suffix, # type: ignore exclude_matchers=matchers): if os.access(self.doc2path(docname), os.R_OK): self.found_docs.add(docname) else: - self.warn(docname, "document not readable. Ignored.") + logger.warning("document not readable. Ignored.", location=docname) # Current implementation is applying translated messages in the reading # phase.Therefore, in order to apply the updated message catalog, it is @@ -413,15 +465,16 @@ class BuildEnvironment(object): self.config.language, self.config.gettext_compact) for filename in catalog_files: - self.dependencies.setdefault(docname, set()).add(filename) + self.dependencies[docname].add(filename) def get_outdated_files(self, config_changed): + # type: (bool) -> Tuple[Set[unicode], Set[unicode], Set[unicode]] """Return (added, changed, removed) sets.""" # clear all files no longer present removed = set(self.all_docs) - self.found_docs - added = set() - changed = set() + added = set() # type: Set[unicode] + changed = set() # type: Set[unicode] if config_changed: # config values affect e.g. substitutions @@ -447,7 +500,7 @@ class BuildEnvironment(object): changed.add(docname) continue # finally, check the mtime of dependencies - for dep in self.dependencies.get(docname, ()): + for dep in self.dependencies[docname]: try: # this will do the right thing when dep is absolute too deppath = path.join(self.srcdir, dep) @@ -466,6 +519,7 @@ class BuildEnvironment(object): return added, changed, removed def update(self, config, srcdir, doctreedir, app): + # type: (Config, unicode, unicode, Sphinx) -> List[unicode] """(Re-)read all files new or changed since last update. Store all environment docnames in the canonical format (ie using SEP as @@ -501,7 +555,7 @@ class BuildEnvironment(object): # this cache also needs to be updated every time self._nitpick_ignore = set(self.config.nitpick_ignore) - app.info(bold('updating environment: '), nonl=True) + logger.info(bold('updating environment: '), nonl=True) added, changed, removed = self.get_outdated_files(config_changed) @@ -517,7 +571,7 @@ class BuildEnvironment(object): msg += '%s added, %s changed, %s removed' % (len(added), len(changed), len(removed)) - app.info(msg) + logger.info(msg) self.app = app @@ -540,14 +594,14 @@ class BuildEnvironment(object): if ext_ok: continue if ext_ok is None: - app.warn('the %s extension does not declare if it ' - 'is safe for parallel reading, assuming it ' - 'isn\'t - please ask the extension author to ' - 'check and make it explicit' % extname) - app.warn('doing serial read') + logger.warning('the %s extension does not declare if it ' + 'is safe for parallel reading, assuming it ' + 'isn\'t - please ask the extension author to ' + 'check and make it explicit', extname) + logger.warning('doing serial read') else: - app.warn('the %s extension is not safe for parallel ' - 'reading, doing serial read' % extname) + logger.warning('the %s extension is not safe for parallel ' + 'reading, doing serial read', extname) par_ok = False break if par_ok: @@ -568,6 +622,7 @@ class BuildEnvironment(object): return sorted(docnames) def _read_serial(self, docnames, app): + # type: (List[unicode], Sphinx) -> None for docname in app.status_iterator(docnames, 'reading sources... ', purple, len(docnames)): # remove all inventory entries for that file @@ -576,14 +631,16 @@ class BuildEnvironment(object): self.read_doc(docname, app) def _read_parallel(self, docnames, app, nproc): + # type: (List[unicode], Sphinx, int) -> None # clear all outdated docs at once for docname in docnames: app.emit('env-purge-doc', self, docname) self.clear_doc(docname) def read_process(docs): + # type: (List[unicode]) -> BuildEnvironment self.app = app - self.warnings = [] + self.warnings = [] # type: List[Tuple] self.set_warnfunc(lambda *args, **kwargs: self.warnings.append((args, kwargs))) for docname in docs: self.read_doc(docname, app) @@ -596,27 +653,29 @@ class BuildEnvironment(object): return self def merge(docs, otherenv): + # type: (List[unicode], BuildEnvironment) -> None warnings.extend(otherenv.warnings) self.merge_info_from(docs, otherenv, app) tasks = ParallelTasks(nproc) chunks = make_chunks(docnames, nproc) - warnings = [] + warnings = [] # type: List[Tuple] for chunk in app.status_iterator( chunks, 'reading sources... ', purple, len(chunks)): tasks.add_task(read_process, chunk, merge) # make sure all threads have finished - app.info(bold('waiting for workers...')) + logger.info(bold('waiting for workers...')) tasks.join() for warning, kwargs in warnings: self._warnfunc(*warning, **kwargs) def check_dependents(self, already): - to_rewrite = (self.toctree.assign_section_numbers() + - self.toctree.assign_figure_numbers()) + # type: (Set[unicode]) -> Iterator[unicode] + to_rewrite = (self.toctree.assign_section_numbers() + # type: ignore + self.toctree.assign_figure_numbers()) # type: ignore for docname in set(to_rewrite): if docname not in already: yield docname @@ -624,20 +683,22 @@ class BuildEnvironment(object): # --------- SINGLE FILE READING -------------------------------------------- def warn_and_replace(self, error): + # type: (Any) -> Tuple """Custom decoding error handler that warns and replaces.""" linestart = error.object.rfind(b'\n', 0, error.start) lineend = error.object.find(b'\n', error.start) if lineend == -1: lineend = len(error.object) lineno = error.object.count(b'\n', 0, error.start) + 1 - self.warn(self.docname, 'undecodable source characters, ' - 'replacing with "?": %r' % - (error.object[linestart+1:error.start] + b'>>>' + - error.object[error.start:error.end] + b'<<<' + - error.object[error.end:lineend]), lineno) + logger.warning('undecodable source characters, replacing with "?": %r', + (error.object[linestart+1:error.start] + b'>>>' + + error.object[error.start:error.end] + b'<<<' + + error.object[error.end:lineend]), + location=(self.docname, lineno)) return (u'?', error.end) def read_doc(self, docname, app=None): + # type: (unicode, Sphinx) -> None """Parse a file and add/update inventory entries for the doctree.""" self.temp_data['docname'] = docname @@ -663,10 +724,10 @@ class BuildEnvironment(object): if role_fn: roles._roles[''] = role_fn else: - self.warn(docname, 'default role %s not found' % - self.config.default_role) + logger.warning('default role %s not found', self.config.default_role, + location=docname) - codecs.register_error('sphinx', self.warn_and_replace) + codecs.register_error('sphinx', self.warn_and_replace) # type: ignore # publish manually reader = SphinxStandaloneReader(self.app, parsers=self.config.source_parsers) @@ -747,24 +808,30 @@ class BuildEnvironment(object): @property def docname(self): + # type: () -> unicode """Returns the docname of the document currently being parsed.""" return self.temp_data['docname'] @property def currmodule(self): + # type () -> None """Backwards compatible alias. Will be removed.""" - self.warn(self.docname, 'env.currmodule is being referenced by an ' - 'extension; this API will be removed in the future') + logger.warning('env.currmodule is being referenced by an ' + 'extension; this API will be removed in the future', + location=self.docname) return self.ref_context.get('py:module') @property def currclass(self): + # type: () -> None """Backwards compatible alias. Will be removed.""" - self.warn(self.docname, 'env.currclass is being referenced by an ' - 'extension; this API will be removed in the future') + logger.warning('env.currclass is being referenced by an ' + 'extension; this API will be removed in the future', + location=self.docname) return self.ref_context.get('py:class') def new_serialno(self, category=''): + # type: (unicode) -> int """Return a serial number, e.g. for index entry targets. The number is guaranteed to be unique in the current document. @@ -775,15 +842,17 @@ class BuildEnvironment(object): return cur def note_dependency(self, filename): + # type: (unicode) -> None """Add *filename* as a dependency of the current document. This means that the document will be rebuilt if this file changes. *filename* should be absolute or relative to the source directory. """ - self.dependencies.setdefault(self.docname, set()).add(filename) + self.dependencies[self.docname].add(filename) def note_included(self, filename): + # type: (unicode) -> None """Add *filename* as a included from other document. This means the document is not orphaned. @@ -793,12 +862,14 @@ class BuildEnvironment(object): self.included.add(self.path2doc(filename)) def note_reread(self): + # type: () -> None """Add the current document to the list of documents that will automatically be re-read at the next build. """ self.reread_always.add(self.docname) def note_versionchange(self, type, version, node, lineno): + # type: (unicode, unicode, nodes.Node, int) -> None self.versionchanges.setdefault(version, []).append( (type, self.temp_data['docname'], lineno, self.ref_context.get('py:module'), @@ -807,6 +878,7 @@ class BuildEnvironment(object): # post-processing of read doctrees def process_dependencies(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Process docutils-generated dependency info.""" cwd = getcwd() frompath = path.join(path.normpath(self.srcdir), 'dummy') @@ -820,25 +892,27 @@ class BuildEnvironment(object): dep = dep.decode(fs_encoding) relpath = relative_path(frompath, path.normpath(path.join(cwd, dep))) - self.dependencies.setdefault(docname, set()).add(relpath) + self.dependencies[docname].add(relpath) def process_downloads(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Process downloadable file paths. """ for node in doctree.traverse(addnodes.download_reference): targetname = node['reftarget'] rel_filename, filename = self.relfn2path(targetname, docname) - self.dependencies.setdefault(docname, set()).add(rel_filename) + self.dependencies[docname].add(rel_filename) if not os.access(filename, os.R_OK): - self.warn_node('download file not readable: %s' % filename, - node) + logger.warning('download file not readable: %s', filename, + location=node) continue uniquename = self.dlfiles.add_file(docname, filename) node['filename'] = uniquename def process_images(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Process and rewrite image URIs.""" def collect_candidates(imgpath, candidates): - globbed = {} + globbed = {} # type: Dict[unicode, List[unicode]] for filename in glob(imgpath): new_imgpath = relative_path(path.join(self.srcdir, 'dummy'), filename) @@ -847,8 +921,8 @@ class BuildEnvironment(object): if mimetype not in candidates: globbed.setdefault(mimetype, []).append(new_imgpath) except (OSError, IOError) as err: - self.warn_node('image file %s not readable: %s' % - (filename, err), node) + logger.warning('image file %s not readable: %s', filename, err, + location=node) for key, files in iteritems(globbed): candidates[key] = sorted(files, key=len)[0] # select by similarity @@ -860,13 +934,13 @@ class BuildEnvironment(object): node['candidates'] = candidates = {} imguri = node['uri'] if imguri.startswith('data:'): - self.warn_node('image data URI found. some builders might not support', node, - type='image', subtype='data_uri') + logger.warning('image data URI found. some builders might not support', + location=node, type='image', subtype='data_uri') candidates['?'] = imguri continue elif imguri.find('://') != -1: - self.warn_node('nonlocal image URI found: %s' % imguri, node, - type='image', subtype='nonlocal_uri') + logger.warning('nonlocal image URI found: %s', imguri, + location=node, type='image', subtype='nonlocal_uri') candidates['?'] = imguri continue rel_imgpath, full_imgpath = self.relfn2path(imguri, docname) @@ -893,19 +967,21 @@ class BuildEnvironment(object): # map image paths to unique image names (so that they can be put # into a single directory) for imgpath in itervalues(candidates): - self.dependencies.setdefault(docname, set()).add(imgpath) + self.dependencies[docname].add(imgpath) if not os.access(path.join(self.srcdir, imgpath), os.R_OK): - self.warn_node('image file not readable: %s' % imgpath, - node) + logger.warning('image file not readable: %s', imgpath, + location=node) continue self.images.add_file(docname, imgpath) def process_metadata(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Process the docinfo part of the doctree as metadata. Keep processing minimal -- just return what docutils says. """ - self.metadata[docname] = md = {} + self.metadata[docname] = {} + md = self.metadata[docname] try: docinfo = doctree[0] except IndexError: @@ -934,6 +1010,7 @@ class BuildEnvironment(object): del doctree[0] def create_title_from(self, docname, document): + # type: (unicode, nodes.Node) -> None """Add a title node to the document (just copy the first section title), and store that title in the environment. """ @@ -957,20 +1034,24 @@ class BuildEnvironment(object): self.longtitles[docname] = longtitlenode def note_toctree(self, docname, toctreenode): + # type: (unicode, addnodes.toctree) -> None """Note a TOC tree directive in a document and gather information about file relations from it. """ - self.toctree.note_toctree(docname, toctreenode) + self.toctree.note_toctree(docname, toctreenode) # type: ignore def get_toc_for(self, docname, builder): + # type: (unicode, Builder) -> addnodes.toctree """Return a TOC nodetree -- for use on the same page only!""" - return self.toctree.get_toc_for(docname, builder) + return self.toctree.get_toc_for(docname, builder) # type: ignore def get_toctree_for(self, docname, builder, collapse, **kwds): + # type: (unicode, Builder, bool, Any) -> addnodes.toctree """Return the global TOC nodetree.""" - return self.toctree.get_toctree_for(docname, builder, collapse, **kwds) + return self.toctree.get_toctree_for(docname, builder, collapse, **kwds) # type: ignore def get_domain(self, domainname): + # type: (unicode) -> Domain """Return the domain instance with the specified name. Raises an ExtensionError if the domain is not registered. @@ -983,6 +1064,7 @@ class BuildEnvironment(object): # --------- RESOLVING REFERENCES AND TOCTREES ------------------------------ def get_doctree(self, docname): + # type: (unicode) -> nodes.Node """Read the doctree for a file from the pickle and return it.""" doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') with open(doctree_filename, 'rb') as f: @@ -994,6 +1076,7 @@ class BuildEnvironment(object): def get_and_resolve_doctree(self, docname, builder, doctree=None, prune_toctrees=True, includehidden=False): + # type: (unicode, Builder, nodes.Node, bool, bool) -> nodes.Node """Read the doctree from the pickle, resolve cross-references and toctrees and return it. """ @@ -1017,6 +1100,7 @@ class BuildEnvironment(object): def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, titles_only=False, collapse=False, includehidden=False): + # type: (unicode, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Node """Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node. @@ -1028,11 +1112,12 @@ class BuildEnvironment(object): If *collapse* is True, all branches not containing docname will be collapsed. """ - return self.toctree.resolve_toctree(docname, builder, toctree, prune, + return self.toctree.resolve_toctree(docname, builder, toctree, prune, # type: ignore maxdepth, titles_only, collapse, includehidden) def resolve_references(self, doctree, fromdocname, builder): + # type: (nodes.Node, unicode, Builder) -> None for node in doctree.traverse(addnodes.pending_xref): contnode = node[0].deepcopy() newnode = None @@ -1069,12 +1154,13 @@ class BuildEnvironment(object): node.replace_self(newnode or contnode) # remove only-nodes that do not belong to our builder - process_only_nodes(doctree, builder.tags, warn_node=self.warn_node) + process_only_nodes(doctree, builder.tags) # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname) def _warn_missing_reference(self, refdoc, typ, target, node, domain): + # type: (unicode, unicode, unicode, nodes.Node, Domain) -> None warn = node.get('refwarn') if self.config.nitpicky: warn = True @@ -1097,9 +1183,11 @@ class BuildEnvironment(object): (node['refdomain'], typ) else: msg = '%r reference target not found: %%(target)s' % typ - self.warn_node(msg % {'target': target}, node, type='ref', subtype=typ) + logger.warning(msg % {'target': target}, + location=node, type='ref', subtype=typ) def _resolve_doc_reference(self, builder, refdoc, node, contnode): + # type: (Builder, unicode, nodes.Node, nodes.Node) -> nodes.Node # directly reference to document by source name; # can be absolute or relative docname = docname_join(refdoc, node['reftarget']) @@ -1117,9 +1205,10 @@ class BuildEnvironment(object): return newnode def _resolve_any_reference(self, builder, refdoc, node, contnode): + # type: (Builder, unicode, nodes.Node, nodes.Node) -> nodes.Node """Resolve reference generated by the "any" role.""" target = node['reftarget'] - results = [] + results = [] # type: List[Tuple[unicode, nodes.Node]] # first, try resolving as :doc: doc_ref = self._resolve_doc_reference(builder, refdoc, node, contnode) if doc_ref: @@ -1146,9 +1235,9 @@ class BuildEnvironment(object): return None if len(results) > 1: nice_results = ' or '.join(':%s:' % r[0] for r in results) - self.warn_node('more than one target found for \'any\' cross-' - 'reference %r: could be %s' % (target, nice_results), - node) + logger.warning('more than one target found for \'any\' cross-' + 'reference %r: could be %s', target, nice_results, + location=node) res_role, newnode = results[0] # Override "any" class with the actual role type to get the styling # approximately correct. @@ -1160,14 +1249,16 @@ class BuildEnvironment(object): def create_index(self, builder, group_entries=True, _fixre=re.compile(r'(.*) ([(][^()]*[)])')): - return self.indices.create_index(builder, group_entries=group_entries, _fixre=_fixre) + # type: (Builder, bool, Pattern) -> Any + return self.indices.create_index(builder, group_entries=group_entries, _fixre=_fixre) # type: ignore # NOQA def collect_relations(self): + # type: () -> Dict[unicode, List[unicode]] traversed = set() def traverse_toctree(parent, docname): if parent == docname: - self.warn(docname, 'self referenced toctree found. Ignored.') + logger.warning('self referenced toctree found. Ignored.', location=docname) return # traverse toctree by pre-order @@ -1195,6 +1286,7 @@ class BuildEnvironment(object): return relations def check_consistency(self): + # type: () -> None """Do consistency checks.""" for docname in sorted(self.all_docs): if docname not in self.files_to_rebuild: @@ -1206,4 +1298,5 @@ class BuildEnvironment(object): continue if 'orphan' in self.metadata[docname]: continue - self.warn(docname, 'document isn\'t included in any toctree') + logger.warning('document isn\'t included in any toctree', + location=docname) diff --git a/sphinx/environment/managers/__init__.py b/sphinx/environment/managers/__init__.py index 963ec54b8..0822f1091 100644 --- a/sphinx/environment/managers/__init__.py +++ b/sphinx/environment/managers/__init__.py @@ -9,29 +9,42 @@ :license: BSD, see LICENSE for details. """ +if False: + # For type annotation + from typing import Any # NOQA + from docutils import nodes # NOQA + from sphinx.environment import BuildEnvironment # NOQA + class EnvironmentManager(object): """Base class for sphinx.environment managers.""" - name = None + name = None # type: unicode + env = None # type: BuildEnvironment def __init__(self, env): + # type: (BuildEnvironment) -> None self.env = env def attach(self, env): + # type: (BuildEnvironment) -> None self.env = env if self.name: setattr(env, self.name, self) def detach(self, env): + # type: (BuildEnvironment) -> None self.env = None if self.name: delattr(env, self.name) def clear_doc(self, docname): + # type: (unicode) -> None raise NotImplementedError def merge_other(self, docnames, other): + # type: (List[unicode], Any) -> None raise NotImplementedError def process_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None raise NotImplementedError diff --git a/sphinx/environment/managers/indexentries.py b/sphinx/environment/managers/indexentries.py index d4e5f05bd..ef9c84d02 100644 --- a/sphinx/environment/managers/indexentries.py +++ b/sphinx/environment/managers/indexentries.py @@ -15,35 +15,47 @@ import string from itertools import groupby from six import text_type - from sphinx import addnodes -from sphinx.util import iteritems, split_index_msg, split_into +from sphinx.util import iteritems, split_index_msg, split_into, logging from sphinx.locale import _ from sphinx.environment.managers import EnvironmentManager +if False: + # For type annotation + from typing import Pattern, Tuple # NOQA + from docutils import nodes # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + class IndexEntries(EnvironmentManager): name = 'indices' def __init__(self, env): + # type: (BuildEnvironment) -> None super(IndexEntries, self).__init__(env) self.data = env.indexentries def clear_doc(self, docname): + # type: (unicode) -> None self.data.pop(docname, None) def merge_other(self, docnames, other): + # type: (List[unicode], BuildEnvironment) -> None for docname in docnames: self.data[docname] = other.indexentries[docname] def process_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None entries = self.data[docname] = [] for node in doctree.traverse(addnodes.index): try: for entry in node['entries']: split_index_msg(entry[0], entry[1]) except ValueError as exc: - self.env.warn_node(exc, node) + logger.warning(str(exc), location=node) node.parent.remove(node) else: for entry in node['entries']: @@ -55,10 +67,11 @@ class IndexEntries(EnvironmentManager): def create_index(self, builder, group_entries=True, _fixre=re.compile(r'(.*) ([(][^()]*[)])')): + # type: (Builder, bool, Pattern) -> List[Tuple[unicode, List[Tuple[unicode, List[unicode]]]]] # NOQA """Create the real index from the collected index entries.""" from sphinx.environment import NoUri - new = {} + new = {} # type: Dict[unicode, List] def add_entry(word, subword, main, link=True, dic=new, key=None): # Force the word to be unicode if it's a ASCII bytestring. @@ -108,9 +121,9 @@ class IndexEntries(EnvironmentManager): add_entry(first, _('see also %s') % second, None, link=False, key=index_key) else: - self.env.warn(fn, 'unknown index entry type %r' % type) + logger.warning('unknown index entry type %r', type, location=fn) except ValueError as err: - self.env.warn(fn, str(err)) + logger.warning(str(err), location=fn) # sort the index entries; put all symbols at the front, even those # following the letters in ASCII, this is where the chr(127) comes from @@ -135,8 +148,8 @@ class IndexEntries(EnvironmentManager): # func() # (in module foo) # (in module bar) - oldkey = '' - oldsubitems = None + oldkey = '' # type: unicode + oldsubitems = None # type: Dict[unicode, List] i = 0 while i < len(newlist): key, (targets, subitems, _key) = newlist[i] diff --git a/sphinx/environment/managers/toctree.py b/sphinx/environment/managers/toctree.py index 67fbfa7b6..8f247c986 100644 --- a/sphinx/environment/managers/toctree.py +++ b/sphinx/environment/managers/toctree.py @@ -10,19 +10,29 @@ """ from six import iteritems + from docutils import nodes from sphinx import addnodes -from sphinx.util import url_re +from sphinx.util import url_re, logging from sphinx.util.nodes import clean_astext, process_only_nodes from sphinx.transforms import SphinxContentsFilter from sphinx.environment.managers import EnvironmentManager +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + class Toctree(EnvironmentManager): name = 'toctree' def __init__(self, env): + # type: (BuildEnvironment) -> None super(Toctree, self).__init__(env) self.tocs = env.tocs @@ -35,6 +45,7 @@ class Toctree(EnvironmentManager): self.numbered_toctrees = env.numbered_toctrees def clear_doc(self, docname): + # type: (unicode) -> None self.tocs.pop(docname, None) self.toc_secnumbers.pop(docname, None) self.toc_fignumbers.pop(docname, None) @@ -49,6 +60,7 @@ class Toctree(EnvironmentManager): del self.files_to_rebuild[subfn] def merge_other(self, docnames, other): + # type: (List[unicode], BuildEnvironment) -> None for docname in docnames: self.tocs[docname] = other.tocs[docname] self.toc_num_entries[docname] = other.toc_num_entries[docname] @@ -63,6 +75,7 @@ class Toctree(EnvironmentManager): self.files_to_rebuild.setdefault(subfn, set()).update(fnset & docnames) def process_doc(self, docname, doctree): + # type: (unicode, nodes.Node) -> None """Build a TOC from the doctree and store it in the inventory.""" numentries = [0] # nonlocal again... @@ -132,6 +145,7 @@ class Toctree(EnvironmentManager): self.toc_num_entries[docname] = numentries[0] def note_toctree(self, docname, toctreenode): + # type: (unicode, addnodes.toctree) -> None """Note a TOC tree directive in a document and gather information about file relations from it. """ @@ -147,6 +161,7 @@ class Toctree(EnvironmentManager): self.toctree_includes.setdefault(docname, []).extend(includefiles) def get_toc_for(self, docname, builder): + # type: (unicode, Builder) -> None """Return a TOC nodetree -- for use on the same page only!""" tocdepth = self.env.metadata[docname].get('tocdepth', 0) try: @@ -156,12 +171,13 @@ class Toctree(EnvironmentManager): # the document does not exist anymore: return a dummy node that # renders to nothing return nodes.paragraph() - process_only_nodes(toc, builder.tags, warn_node=self.env.warn_node) + process_only_nodes(toc, builder.tags) for node in toc.traverse(nodes.reference): node['refuri'] = node['anchorname'] or '#' return toc def get_toctree_for(self, docname, builder, collapse, **kwds): + # type: (unicode, Builder, bool, Any) -> nodes.Node """Return the global TOC nodetree.""" doctree = self.env.get_doctree(self.env.config.master_doc) toctrees = [] @@ -184,6 +200,7 @@ class Toctree(EnvironmentManager): def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, titles_only=False, collapse=False, includehidden=False): + # type: (unicode, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Node """Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node. @@ -281,16 +298,17 @@ class Toctree(EnvironmentManager): toc = nodes.bullet_list('', item) else: if ref in parents: - self.env.warn(ref, 'circular toctree references ' - 'detected, ignoring: %s <- %s' % - (ref, ' <- '.join(parents))) + logger.warning('circular toctree references ' + 'detected, ignoring: %s <- %s', + ref, ' <- '.join(parents), + location=ref) continue refdoc = ref toc = self.tocs[ref].deepcopy() maxdepth = self.env.metadata[ref].get('tocdepth', 0) if ref not in toctree_ancestors or (prune and maxdepth > 0): self._toctree_prune(toc, 2, maxdepth, collapse) - process_only_nodes(toc, builder.tags, warn_node=self.env.warn_node) + process_only_nodes(toc, builder.tags) if title and toc.children and len(toc.children) == 1: child = toc.children[0] for refnode in child.traverse(nodes.reference): @@ -299,15 +317,13 @@ class Toctree(EnvironmentManager): refnode.children = [nodes.Text(title)] if not toc.children: # empty toc means: no titles will show up in the toctree - self.env.warn_node( - 'toctree contains reference to document %r that ' - 'doesn\'t have a title: no link will be generated' - % ref, toctreenode) + logger.warning('toctree contains reference to document %r that ' + 'doesn\'t have a title: no link will be generated', + ref, location=toctreenode) except KeyError: # this is raised if the included file does not exist - self.env.warn_node( - 'toctree contains reference to nonexisting document %r' - % ref, toctreenode) + logger.warning('toctree contains reference to nonexisting document %r', + ref, location=toctreenode) else: # if titles_only is given, only keep the main title and # sub-toctrees @@ -387,11 +403,12 @@ class Toctree(EnvironmentManager): return newnode def get_toctree_ancestors(self, docname): + # type: (unicode) -> List[unicode] parent = {} for p, children in iteritems(self.toctree_includes): for child in children: parent[child] = p - ancestors = [] + ancestors = [] # type: List[unicode] d = docname while d in parent and d not in ancestors: ancestors.append(d) @@ -399,6 +416,7 @@ class Toctree(EnvironmentManager): return ancestors def _toctree_prune(self, node, depth, maxdepth, collapse=False): + # type: (nodes.Node, int, int, bool) -> None """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: if isinstance(subnode, (addnodes.compact_paragraph, @@ -420,11 +438,12 @@ class Toctree(EnvironmentManager): self._toctree_prune(subnode, depth+1, maxdepth, collapse) def assign_section_numbers(self): + # type: () -> List[unicode] """Assign a section number to each heading under a numbered toctree.""" # a list of all docnames whose section numbers changed rewrite_needed = [] - assigned = set() + assigned = set() # type: Set[unicode] old_secnumbers = self.toc_secnumbers self.toc_secnumbers = self.env.toc_secnumbers = {} @@ -468,9 +487,9 @@ class Toctree(EnvironmentManager): # don't mess with those continue elif ref in assigned: - self.env.warn_node('%s is already assigned section numbers ' - '(nested numbered toctree?)' % ref, - toctreenode, type='toc', subtype='secnum') + logger.warning('%s is already assigned section numbers ' + '(nested numbered toctree?)', ref, + location=toctreenode, type='toc', subtype='secnum') elif ref in self.tocs: secnums = self.toc_secnumbers[ref] = {} assigned.add(ref) @@ -492,14 +511,15 @@ class Toctree(EnvironmentManager): return rewrite_needed def assign_figure_numbers(self): + # type: () -> List[unicode] """Assign a figure number to each figure under a numbered toctree.""" rewrite_needed = [] - assigned = set() + assigned = set() # type: Set[unicode] old_fignumbers = self.toc_fignumbers self.toc_fignumbers = self.env.toc_fignumbers = {} - fignum_counter = {} + fignum_counter = {} # type: Dict[unicode, Dict[Tuple[int], int]] def get_section_number(docname, section): anchorname = '#' + section['ids'][0] @@ -544,7 +564,7 @@ class Toctree(EnvironmentManager): continue - figtype = self.env.domains['std'].get_figtype(subnode) + figtype = self.env.get_domain('std').get_figtype(subnode) # type: ignore if figtype and subnode['ids']: register_fignumber(docname, secnum, figtype, subnode) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index efa642c8f..01ced26de 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -20,8 +20,10 @@ from types import FunctionType, BuiltinFunctionType, MethodType from six import PY2, iterkeys, iteritems, itervalues, text_type, class_types, \ string_types, StringIO + from docutils import nodes from docutils.utils import assemble_option_dict +from docutils.parsers.rst import Directive from docutils.statemachine import ViewList import sphinx @@ -29,21 +31,30 @@ from sphinx.util import rpartition, force_decode from sphinx.locale import _ from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.application import ExtensionError +from sphinx.util import logging from sphinx.util.nodes import nested_parse_with_titles -from sphinx.util.compat import Directive from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \ safe_getattr, object_description, is_builtin_class_method, \ isenumclass, isenumattribute from sphinx.util.docstrings import prepare_docstring +if False: + # For type annotation + from typing import Any, Callable, Iterator, Sequence, Tuple, Type, Union # NOQA + from types import ModuleType # NOQA + from docutils.utils import Reporter # NOQA + from sphinx.application import Sphinx # NOQA + try: if sys.version_info >= (3,): import typing else: - typing = None + typing = None # type: ignore except ImportError: typing = None +logger = logging.getLogger(__name__) + # This type isn't exposed directly in any modules, but can be found # here in most Python versions MethodDescriptorType = type(type.__subclasses__) @@ -63,28 +74,33 @@ py_ext_sig_re = re.compile( class DefDict(dict): """A dict that returns a default on nonexisting keys.""" def __init__(self, default): + # type: (Any) -> None dict.__init__(self) self.default = default def __getitem__(self, key): + # type: (Any) -> Any try: return dict.__getitem__(self, key) except KeyError: return self.default def __bool__(self): + # type: () -> bool # docutils check "if option_spec" return True __nonzero__ = __bool__ # for python2 compatibility def identity(x): + # type: (Any) -> Any return x class Options(dict): """A dict/attribute hybrid that returns None on nonexisting keys.""" def __getattr__(self, name): + # type: (unicode) -> Any try: return self[name.replace('_', '-')] except KeyError: @@ -97,22 +113,26 @@ class _MockModule(object): __path__ = '/dev/null' def __init__(self, *args, **kwargs): - self.__all__ = [] + # type: (Any, Any) -> None + self.__all__ = [] # type: List[str] def __call__(self, *args, **kwargs): + # type: (Any, Any) -> _MockModule if args and type(args[0]) in [FunctionType, MethodType]: # Appears to be a decorator, pass through unchanged return args[0] return _MockModule() def _append_submodule(self, submod): + # type: (str) -> None self.__all__.append(submod) @classmethod def __getattr__(cls, name): + # type: (unicode) -> Any if name[0] == name[0].upper(): # Not very good, we assume Uppercase names are classes... - mocktype = type(name, (), {}) + mocktype = type(name, (), {}) # type: ignore mocktype.__module__ = __name__ return mocktype else: @@ -120,15 +140,16 @@ class _MockModule(object): def mock_import(modname): + # type: (str) -> None if '.' in modname: pkg, _n, mods = modname.rpartition('.') mock_import(pkg) if isinstance(sys.modules[pkg], _MockModule): - sys.modules[pkg]._append_submodule(mods) + sys.modules[pkg]._append_submodule(mods) # type: ignore if modname not in sys.modules: mod = _MockModule() - sys.modules[modname] = mod + sys.modules[modname] = mod # type: ignore ALL = object() @@ -136,6 +157,7 @@ INSTANCEATTR = object() def members_option(arg): + # type: (Any) -> Union[object, List[unicode]] """Used to convert the :members: option to auto directives.""" if arg is None: return ALL @@ -143,6 +165,7 @@ def members_option(arg): def members_set_option(arg): + # type: (Any) -> Union[object, Set[unicode]] """Used to convert the :members: option to auto directives.""" if arg is None: return ALL @@ -153,6 +176,7 @@ SUPPRESS = object() def annotation_option(arg): + # type: (Any) -> Any if arg is None: # suppress showing the representation of the object return SUPPRESS @@ -161,6 +185,7 @@ def annotation_option(arg): def bool_option(arg): + # type: (Any) -> bool """Used to convert flag options to auto directives. (Instead of directives.flag(), which returns None). """ @@ -173,13 +198,16 @@ class AutodocReporter(object): and line number to a system message, as recorded in a ViewList. """ def __init__(self, viewlist, reporter): + # type: (ViewList, Reporter) -> None self.viewlist = viewlist self.reporter = reporter def __getattr__(self, name): + # type: (unicode) -> Any return getattr(self.reporter, name) def system_message(self, level, message, *children, **kwargs): + # type: (int, unicode, Any, Any) -> nodes.system_message if 'line' in kwargs and 'source' not in kwargs: try: source, line = self.viewlist.items[kwargs['line']] @@ -192,25 +220,31 @@ class AutodocReporter(object): *children, **kwargs) def debug(self, *args, **kwargs): + # type: (Any, Any) -> nodes.system_message if self.reporter.debug_flag: return self.system_message(0, *args, **kwargs) def info(self, *args, **kwargs): + # type: (Any, Any) -> nodes.system_message return self.system_message(1, *args, **kwargs) def warning(self, *args, **kwargs): + # type: (Any, Any) -> nodes.system_message return self.system_message(2, *args, **kwargs) def error(self, *args, **kwargs): + # type: (Any, Any) -> nodes.system_message return self.system_message(3, *args, **kwargs) def severe(self, *args, **kwargs): + # type: (Any, Any) -> nodes.system_message return self.system_message(4, *args, **kwargs) # Some useful event listener factories for autodoc-process-docstring. def cut_lines(pre, post=0, what=None): + # type: (int, int, unicode) -> Callable """Return a listener that removes the first *pre* and last *post* lines of every docstring. If *what* is a sequence of strings, only docstrings of a type in *what* will be processed. @@ -223,6 +257,7 @@ def cut_lines(pre, post=0, what=None): This can (and should) be used in place of :confval:`automodule_skip_lines`. """ def process(app, what_, name, obj, options, lines): + # type: (Sphinx, unicode, unicode, Any, Any, List[unicode]) -> None if what and what_ not in what: return del lines[:pre] @@ -238,6 +273,7 @@ def cut_lines(pre, post=0, what=None): def between(marker, what=None, keepempty=False, exclude=False): + # type: (unicode, Sequence[unicode], bool, bool) -> Callable """Return a listener that either keeps, or if *exclude* is True excludes, lines between lines that match the *marker* regular expression. If no line matches, the resulting docstring would be empty, so no change will be made @@ -249,6 +285,7 @@ def between(marker, what=None, keepempty=False, exclude=False): marker_re = re.compile(marker) def process(app, what_, name, obj, options, lines): + # type: (Sphinx, unicode, unicode, Any, Any, List[unicode]) -> None if what and what_ not in what: return deleted = 0 @@ -272,6 +309,7 @@ def between(marker, what=None, keepempty=False, exclude=False): def format_annotation(annotation): + # type: (Any) -> str """Return formatted representation of a type annotation. Show qualified names for types and additional details for types from @@ -279,18 +317,18 @@ def format_annotation(annotation): Displaying complex types from ``typing`` relies on its private API. """ - if typing and isinstance(annotation, typing.TypeVar): + if typing and isinstance(annotation, typing.TypeVar): # type: ignore return annotation.__name__ if annotation == Ellipsis: return '...' if not isinstance(annotation, type): return repr(annotation) - qualified_name = (annotation.__module__ + '.' + annotation.__qualname__ + qualified_name = (annotation.__module__ + '.' + annotation.__qualname__ # type: ignore if annotation else repr(annotation)) if annotation.__module__ == 'builtins': - return annotation.__qualname__ + return annotation.__qualname__ # type: ignore elif typing: if hasattr(typing, 'GenericMeta') and \ isinstance(annotation, typing.GenericMeta): @@ -351,6 +389,7 @@ def format_annotation(annotation): def formatargspec(function, args, varargs=None, varkw=None, defaults=None, kwonlyargs=(), kwonlydefaults={}, annotations={}): + # type: (Callable, Tuple[str, ...], str, str, Any, Tuple, Dict, Dict[str, Any]) -> str """Return a string representation of an ``inspect.FullArgSpec`` tuple. An enhanced version of ``inspect.formatargspec()`` that handles typing @@ -358,18 +397,20 @@ def formatargspec(function, args, varargs=None, varkw=None, defaults=None, """ def format_arg_with_annotation(name): + # type: (str) -> str if name in annotations: return '%s: %s' % (name, format_annotation(get_annotation(name))) return name def get_annotation(name): + # type: (str) -> str value = annotations[name] if isinstance(value, string_types): return introspected_hints.get(name, value) else: return value - introspected_hints = (typing.get_type_hints(function) + introspected_hints = (typing.get_type_hints(function) # type: ignore if typing and hasattr(function, '__code__') else {}) fd = StringIO() @@ -383,7 +424,7 @@ def formatargspec(function, args, varargs=None, varkw=None, defaults=None, arg_fd.write(format_arg_with_annotation(arg)) if defaults and i >= defaults_start: arg_fd.write(' = ' if arg in annotations else '=') - arg_fd.write(object_description(defaults[i - defaults_start])) + arg_fd.write(object_description(defaults[i - defaults_start])) # type: ignore formatted.append(arg_fd.getvalue()) if varargs: @@ -398,7 +439,7 @@ def formatargspec(function, args, varargs=None, varkw=None, defaults=None, arg_fd.write(format_arg_with_annotation(kwarg)) if kwonlydefaults and kwarg in kwonlydefaults: arg_fd.write(' = ' if kwarg in annotations else '=') - arg_fd.write(object_description(kwonlydefaults[kwarg])) + arg_fd.write(object_description(kwonlydefaults[kwarg])) # type: ignore formatted.append(arg_fd.getvalue()) if varkw: @@ -445,6 +486,7 @@ class Documenter(object): @staticmethod def get_attr(obj, name, *defargs): + # type: (Any, unicode, Any) -> Any """getattr() override for types such as Zope interfaces.""" for typ, func in iteritems(AutoDirective._special_attrgetters): if isinstance(obj, typ): @@ -453,10 +495,12 @@ class Documenter(object): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool """Called to see if a member can be documented by this documenter.""" raise NotImplementedError('must be implemented in subclasses') def __init__(self, directive, name, indent=u''): + # type: (Directive, unicode, unicode) -> None self.directive = directive self.env = directive.env self.options = directive.genopt @@ -464,27 +508,29 @@ class Documenter(object): self.indent = indent # the module and object path within the module, and the fully # qualified name (all set after resolve_name succeeds) - self.modname = None - self.module = None - self.objpath = None - self.fullname = None + self.modname = None # type: str + self.module = None # type: ModuleType + self.objpath = None # type: List[unicode] + self.fullname = None # type: unicode # extra signature items (arguments and return annotation, # also set after resolve_name succeeds) - self.args = None - self.retann = None + self.args = None # type: unicode + self.retann = None # type: unicode # the object to document (set after import_object succeeds) - self.object = None - self.object_name = None + self.object = None # type: Any + self.object_name = None # type: unicode # the parent/owner of the object to document - self.parent = None + self.parent = None # type: Any # the module analyzer to get at attribute docs, or None - self.analyzer = None + self.analyzer = None # type: Any def add_line(self, line, source, *lineno): + # type: (unicode, unicode, int) -> None """Append one line of generated reST to the output.""" self.directive.result.append(self.indent + line, source, *lineno) def resolve_name(self, modname, parents, path, base): + # type: (str, Any, str, Any) -> Tuple[str, List[unicode]] """Resolve the module and name of the object to document given by the arguments and the current module/class. @@ -495,6 +541,7 @@ class Documenter(object): raise NotImplementedError('must be implemented in subclasses') def parse_name(self): + # type: () -> bool """Determine what module to import and what attribute to document. Returns True and sets *self.modname*, *self.objpath*, *self.fullname*, @@ -505,7 +552,7 @@ class Documenter(object): # an autogenerated one try: explicit_modname, path, base, args, retann = \ - py_ext_sig_re.match(self.name).groups() + py_ext_sig_re.match(self.name).groups() # type: ignore except AttributeError: self.directive.warn('invalid signature for auto%s (%r)' % (self.objtype, self.name)) @@ -519,8 +566,7 @@ class Documenter(object): modname = None parents = [] - self.modname, self.objpath = \ - self.resolve_name(modname, parents, path, base) + self.modname, self.objpath = self.resolve_name(modname, parents, path, base) if not self.modname: return False @@ -532,31 +578,31 @@ class Documenter(object): return True def import_object(self): + # type: () -> bool """Import the object given by *self.modname* and *self.objpath* and set it as *self.object*. Returns True if successful, False if an error occurred. """ - dbg = self.env.app.debug if self.objpath: - dbg('[autodoc] from %s import %s', - self.modname, '.'.join(self.objpath)) + logger.debug('[autodoc] from %s import %s', + self.modname, '.'.join(self.objpath)) try: - dbg('[autodoc] import %s', self.modname) + logger.debug('[autodoc] import %s', self.modname) for modname in self.env.config.autodoc_mock_imports: - dbg('[autodoc] adding a mock module %s!', modname) + logger.debug('[autodoc] adding a mock module %s!', modname) mock_import(modname) with warnings.catch_warnings(): warnings.filterwarnings("ignore", category=ImportWarning) __import__(self.modname) parent = None obj = self.module = sys.modules[self.modname] - dbg('[autodoc] => %r', obj) + logger.debug('[autodoc] => %r', obj) for part in self.objpath: parent = obj - dbg('[autodoc] getattr(_, %r)', part) + logger.debug('[autodoc] getattr(_, %r)', part) obj = self.get_attr(obj, part) - dbg('[autodoc] => %r', obj) + logger.debug('[autodoc] => %r', obj) self.object_name = part self.parent = parent self.object = obj @@ -577,13 +623,14 @@ class Documenter(object): errmsg += '; the following exception was raised:\n%s' % \ traceback.format_exc() if PY2: - errmsg = errmsg.decode('utf-8') - dbg(errmsg) + errmsg = errmsg.decode('utf-8') # type: ignore + logger.debug(errmsg) self.directive.warn(errmsg) self.env.note_reread() return False def get_real_modname(self): + # type: () -> str """Get the real module name of an object to document. It can differ from the name of the module through which the object was @@ -592,6 +639,7 @@ class Documenter(object): return self.get_attr(self.object, '__module__', None) or self.modname def check_module(self): + # type: () -> bool """Check if *self.object* is really defined in the module given by *self.modname*. """ @@ -604,6 +652,7 @@ class Documenter(object): return True def format_args(self): + # type: () -> unicode """Format the argument signature of *self.object*. Should return None if the object does not have a signature. @@ -611,6 +660,7 @@ class Documenter(object): return None def format_name(self): + # type: () -> unicode """Format the name of *self.object*. This normally should be something that can be parsed by the generated @@ -622,13 +672,14 @@ class Documenter(object): return '.'.join(self.objpath) or self.modname def format_signature(self): + # type: () -> unicode """Format the signature (arguments and return annotation) of the object. Let the user process it via the ``autodoc-process-signature`` event. """ if self.args is not None: # signature given explicitly - args = "(%s)" % self.args + args = "(%s)" % self.args # type: unicode else: # try to introspect the signature try: @@ -652,6 +703,7 @@ class Documenter(object): return '' def add_directive_header(self, sig): + # type: (unicode) -> None """Add the directive header and options to the generated content.""" domain = getattr(self, 'domain', 'py') directive = getattr(self, 'directivetype', self.objtype) @@ -667,6 +719,7 @@ class Documenter(object): self.add_line(u' :module: %s' % self.modname, sourcename) def get_doc(self, encoding=None, ignore=1): + # type: (unicode, int) -> List[List[unicode]] """Decode and return lines of the docstring(s) for the object.""" docstring = self.get_attr(self.object, '__doc__', None) # make sure we have Unicode docstrings, then sanitize and split @@ -680,6 +733,7 @@ class Documenter(object): return [] def process_doc(self, docstrings): + # type: (List[List[unicode]]) -> Iterator[unicode] """Let the user process the docstrings before adding them.""" for docstringlines in docstrings: if self.env.app: @@ -691,6 +745,7 @@ class Documenter(object): yield line def get_sourcename(self): + # type: () -> unicode if self.analyzer: # prevent encoding errors when the file name is non-ASCII if not isinstance(self.analyzer.srcname, text_type): @@ -702,6 +757,7 @@ class Documenter(object): return u'docstring of %s' % self.fullname def add_content(self, more_content, no_docstring=False): + # type: (Any, bool) -> None """Add content from docstrings, attribute documentation and user.""" # set sourcename and add content from attribute documentation sourcename = self.get_sourcename() @@ -733,6 +789,7 @@ class Documenter(object): self.add_line(line, src[0], src[1]) def get_object_members(self, want_all): + # type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]] """Return `(members_check_module, members)` where `members` is a list of `(membername, member)` pairs of the members of *self.object*. @@ -792,6 +849,7 @@ class Documenter(object): return False, sorted(members) def filter_members(self, members, want_all): + # type: (List[Tuple[unicode, Any]], bool) -> List[Tuple[unicode, Any, bool]] """Filter the given member list. Members are skipped if @@ -869,6 +927,7 @@ class Documenter(object): return ret def document_members(self, all_members=False): + # type: (bool) -> None """Generate reST for member documentation. If *all_members* is True, do all members, else those given by @@ -890,7 +949,7 @@ class Documenter(object): if membername not in self.options.exclude_members] # document non-skipped members - memberdocumenters = [] + memberdocumenters = [] # type: List[Tuple[Documenter, bool]] for (mname, member, isattr) in self.filter_members(members, want_all): classes = [cls for cls in itervalues(AutoDirective._registry) if cls.can_document_member(member, mname, isattr, self)] @@ -931,6 +990,7 @@ class Documenter(object): def generate(self, more_content=None, real_modname=None, check_module=False, all_members=False): + # type: (Any, str, bool, bool) -> None """Generate reST for the object given by *self.name*, and possibly for its members. @@ -966,7 +1026,7 @@ class Documenter(object): # be cached anyway) self.analyzer.find_attr_docs() except PycodeError as err: - self.env.app.debug('[autodoc] module analyzer failed: %s', err) + logger.debug('[autodoc] module analyzer failed: %s', err) # no source file -- e.g. for builtin and C modules self.analyzer = None # at least add the module.__file__ as a dependency @@ -1024,15 +1084,18 @@ class ModuleDocumenter(Documenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool # don't document submodules automatically return False def resolve_name(self, modname, parents, path, base): + # type: (str, Any, str, Any) -> Tuple[str, List[unicode]] if modname is not None: self.directive.warn('"::" in automodule name doesn\'t make sense') return (path or '') + base, [] def parse_name(self): + # type: () -> bool ret = Documenter.parse_name(self) if self.args or self.retann: self.directive.warn('signature arguments or return annotation ' @@ -1040,6 +1103,7 @@ class ModuleDocumenter(Documenter): return ret def add_directive_header(self, sig): + # type: (unicode) -> None Documenter.add_directive_header(self, sig) sourcename = self.get_sourcename() @@ -1055,6 +1119,7 @@ class ModuleDocumenter(Documenter): self.add_line(u' :deprecated:', sourcename) def get_object_members(self, want_all): + # type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]] if want_all: if not hasattr(self.object, '__all__'): # for implicit module members, check __module__ to avoid @@ -1091,6 +1156,7 @@ class ModuleLevelDocumenter(Documenter): classes, data/constants). """ def resolve_name(self, modname, parents, path, base): + # type: (str, Any, str, Any) -> Tuple[str, List[unicode]] if modname is None: if path: modname = path.rstrip('.') @@ -1111,6 +1177,7 @@ class ClassLevelDocumenter(Documenter): attributes). """ def resolve_name(self, modname, parents, path, base): + # type: (str, Any, str, Any) -> Tuple[str, List[unicode]] if modname is None: if path: mod_cls = path.rstrip('.') @@ -1144,6 +1211,7 @@ class DocstringSignatureMixin(object): """ def _find_signature(self, encoding=None): + # type: (unicode) -> Tuple[str, str] docstrings = self.get_doc(encoding) self._new_docstrings = docstrings[:] result = None @@ -1152,12 +1220,12 @@ class DocstringSignatureMixin(object): if not doclines: continue # match first line of docstring against signature RE - match = py_ext_sig_re.match(doclines[0]) + match = py_ext_sig_re.match(doclines[0]) # type: ignore if not match: continue exmod, path, base, args, retann = match.groups() # the base name must match ours - valid_names = [self.objpath[-1]] + valid_names = [self.objpath[-1]] # type: ignore if isinstance(self, ClassDocumenter): valid_names.append('__init__') if hasattr(self.object, '__mro__'): @@ -1172,19 +1240,21 @@ class DocstringSignatureMixin(object): return result def get_doc(self, encoding=None, ignore=1): + # type: (unicode, int) -> List[List[unicode]] lines = getattr(self, '_new_docstrings', None) if lines is not None: return lines - return Documenter.get_doc(self, encoding, ignore) + return Documenter.get_doc(self, encoding, ignore) # type: ignore def format_signature(self): - if self.args is None and self.env.config.autodoc_docstring_signature: + # type: () -> unicode + 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 result = self._find_signature() if result is not None: self.args, self.retann = result - return Documenter.format_signature(self) + return Documenter.format_signature(self) # type: ignore class DocstringStripSignatureMixin(DocstringSignatureMixin): @@ -1193,7 +1263,8 @@ class DocstringStripSignatureMixin(DocstringSignatureMixin): feature of stripping any function signature from the docstring. """ def format_signature(self): - if self.args is None and self.env.config.autodoc_docstring_signature: + # type: () -> unicode + 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 result = self._find_signature() @@ -1202,10 +1273,10 @@ class DocstringStripSignatureMixin(DocstringSignatureMixin): # DocstringSignatureMixin.format_signature. # Documenter.format_signature use self.args value to format. _args, self.retann = result - return Documenter.format_signature(self) + return Documenter.format_signature(self) # type: ignore -class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): +class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: ignore """ Specialized Documenter subclass for functions. """ @@ -1214,9 +1285,11 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool return isinstance(member, (FunctionType, BuiltinFunctionType)) def format_args(self): + # type: () -> unicode if inspect.isbuiltin(self.object) or \ inspect.ismethoddescriptor(self.object): # cannot introspect arguments of a C function or method @@ -1243,10 +1316,11 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): return args def document_members(self, all_members=False): + # type: (bool) -> None pass -class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): +class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: ignore """ Specialized Documenter subclass for classes. """ @@ -1262,9 +1336,11 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool return isinstance(member, class_types) def import_object(self): + # type: () -> Any ret = ModuleLevelDocumenter.import_object(self) # if the class is documented under another name, document it # as data/attribute @@ -1276,6 +1352,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): return ret def format_args(self): + # type: () -> unicode # for classes, the relevant signature is the __init__ method's initmeth = self.get_attr(self.object, '__init__', None) # classes without __init__ method, default __init__ or @@ -1295,12 +1372,14 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): return formatargspec(initmeth, *argspec) def format_signature(self): + # type: () -> unicode if self.doc_as_attr: return '' return DocstringSignatureMixin.format_signature(self) def add_directive_header(self, sig): + # type: (unicode) -> None if self.doc_as_attr: self.directivetype = 'attribute' Documenter.add_directive_header(self, sig) @@ -1318,6 +1397,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): sourcename) def get_doc(self, encoding=None, ignore=1): + # type: (unicode, int) -> List[List[unicode]] lines = getattr(self, '_new_docstrings', None) if lines is not None: return lines @@ -1363,6 +1443,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): return doc def add_content(self, more_content, no_docstring=False): + # type: (Any, bool) -> None if self.doc_as_attr: classname = safe_getattr(self.object, '__name__', None) if classname: @@ -1374,6 +1455,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): ModuleLevelDocumenter.add_content(self, more_content) def document_members(self, all_members=False): + # type: (bool) -> None if self.doc_as_attr: return ModuleLevelDocumenter.document_members(self, all_members) @@ -1391,8 +1473,9 @@ class ExceptionDocumenter(ClassDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool return isinstance(member, class_types) and \ - issubclass(member, BaseException) + issubclass(member, BaseException) # type: ignore class DataDocumenter(ModuleLevelDocumenter): @@ -1407,9 +1490,11 @@ class DataDocumenter(ModuleLevelDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool return isinstance(parent, ModuleDocumenter) and isattr def add_directive_header(self, sig): + # type: (unicode) -> None ModuleLevelDocumenter.add_directive_header(self, sig) sourcename = self.get_sourcename() if not self.options.annotation: @@ -1426,10 +1511,11 @@ class DataDocumenter(ModuleLevelDocumenter): sourcename) def document_members(self, all_members=False): + # type: (bool) -> None pass -class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): +class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: ignore """ Specialized Documenter subclass for methods (normal, static and class). """ @@ -1439,10 +1525,12 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool return inspect.isroutine(member) and \ not isinstance(parent, ModuleDocumenter) def import_object(self): + # type: () -> Any ret = ClassLevelDocumenter.import_object(self) if not ret: return ret @@ -1450,11 +1538,11 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # to distinguish classmethod/staticmethod obj = self.parent.__dict__.get(self.object_name) - if isinstance(obj, classmethod): + if isinstance(obj, classmethod): # type: ignore self.directivetype = 'classmethod' # document class and static members before ordinary ones self.member_order = self.member_order - 1 - elif isinstance(obj, staticmethod): + elif isinstance(obj, staticmethod): # type: ignore self.directivetype = 'staticmethod' # document class and static members before ordinary ones self.member_order = self.member_order - 1 @@ -1463,6 +1551,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): return ret def format_args(self): + # type: () -> unicode if inspect.isbuiltin(self.object) or \ inspect.ismethoddescriptor(self.object): # can never get arguments of a C function or method @@ -1476,10 +1565,11 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): return args def document_members(self, all_members=False): + # type: (bool) -> None pass -class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): +class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): # type: ignore """ Specialized Documenter subclass for attributes. """ @@ -1496,6 +1586,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool non_attr_types = cls.method_types + (type, MethodDescriptorType) isdatadesc = isdescriptor(member) and not \ isinstance(member, non_attr_types) and not \ @@ -1508,9 +1599,11 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): not isinstance(member, class_types)) def document_members(self, all_members=False): + # type: (bool) -> None pass def import_object(self): + # type: () -> Any ret = ClassLevelDocumenter.import_object(self) if isenumattribute(self.object): self.object = self.object.value @@ -1523,10 +1616,12 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): return ret def get_real_modname(self): + # type: () -> str return self.get_attr(self.parent or self.object, '__module__', None) \ or self.modname def add_directive_header(self, sig): + # type: (unicode) -> None ClassLevelDocumenter.add_directive_header(self, sig) sourcename = self.get_sourcename() if not self.options.annotation: @@ -1544,6 +1639,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): sourcename) def add_content(self, more_content, no_docstring=False): + # type: (Any, bool) -> None if not self._datadescriptor: # if it's not a data descriptor, its docstring is very probably the # wrong thing to display @@ -1565,10 +1661,12 @@ class InstanceAttributeDocumenter(AttributeDocumenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): + # type: (Any, unicode, bool, Any) -> bool """This documents only INSTANCEATTR members.""" return isattr and (member is INSTANCEATTR) def import_object(self): + # type: () -> bool """Never import anything.""" # disguise as an attribute self.objtype = 'attribute' @@ -1576,6 +1674,7 @@ class InstanceAttributeDocumenter(AttributeDocumenter): return True def add_content(self, more_content, no_docstring=False): + # type: (Any, bool) -> None """Never try to get a docstring from the object.""" AttributeDocumenter.add_content(self, more_content, no_docstring=True) @@ -1596,10 +1695,10 @@ class AutoDirective(Directive): attributes of the parents. """ # a registry of objtype -> documenter class - _registry = {} + _registry = {} # type: Dict[unicode, Type[Documenter]] # a registry of type -> getattr function - _special_attrgetters = {} + _special_attrgetters = {} # type: Dict[Type, Callable] # flags that can be given in autodoc_default_flags _default_flags = set([ @@ -1617,21 +1716,24 @@ class AutoDirective(Directive): option_spec = DefDict(identity) def warn(self, msg): + # type: (unicode) -> None self.warnings.append(self.reporter.warning(msg, line=self.lineno)) def run(self): - self.filename_set = set() # a set of dependent filenames + # type: () -> List[nodes.Node] + self.filename_set = set() # type: Set[unicode] + # a set of dependent filenames self.reporter = self.state.document.reporter self.env = self.state.document.settings.env - self.warnings = [] + self.warnings = [] # type: List[unicode] self.result = ViewList() try: source, lineno = self.reporter.get_source_and_line(self.lineno) except AttributeError: source = lineno = None - self.env.app.debug('[autodoc] %s:%s: input:\n%s', - source, lineno, self.block_text) + logger.debug('[autodoc] %s:%s: input:\n%s', + source, lineno, self.block_text) # find out what documenter to call objtype = self.name[4:] @@ -1660,7 +1762,7 @@ class AutoDirective(Directive): if not self.result: return self.warnings - self.env.app.debug2('[autodoc] output:\n%s', '\n'.join(self.result)) + logger.debug('[autodoc] output:\n%s', '\n'.join(self.result)) # record all filenames as dependencies -- this will at least # partially make automatic invalidation possible @@ -1687,6 +1789,7 @@ class AutoDirective(Directive): def add_documenter(cls): + # type: (Type[Documenter]) -> None """Register a new Documenter.""" if not issubclass(cls, Documenter): raise ExtensionError('autodoc documenter %r must be a subclass ' @@ -1699,6 +1802,7 @@ def add_documenter(cls): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_autodocumenter(ModuleDocumenter) app.add_autodocumenter(ClassDocumenter) app.add_autodocumenter(ExceptionDocumenter) diff --git a/sphinx/ext/autosectionlabel.py b/sphinx/ext/autosectionlabel.py index be769eb85..d45ba66a6 100644 --- a/sphinx/ext/autosectionlabel.py +++ b/sphinx/ext/autosectionlabel.py @@ -10,8 +10,11 @@ """ from docutils import nodes +from sphinx.util import logging from sphinx.util.nodes import clean_astext +logger = logging.getLogger(__name__) + def register_sections_as_label(app, document): labels = app.env.domaindata['std']['labels'] @@ -23,8 +26,9 @@ def register_sections_as_label(app, document): sectname = clean_astext(node[0]) if name in labels: - app.env.warn_node('duplicate label %s, ' % name + 'other instance ' - 'in ' + app.env.doc2path(labels[name][0]), node) + logger.warning('duplicate label %s, ' % name + 'other instance ' + 'in ' + app.env.doc2path(labels[name][0]), + location=node) anonlabels[name] = docname, labelid labels[name] = docname, labelid, sectname diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 030fec301..89fdbe522 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -62,17 +62,27 @@ from six import string_types from types import ModuleType from six import text_type -from docutils.parsers.rst import directives + +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList from docutils import nodes import sphinx from sphinx import addnodes -from sphinx.util import import_object, rst -from sphinx.util.compat import Directive +from sphinx.util import import_object, rst, logging from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.ext.autodoc import Options +if False: + # For type annotation + from typing import Any, Tuple, Type, Union # NOQA + from docutils.utils import Inliner # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.environment import BuildEnvironment # NOQA + from sphinx.ext.autodoc import Documenter # NOQA + +logger = logging.getLogger(__name__) + # -- autosummary_toc node ------------------------------------------------------ @@ -81,6 +91,7 @@ class autosummary_toc(nodes.comment): def process_autosummary_toc(app, doctree): + # type: (Sphinx, nodes.Node) -> None """Insert items described in autosummary:: to the TOC tree, but do not generate the toctree:: list. """ @@ -105,11 +116,13 @@ def process_autosummary_toc(app, doctree): def autosummary_toc_visit_html(self, node): + # type: (nodes.NodeVisitor, autosummary_toc) -> None """Hide autosummary toctree list in HTML output.""" raise nodes.SkipNode def autosummary_noop(self, node): + # type: (nodes.NodeVisitor, nodes.Node) -> None pass @@ -120,6 +133,7 @@ class autosummary_table(nodes.comment): def autosummary_table_visit_html(self, node): + # type: (nodes.NodeVisitor, autosummary_table) -> None """Make the first column of the table non-breaking.""" try: tbody = node[0][0][-1] @@ -138,11 +152,12 @@ def autosummary_table_visit_html(self, node): # -- autodoc integration ------------------------------------------------------- class FakeDirective(object): - env = {} + env = {} # type: Dict genopt = Options() def get_documenter(obj, parent): + # type: (Any, Any) -> Type[Documenter] """Get an autodoc.Documenter class suitable for documenting the given object. @@ -198,13 +213,15 @@ class Autosummary(Directive): } def warn(self, msg): + # type: (unicode) -> None self.warnings.append(self.state.document.reporter.warning( msg, line=self.lineno)) def run(self): + # type: () -> List[nodes.Node] self.env = env = self.state.document.settings.env self.genopt = Options() - self.warnings = [] + self.warnings = [] # type: List[nodes.Node] self.result = ViewList() names = [x.strip().split()[0] for x in self.content @@ -237,6 +254,7 @@ class Autosummary(Directive): return self.warnings + nodes def get_items(self, names): + # type: (List[unicode]) -> List[Tuple[unicode, unicode, unicode, unicode]] """Try to import the given names, and return a list of ``[(name, signature, summary_string, real_name), ...]``. """ @@ -244,7 +262,7 @@ class Autosummary(Directive): prefixes = get_import_prefixes_from_env(env) - items = [] + items = [] # type: List[Tuple[unicode, unicode, unicode, unicode]] max_item_chars = 50 @@ -289,8 +307,7 @@ class Autosummary(Directive): # be cached anyway) documenter.analyzer.find_attr_docs() except PycodeError as err: - documenter.env.app.debug( - '[autodoc] module analyzer failed: %s', err) + logger.debug('[autodoc] module analyzer failed: %s', err) # no source file -- e.g. for builtin and C modules documenter.analyzer = None @@ -334,6 +351,7 @@ class Autosummary(Directive): return items def get_table(self, items): + # type: (List[Tuple[unicode, unicode, unicode, unicode]]) -> List[Union[addnodes.tabular_col_spec, autosummary_table]] # NOQA """Generate a proper list of table nodes for autosummary:: directive. *items* is a list produced by :meth:`get_items`. @@ -352,6 +370,7 @@ class Autosummary(Directive): group.append(body) def append_row(*column_texts): + # type: (unicode) -> None row = nodes.row('') for text in column_texts: node = nodes.paragraph('') @@ -369,7 +388,7 @@ class Autosummary(Directive): for name, sig, summary, real_name in items: qualifier = 'obj' if 'nosignatures' not in self.options: - col1 = ':%s:`%s <%s>`\ %s' % (qualifier, name, real_name, rst.escape(sig)) + col1 = ':%s:`%s <%s>`\ %s' % (qualifier, name, real_name, rst.escape(sig)) # type: unicode # NOQA else: col1 = ':%s:`%s <%s>`' % (qualifier, name, real_name) col2 = summary @@ -379,6 +398,7 @@ class Autosummary(Directive): def mangle_signature(sig, max_chars=30): + # type: (unicode, int) -> unicode """Reformat a function signature to a more compact form.""" s = re.sub(r"^\((.*)\)$", r"\1", sig).strip() @@ -388,12 +408,12 @@ def mangle_signature(sig, max_chars=30): s = re.sub(r"'[^']*'", "", s) # Parse the signature to arguments + options - args = [] - opts = [] + args = [] # type: List[unicode] + opts = [] # type: List[unicode] opt_re = re.compile(r"^(.*, |)([a-zA-Z0-9_*]+)=") while s: - m = opt_re.search(s) + m = opt_re.search(s) # type: ignore if not m: # The rest are arguments args = s.split(', ') @@ -415,6 +435,7 @@ def mangle_signature(sig, max_chars=30): def limited_join(sep, items, max_chars=30, overflow_marker="..."): + # type: (unicode, List[unicode], int, unicode) -> unicode """Join a number of strings to one, limiting the length to *max_chars*. If the string overflows this limit, replace the last fitting item by @@ -441,11 +462,12 @@ def limited_join(sep, items, max_chars=30, overflow_marker="..."): # -- Importing items ----------------------------------------------------------- def get_import_prefixes_from_env(env): + # type: (BuildEnvironment) -> List """ Obtain current Python import prefixes (for `import_by_name`) from ``document.env`` """ - prefixes = [None] + prefixes = [None] # type: List currmodule = env.ref_context.get('py:module') if currmodule: @@ -462,6 +484,7 @@ def get_import_prefixes_from_env(env): def import_by_name(name, prefixes=[None]): + # type: (unicode, List) -> Tuple[unicode, Any, Any, unicode] """Import a Python object that has the given *name*, under one of the *prefixes*. The first name that succeeds is used. """ @@ -480,6 +503,7 @@ def import_by_name(name, prefixes=[None]): def _import_by_name(name): + # type: (str) -> Tuple[Any, Any, unicode] """Import a Python object given its full name.""" try: name_parts = name.split('.') @@ -524,6 +548,7 @@ def _import_by_name(name): def autolink_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]): + # type: (unicode, unicode, unicode, int, Inliner, Dict, List[unicode]) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA """Smart linking role. Expands to ':obj:`text`' if `text` is an object that can be imported; @@ -539,21 +564,24 @@ def autolink_role(typ, rawtext, etext, lineno, inliner, name, obj, parent, modname = import_by_name(pnode['reftarget'], prefixes) except ImportError: content = pnode[0] - r[0][0] = nodes.emphasis(rawtext, content[0].astext(), - classes=content['classes']) + r[0][0] = nodes.emphasis(rawtext, content[0].astext(), # type: ignore + classes=content['classes']) # type: ignore return r def get_rst_suffix(app): + # type: (Sphinx) -> unicode def get_supported_format(suffix): + # type: (unicode) -> Tuple[unicode] parser_class = app.config.source_parsers.get(suffix) if parser_class is None: return ('restructuredtext',) if isinstance(parser_class, string_types): - parser_class = import_object(parser_class, 'source parser') + parser_class = import_object(parser_class, 'source parser') # type: ignore return parser_class.supported - for suffix in app.config.source_suffix: + suffix = None # type: unicode + for suffix in app.config.source_suffix: # type: ignore if 'restructuredtext' in get_supported_format(suffix): return suffix @@ -561,6 +589,7 @@ def get_rst_suffix(app): def process_generate_options(app): + # type: (Sphinx) -> None genfiles = app.config.autosummary_generate if genfiles and not hasattr(genfiles, '__len__'): @@ -579,16 +608,17 @@ def process_generate_options(app): suffix = get_rst_suffix(app) if suffix is None: - app.warn('autosummary generats .rst files internally. ' - 'But your source_suffix does not contain .rst. Skipped.') + logger.warning('autosummary generats .rst files internally. ' + 'But your source_suffix does not contain .rst. Skipped.') return generate_autosummary_docs(genfiles, builder=app.builder, - warn=app.warn, info=app.info, suffix=suffix, - base_path=app.srcdir) + warn=logger.warning, info=logger.info, + suffix=suffix, base_path=app.srcdir) def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] # I need autodoc app.setup_extension('sphinx.ext.autodoc') app.add_node(autosummary_toc, diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 8495da7b4..cf57d3ea2 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -49,8 +49,16 @@ add_documenter(MethodDocumenter) add_documenter(AttributeDocumenter) add_documenter(InstanceAttributeDocumenter) +if False: + # For type annotation + from typing import Any, Callable, Tuple, List # NOQA + from sphinx import addnodes # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + def main(argv=sys.argv): + # type: (List[str]) -> None usage = """%prog [OPTIONS] SOURCEFILE ...""" p = optparse.OptionParser(usage.strip()) p.add_option("-o", "--output-dir", action="store", type="string", @@ -62,6 +70,9 @@ def main(argv=sys.argv): p.add_option("-t", "--templates", action="store", type="string", dest="templates", default=None, help="Custom template directory (default: %default)") + p.add_option("-i", "--imported-members", action="store_true", + dest="imported_members", default=False, + help="Document imported members (default: %default)") options, args = p.parse_args(argv[1:]) if len(args) < 1: @@ -69,14 +80,17 @@ def main(argv=sys.argv): generate_autosummary_docs(args, options.output_dir, "." + options.suffix, - template_dir=options.templates) + template_dir=options.templates, + imported_members=options.imported_members) def _simple_info(msg): + # type: (unicode) -> None print(msg) def _simple_warn(msg): + # type: (unicode) -> None print('WARNING: ' + msg, file=sys.stderr) @@ -84,7 +98,9 @@ def _simple_warn(msg): def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', warn=_simple_warn, info=_simple_info, - base_path=None, builder=None, template_dir=None): + base_path=None, builder=None, template_dir=None, + imported_members=False): + # type: (List[unicode], unicode, unicode, Callable, Callable, unicode, Builder, unicode, bool) -> None # NOQA showed_sources = list(sorted(sources)) if len(showed_sources) > 20: @@ -99,6 +115,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', sources = [os.path.join(base_path, filename) for filename in sources] # create our own templating environment + template_dirs = None # type: List[unicode] template_dirs = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')] if builder is not None: @@ -153,36 +170,38 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', except TemplateNotFound: template = template_env.get_template('autosummary/base.rst') - def get_members(obj, typ, include_public=[]): - items = [] + def get_members(obj, typ, include_public=[], imported=False): + # type: (Any, unicode, List[unicode], bool) -> Tuple[List[unicode], List[unicode]] # NOQA + items = [] # type: List[unicode] for name in dir(obj): try: - documenter = get_documenter(safe_getattr(obj, name), - obj) + value = safe_getattr(obj, name) except AttributeError: continue + documenter = get_documenter(value, obj) if documenter.objtype == typ: - items.append(name) + if imported or getattr(value, '__module__', None) == obj.__name__: + items.append(name) public = [x for x in items if x in include_public or not x.startswith('_')] return public, items - ns = {} + ns = {} # type: Dict[unicode, Any] if doc.objtype == 'module': ns['members'] = dir(obj) ns['functions'], ns['all_functions'] = \ - get_members(obj, 'function') + get_members(obj, 'function', imported=imported_members) ns['classes'], ns['all_classes'] = \ - get_members(obj, 'class') + get_members(obj, 'class', imported=imported_members) ns['exceptions'], ns['all_exceptions'] = \ - get_members(obj, 'exception') + get_members(obj, 'exception', imported=imported_members) elif doc.objtype == 'class': ns['members'] = dir(obj) ns['methods'], ns['all_methods'] = \ - get_members(obj, 'method', ['__init__']) + get_members(obj, 'method', ['__init__'], imported=imported_members) ns['attributes'], ns['all_attributes'] = \ - get_members(obj, 'attribute') + get_members(obj, 'attribute', imported=imported_members) parts = name.split('.') if doc.objtype in ('method', 'attribute'): @@ -215,21 +234,23 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', # -- Finding documented entries in files --------------------------------------- def find_autosummary_in_files(filenames): + # type: (List[unicode]) -> List[Tuple[unicode, unicode, unicode]] """Find out what items are documented in source/*.rst. See `find_autosummary_in_lines`. """ - documented = [] + documented = [] # type: List[Tuple[unicode, unicode, unicode]] for filename in filenames: - with codecs.open(filename, 'r', encoding='utf-8', + with codecs.open(filename, 'r', encoding='utf-8', # type: ignore errors='ignore') as f: lines = f.read().splitlines() - documented.extend(find_autosummary_in_lines(lines, + documented.extend(find_autosummary_in_lines(lines, # type: ignore filename=filename)) return documented def find_autosummary_in_docstring(name, module=None, filename=None): + # type: (unicode, Any, unicode) -> List[Tuple[unicode, unicode, unicode]] """Find out what items are documented in the given object's docstring. See `find_autosummary_in_lines`. @@ -249,6 +270,7 @@ def find_autosummary_in_docstring(name, module=None, filename=None): def find_autosummary_in_lines(lines, module=None, filename=None): + # type: (List[unicode], Any, unicode) -> List[Tuple[unicode, unicode, unicode]] """Find out what items appear in autosummary:: directives in the given lines. @@ -268,9 +290,9 @@ def find_autosummary_in_lines(lines, module=None, filename=None): toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$') - documented = [] + documented = [] # type: List[Tuple[unicode, unicode, unicode]] - toctree = None + toctree = None # type: unicode template = None current_module = module in_autosummary = False @@ -278,7 +300,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): for line in lines: if in_autosummary: - m = toctree_arg_re.match(line) + m = toctree_arg_re.match(line) # type: ignore if m: toctree = m.group(1) if filename: @@ -286,7 +308,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): toctree) continue - m = template_arg_re.match(line) + m = template_arg_re.match(line) # type: ignore if m: template = m.group(1).strip() continue @@ -294,7 +316,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): if line.strip().startswith(':'): continue # skip options - m = autosummary_item_re.match(line) + m = autosummary_item_re.match(line) # type: ignore if m: name = m.group(1).strip() if name.startswith('~'): @@ -310,7 +332,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): in_autosummary = False - m = autosummary_re.match(line) + m = autosummary_re.match(line) # type: ignore if m: in_autosummary = True base_indent = m.group(1) @@ -318,7 +340,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): template = None continue - m = automodule_re.search(line) + m = automodule_re.search(line) # type: ignore if m: current_module = m.group(1).strip() # recurse into the automodule docstring @@ -326,7 +348,7 @@ def find_autosummary_in_lines(lines, module=None, filename=None): current_module, filename=filename)) continue - m = module_re.match(line) + m = module_re.match(line) # type: ignore if m: current_module = m.group(2) continue diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py index c08b1e706..1698f936b 100644 --- a/sphinx/ext/coverage.py +++ b/sphinx/ext/coverage.py @@ -20,22 +20,32 @@ from six.moves import cPickle as pickle import sphinx from sphinx.builders import Builder +from sphinx.util import logging from sphinx.util.inspect import safe_getattr +if False: + # For type annotation + from typing import Any, Callable, IO, Pattern, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + +logger = logging.getLogger(__name__) + # utility def write_header(f, text, char='-'): + # type:(IO, unicode, unicode) -> None f.write(text + '\n') f.write(char * len(text) + '\n') -def compile_regex_list(name, exps, warnfunc): +def compile_regex_list(name, exps): + # type: (unicode, unicode) -> List[Pattern] lst = [] for exp in exps: try: lst.append(re.compile(exp)) except Exception: - warnfunc('invalid regex %r in %s' % (exp, name)) + logger.warning('invalid regex %r in %s', exp, name) return lst @@ -44,45 +54,46 @@ class CoverageBuilder(Builder): name = 'coverage' def init(self): - self.c_sourcefiles = [] + # type: () -> None + self.c_sourcefiles = [] # type: List[unicode] for pattern in self.config.coverage_c_path: pattern = path.join(self.srcdir, pattern) self.c_sourcefiles.extend(glob.glob(pattern)) - self.c_regexes = [] + self.c_regexes = [] # type: List[Tuple[unicode, Pattern]] for (name, exp) in self.config.coverage_c_regexes.items(): try: self.c_regexes.append((name, re.compile(exp))) except Exception: - self.warn('invalid regex %r in coverage_c_regexes' % exp) + logger.warning('invalid regex %r in coverage_c_regexes', exp) - self.c_ignorexps = {} + self.c_ignorexps = {} # type: Dict[unicode, List[Pattern]] for (name, exps) in iteritems(self.config.coverage_ignore_c_items): - self.c_ignorexps[name] = compile_regex_list( - 'coverage_ignore_c_items', exps, self.warn) - self.mod_ignorexps = compile_regex_list( - 'coverage_ignore_modules', self.config.coverage_ignore_modules, - self.warn) - self.cls_ignorexps = compile_regex_list( - 'coverage_ignore_classes', self.config.coverage_ignore_classes, - self.warn) - self.fun_ignorexps = compile_regex_list( - 'coverage_ignore_functions', self.config.coverage_ignore_functions, - self.warn) + self.c_ignorexps[name] = compile_regex_list('coverage_ignore_c_items', + exps) + self.mod_ignorexps = compile_regex_list('coverage_ignore_modules', + self.config.coverage_ignore_modules) + self.cls_ignorexps = compile_regex_list('coverage_ignore_classes', + self.config.coverage_ignore_classes) + self.fun_ignorexps = compile_regex_list('coverage_ignore_functions', + self.config.coverage_ignore_functions) def get_outdated_docs(self): + # type: () -> unicode return 'coverage overview' def write(self, *ignored): - self.py_undoc = {} + # type: (Any) -> None + self.py_undoc = {} # type: Dict[unicode, Dict[unicode, Any]] self.build_py_coverage() self.write_py_coverage() - self.c_undoc = {} + self.c_undoc = {} # type: Dict[unicode, Set[Tuple[unicode, unicode]]] self.build_c_coverage() self.write_c_coverage() def build_c_coverage(self): + # type: () -> None # Fetch all the info from the header files c_objects = self.env.domaindata['c']['objects'] for filename in self.c_sourcefiles: @@ -94,7 +105,7 @@ class CoverageBuilder(Builder): if match: name = match.groups()[0] if name not in c_objects: - for exp in self.c_ignorexps.get(key, ()): + for exp in self.c_ignorexps.get(key, []): if exp.match(name): break else: @@ -104,6 +115,7 @@ class CoverageBuilder(Builder): self.c_undoc[filename] = undoc def write_c_coverage(self): + # type: () -> None output_file = path.join(self.outdir, 'c.txt') with open(output_file, 'w') as op: if self.config.coverage_write_headline: @@ -117,6 +129,7 @@ class CoverageBuilder(Builder): op.write('\n') def build_py_coverage(self): + # type: () -> None objects = self.env.domaindata['py']['objects'] modules = self.env.domaindata['py']['modules'] @@ -134,13 +147,12 @@ class CoverageBuilder(Builder): try: mod = __import__(mod_name, fromlist=['foo']) except ImportError as err: - self.warn('module %s could not be imported: %s' % - (mod_name, err)) + logger.warning('module %s could not be imported: %s', mod_name, err) self.py_undoc[mod_name] = {'error': err} continue funcs = [] - classes = {} + classes = {} # type: Dict[unicode, List[unicode]] for name, obj in inspect.getmembers(mod): # diverse module attributes are ignored: @@ -177,7 +189,7 @@ class CoverageBuilder(Builder): classes[name] = [] continue - attrs = [] + attrs = [] # type: List[unicode] for attr_name in dir(obj): if attr_name not in obj.__dict__: @@ -207,6 +219,7 @@ class CoverageBuilder(Builder): self.py_undoc[mod_name] = {'funcs': funcs, 'classes': classes} def write_py_coverage(self): + # type: () -> None output_file = path.join(self.outdir, 'python.txt') failed = [] with open(output_file, 'w') as op: @@ -242,6 +255,7 @@ class CoverageBuilder(Builder): op.writelines(' * %s -- %s\n' % x for x in failed) def finish(self): + # type: () -> None # dump the coverage data to a pickle file too picklepath = path.join(self.outdir, 'undoc.pickle') with open(picklepath, 'wb') as dumpfile: @@ -249,6 +263,7 @@ class CoverageBuilder(Builder): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(CoverageBuilder) app.add_config_value('coverage_ignore_modules', [], False) app.add_config_value('coverage_ignore_functions', [], False) diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index 244762b69..dafe2863e 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -19,22 +19,30 @@ from os import path import doctest from six import itervalues, StringIO, binary_type, text_type, PY2 + from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives import sphinx from sphinx.builders import Builder -from sphinx.util import force_decode +from sphinx.util import force_decode, logging from sphinx.util.nodes import set_source_info -from sphinx.util.compat import Directive -from sphinx.util.console import bold +from sphinx.util.console import bold # type: ignore from sphinx.util.osutil import fs_encoding +if False: + # For type annotation + from typing import Any, Callable, IO, Iterable, Sequence, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + +logger = logging.getLogger(__name__) + blankline_re = re.compile(r'^\s*<BLANKLINE>', re.MULTILINE) doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE) if PY2: def doctest_encode(text, encoding): + # type: (str, unicode) -> unicode if isinstance(text, text_type): text = text.encode(encoding) if text.startswith(codecs.BOM_UTF8): @@ -42,6 +50,7 @@ if PY2: return text else: def doctest_encode(text, encoding): + # type: (unicode, unicode) -> unicode return text @@ -58,6 +67,7 @@ class TestDirective(Directive): final_argument_whitespace = True def run(self): + # type: () -> List[nodes.Node] # use ordinary docutils nodes for test code: they get special attributes # so that our builder recognizes them, and the other builders are happy. code = '\n'.join(self.content) @@ -92,20 +102,20 @@ class TestDirective(Directive): option_strings = self.options['options'].replace(',', ' ').split() for option in option_strings: if (option[0] not in '+-' or option[1:] not in - doctest.OPTIONFLAGS_BY_NAME): + doctest.OPTIONFLAGS_BY_NAME): # type: ignore # XXX warn? continue - flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] + flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] # type: ignore node['options'][flag] = (option[0] == '+') return [node] class TestsetupDirective(TestDirective): - option_spec = {} + option_spec = {} # type: Dict class TestcleanupDirective(TestDirective): - option_spec = {} + option_spec = {} # type: Dict class DoctestDirective(TestDirective): @@ -128,19 +138,21 @@ class TestoutputDirective(TestDirective): } -parser = doctest.DocTestParser() +parser = doctest.DocTestParser() # type: ignore # helper classes class TestGroup(object): def __init__(self, name): + # type: (unicode) -> None self.name = name - self.setup = [] - self.tests = [] - self.cleanup = [] + self.setup = [] # type: List[TestCode] + self.tests = [] # type: List[List[TestCode]] + self.cleanup = [] # type: List[TestCode] def add_code(self, code, prepend=False): + # type: (TestCode, bool) -> None if code.type == 'testsetup': if prepend: self.setup.insert(0, code) @@ -158,30 +170,34 @@ class TestGroup(object): else: raise RuntimeError('invalid TestCode type') - def __repr__(self): + def __repr__(self): # type: ignore + # type: () -> unicode return 'TestGroup(name=%r, setup=%r, cleanup=%r, tests=%r)' % ( self.name, self.setup, self.cleanup, self.tests) class TestCode(object): def __init__(self, code, type, lineno, options=None): + # type: (unicode, unicode, int, Dict) -> None self.code = code self.type = type self.lineno = lineno self.options = options or {} - def __repr__(self): + def __repr__(self): # type: ignore + # type: () -> unicode return 'TestCode(%r, %r, %r, options=%r)' % ( self.code, self.type, self.lineno, self.options) -class SphinxDocTestRunner(doctest.DocTestRunner): +class SphinxDocTestRunner(doctest.DocTestRunner): # type: ignore def summarize(self, out, verbose=None): + # type: (Callable, bool) -> Tuple[int, int] string_io = StringIO() old_stdout = sys.stdout sys.stdout = string_io try: - res = doctest.DocTestRunner.summarize(self, verbose) + res = doctest.DocTestRunner.summarize(self, verbose) # type: ignore finally: sys.stdout = old_stdout out(string_io.getvalue()) @@ -189,6 +205,7 @@ class SphinxDocTestRunner(doctest.DocTestRunner): def _DocTestRunner__patched_linecache_getlines(self, filename, module_globals=None): + # type: (unicode, Any) -> Any # this is overridden from DocTestRunner adding the try-except below m = self._DocTestRunner__LINECACHE_FILENAME_RE.match(filename) if m and m.group('name') == self.test.name: @@ -213,6 +230,7 @@ class DocTestBuilder(Builder): name = 'doctest' def init(self): + # type: () -> None # default options self.opt = self.config.doctest_default_flags @@ -221,7 +239,7 @@ class DocTestBuilder(Builder): # for doctest examples but unusable for multi-statement code such # as setup code -- to be able to use doctest error reporting with # that code nevertheless, we monkey-patch the "compile" it uses. - doctest.compile = self.compile + doctest.compile = self.compile # type: ignore sys.path[0:0] = self.config.doctest_path @@ -236,7 +254,8 @@ class DocTestBuilder(Builder): date = time.strftime('%Y-%m-%d %H:%M:%S') - self.outfile = codecs.open(path.join(self.outdir, 'output.txt'), + self.outfile = None # type: IO + self.outfile = codecs.open(path.join(self.outdir, 'output.txt'), # type: ignore 'w', encoding='utf-8') self.outfile.write('''\ Results of doctest builder run on %s @@ -244,27 +263,33 @@ Results of doctest builder run on %s ''' % (date, '='*len(date))) def _out(self, text): - self.info(text, nonl=True) + # type: (unicode) -> None + logger.info(text, nonl=True) self.outfile.write(text) def _warn_out(self, text): + # type: (unicode) -> None if self.app.quiet or self.app.warningiserror: - self.warn(text) + logger.warning(text) else: - self.info(text, nonl=True) + logger.info(text, nonl=True) if isinstance(text, binary_type): text = force_decode(text, None) self.outfile.write(text) def get_target_uri(self, docname, typ=None): + # type: (unicode, unicode) -> unicode return '' def get_outdated_docs(self): + # type: () -> Set[unicode] return self.env.found_docs def finish(self): + # type: () -> None # write executive summary def s(v): + # type: (int) -> unicode return v != 1 and 's' or '' repl = (self.total_tries, s(self.total_tries), self.total_failures, s(self.total_failures), @@ -284,17 +309,19 @@ Doctest summary self.app.statuscode = 1 def write(self, build_docnames, updated_docnames, method='update'): + # type: (Iterable[unicode], Sequence[unicode], unicode) -> None if build_docnames is None: build_docnames = sorted(self.env.all_docs) - self.info(bold('running tests...')) + logger.info(bold('running tests...')) for docname in build_docnames: # no need to resolve the doctree doctree = self.env.get_doctree(docname) self.test_doc(docname, doctree) def test_doc(self, docname, doctree): - groups = {} + # type: (unicode, nodes.Node) -> None + groups = {} # type: Dict[unicode, TestGroup] add_to_all_groups = [] self.setup_runner = SphinxDocTestRunner(verbose=False, optionflags=self.opt) @@ -308,19 +335,21 @@ Doctest summary if self.config.doctest_test_doctest_blocks: def condition(node): + # type: (nodes.Node) -> bool return (isinstance(node, (nodes.literal_block, nodes.comment)) and 'testnodetype' in node) or \ isinstance(node, nodes.doctest_block) else: def condition(node): + # type: (nodes.Node) -> bool return isinstance(node, (nodes.literal_block, nodes.comment)) \ and 'testnodetype' in node for node in doctree.traverse(condition): source = 'test' in node and node['test'] or node.astext() if not source: - self.warn('no code/output in %s block at %s:%s' % - (node.get('testnodetype', 'doctest'), - self.env.doc2path(docname), node.line)) + logger.warning('no code/output in %s block at %s:%s', + node.get('testnodetype', 'doctest'), + self.env.doc2path(docname), node.line) code = TestCode(source, type=node.get('testnodetype', 'doctest'), lineno=node.line, options=node.get('options')) node_groups = node.get('groups', ['default']) @@ -366,26 +395,29 @@ Doctest summary self.cleanup_tries += res_t def compile(self, code, name, type, flags, dont_inherit): + # type: (unicode, unicode, unicode, Any, bool) -> Any return compile(code, name, self.type, flags, dont_inherit) def test_group(self, group, filename): + # type: (TestGroup, unicode) -> None if PY2: filename_str = filename.encode(fs_encoding) else: filename_str = filename - ns = {} + ns = {} # type: Dict def run_setup_cleanup(runner, testcodes, what): + # type: (Any, List[TestCode], Any) -> bool examples = [] for testcode in testcodes: - examples.append(doctest.Example( - doctest_encode(testcode.code, self.env.config.source_encoding), '', + examples.append(doctest.Example( # type: ignore + doctest_encode(testcode.code, self.env.config.source_encoding), '', # type: ignore # NOQA lineno=testcode.lineno)) if not examples: return True # simulate a doctest with the code - sim_doctest = doctest.DocTest(examples, {}, + sim_doctest = doctest.DocTest(examples, {}, # type: ignore '%s (%s code)' % (group.name, what), filename_str, 0, None) sim_doctest.globs = ns @@ -407,12 +439,11 @@ Doctest summary # ordinary doctests (code/output interleaved) try: test = parser.get_doctest( - doctest_encode(code[0].code, self.env.config.source_encoding), {}, + doctest_encode(code[0].code, self.env.config.source_encoding), {}, # type: ignore # NOQA group.name, filename_str, code[0].lineno) except Exception: - self.warn('ignoring invalid doctest code: %r' % - code[0].code, - '%s:%s' % (filename, code[0].lineno)) + logger.warning('ignoring invalid doctest code: %r', code[0].code, + location=(filename, code[0].lineno)) continue if not test.examples: continue @@ -427,19 +458,19 @@ Doctest summary output = code[1] and code[1].code or '' options = code[1] and code[1].options or {} # disable <BLANKLINE> processing as it is not needed - options[doctest.DONT_ACCEPT_BLANKLINE] = True + options[doctest.DONT_ACCEPT_BLANKLINE] = True # type: ignore # find out if we're testing an exception m = parser._EXCEPTION_RE.match(output) if m: exc_msg = m.group('msg') else: exc_msg = None - example = doctest.Example( - doctest_encode(code[0].code, self.env.config.source_encoding), output, + example = doctest.Example( # type: ignore + doctest_encode(code[0].code, self.env.config.source_encoding), output, # type: ignore # NOQA exc_msg=exc_msg, lineno=code[0].lineno, options=options) - test = doctest.DocTest([example], {}, group.name, + test = doctest.DocTest([example], {}, group.name, # type: ignore filename_str, code[0].lineno, None) self.type = 'exec' # multiple statements again # DocTest.__init__ copies the globs namespace, which we don't want @@ -452,6 +483,7 @@ Doctest summary def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_directive('testsetup', TestsetupDirective) app.add_directive('testcleanup', TestcleanupDirective) app.add_directive('doctest', DoctestDirective) @@ -465,6 +497,6 @@ def setup(app): app.add_config_value('doctest_global_cleanup', '', False) app.add_config_value( 'doctest_default_flags', - doctest.DONT_ACCEPT_TRUE_FOR_1 | doctest.ELLIPSIS | doctest.IGNORE_EXCEPTION_DETAIL, + doctest.DONT_ACCEPT_TRUE_FOR_1 | doctest.ELLIPSIS | doctest.IGNORE_EXCEPTION_DETAIL, # type: ignore # NOQA False) return {'version': sphinx.__display_version__, 'parallel_read_safe': True} diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index 5e76eb8ba..7df115ea0 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -18,16 +18,24 @@ from subprocess import Popen, PIPE from hashlib import sha1 from six import text_type + from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList import sphinx from sphinx.errors import SphinxError from sphinx.locale import _ +from sphinx.util import logging from sphinx.util.i18n import search_image_for_language from sphinx.util.osutil import ensuredir, ENOENT, EPIPE, EINVAL -from sphinx.util.compat import Directive + +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + +logger = logging.getLogger(__name__) mapname_re = re.compile(r'<map id="(.*?)"') @@ -42,6 +50,7 @@ class graphviz(nodes.General, nodes.Inline, nodes.Element): def figure_wrapper(directive, node, caption): + # type: (Directive, nodes.Node, unicode) -> nodes.figure figure_node = nodes.figure('', node) if 'align' in node: figure_node['align'] = node.attributes.pop('align') @@ -58,6 +67,7 @@ def figure_wrapper(directive, node, caption): def align_spec(argument): + # type: (Any) -> bool return directives.choice(argument, ('left', 'center', 'right')) @@ -72,12 +82,13 @@ class Graphviz(Directive): option_spec = { 'alt': directives.unchanged, 'align': align_spec, - 'inline': directives.flag, 'caption': directives.unchanged, 'graphviz_dot': directives.unchanged, + 'name': directives.unchanged, } def run(self): + # type: () -> List[nodes.Node] if self.arguments: document = self.state.document if self.content: @@ -110,13 +121,12 @@ class Graphviz(Directive): node['alt'] = self.options['alt'] if 'align' in self.options: node['align'] = self.options['align'] - if 'inline' in self.options: - node['inline'] = True caption = self.options.get('caption') if caption: node = figure_wrapper(self, node, caption) + self.add_name(node) return [node] @@ -131,12 +141,13 @@ class GraphvizSimple(Directive): option_spec = { 'alt': directives.unchanged, 'align': align_spec, - 'inline': directives.flag, 'caption': directives.unchanged, 'graphviz_dot': directives.unchanged, + 'name': directives.unchanged, } def run(self): + # type: () -> List[nodes.Node] node = graphviz() node['code'] = '%s %s {\n%s\n}\n' % \ (self.name, self.arguments[0], '\n'.join(self.content)) @@ -147,17 +158,17 @@ class GraphvizSimple(Directive): node['alt'] = self.options['alt'] if 'align' in self.options: node['align'] = self.options['align'] - if 'inline' in self.options: - node['inline'] = True caption = self.options.get('caption') if caption: node = figure_wrapper(self, node, caption) + self.add_name(node) return [node] def render_dot(self, code, options, format, prefix='graphviz'): + # type: (nodes.NodeVisitor, unicode, Dict, unicode, unicode) -> Tuple[unicode, unicode] """Render graphviz code into a PNG or PDF output file.""" graphviz_dot = options.get('graphviz_dot', self.builder.config.graphviz_dot) hashkey = (code + str(options) + str(graphviz_dot) + @@ -190,8 +201,8 @@ def render_dot(self, code, options, format, prefix='graphviz'): except OSError as err: if err.errno != ENOENT: # No such file or directory raise - self.builder.warn('dot command %r cannot be run (needed for graphviz ' - 'output), check the graphviz_dot setting' % graphviz_dot) + logger.warning('dot command %r cannot be run (needed for graphviz ' + 'output), check the graphviz_dot setting', graphviz_dot) if not hasattr(self.builder, '_graphviz_warned_dot'): self.builder._graphviz_warned_dot = {} self.builder._graphviz_warned_dot[graphviz_dot] = True @@ -216,17 +227,9 @@ def render_dot(self, code, options, format, prefix='graphviz'): return relfn, outfn -def warn_for_deprecated_option(self, node): - if hasattr(self.builder, '_graphviz_warned_inline'): - return - - if 'inline' in node: - self.builder.warn(':inline: option for graphviz is deprecated since version 1.4.0.') - self.builder._graphviz_warned_inline = True - - def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None, alt=None): + # type: (nodes.NodeVisitor, graphviz, unicode, Dict, unicode, unicode, unicode) -> Tuple[unicode, unicode] # NOQA format = self.builder.config.graphviz_output_format try: if format not in ('png', 'svg'): @@ -234,7 +237,7 @@ def render_dot_html(self, node, code, options, prefix='graphviz', "'svg', but is %r" % format) fname, outfn = render_dot(self, code, options, format, prefix) except GraphvizError as exc: - self.builder.warn('dot code %r: ' % code + str(exc)) + logger.warning('dot code %r: ' % code + str(exc)) raise nodes.SkipNode if fname is None: @@ -259,7 +262,7 @@ def render_dot_html(self, node, code, options, prefix='graphviz', (fname, alt, imgcss)) else: # has a map: get the name of the map and connect the parts - mapname = mapname_re.match(imgmap[0].decode('utf-8')).group(1) + mapname = mapname_re.match(imgmap[0].decode('utf-8')).group(1) # type: ignore self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>\n' % (fname, alt, mapname, imgcss)) self.body.extend([item.decode('utf-8') for item in imgmap]) @@ -270,15 +273,16 @@ def render_dot_html(self, node, code, options, prefix='graphviz', def html_visit_graphviz(self, node): - warn_for_deprecated_option(self, node) + # type: (nodes.NodeVisitor, graphviz) -> None render_dot_html(self, node, node['code'], node['options']) def render_dot_latex(self, node, code, options, prefix='graphviz'): + # type: (nodes.NodeVisitor, graphviz, unicode, Dict, unicode) -> None try: fname, outfn = render_dot(self, code, options, 'pdf', prefix) except GraphvizError as exc: - self.builder.warn('dot code %r: ' % code + str(exc)) + logger.warning('dot code %r: ' % code + str(exc)) raise nodes.SkipNode is_inline = self.is_inline(node) @@ -288,7 +292,7 @@ def render_dot_latex(self, node, code, options, prefix='graphviz'): para_separator = '\n' if fname is not None: - post = None + post = None # type: unicode if not is_inline and 'align' in node: if node['align'] == 'left': self.body.append('{') @@ -305,15 +309,16 @@ def render_dot_latex(self, node, code, options, prefix='graphviz'): def latex_visit_graphviz(self, node): - warn_for_deprecated_option(self, node) + # type: (nodes.NodeVisitor, graphviz) -> None render_dot_latex(self, node, node['code'], node['options']) def render_dot_texinfo(self, node, code, options, prefix='graphviz'): + # type: (nodes.NodeVisitor, graphviz, unicode, Dict, unicode) -> None try: fname, outfn = render_dot(self, code, options, 'png', prefix) except GraphvizError as exc: - self.builder.warn('dot code %r: ' % code + str(exc)) + logger.warning('dot code %r: ' % code + str(exc)) raise nodes.SkipNode if fname is not None: self.body.append('@image{%s,,,[graphviz],png}\n' % fname[:-4]) @@ -321,12 +326,12 @@ def render_dot_texinfo(self, node, code, options, prefix='graphviz'): def texinfo_visit_graphviz(self, node): - warn_for_deprecated_option(self, node) + # type: (nodes.NodeVisitor, graphviz) -> None render_dot_texinfo(self, node, node['code'], node['options']) def text_visit_graphviz(self, node): - warn_for_deprecated_option(self, node) + # type: (nodes.NodeVisitor, graphviz) -> None if 'alt' in node.attributes: self.add_text(_('[graph: %s]') % node['alt']) else: @@ -335,7 +340,7 @@ def text_visit_graphviz(self, node): def man_visit_graphviz(self, node): - warn_for_deprecated_option(self, node) + # type: (nodes.NodeVisitor, graphviz) -> None if 'alt' in node.attributes: self.body.append(_('[graph: %s]') % node['alt']) else: @@ -344,6 +349,7 @@ def man_visit_graphviz(self, node): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_node(graphviz, html=(html_visit_graphviz, None), latex=(latex_visit_graphviz, None), diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index 74580fb4a..18504d94e 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -21,10 +21,15 @@ """ from docutils import nodes +from docutils.parsers.rst import Directive import sphinx from sphinx.util.nodes import set_source_info -from sphinx.util.compat import Directive + +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA class ifconfig(nodes.Element): @@ -37,9 +42,10 @@ class IfConfig(Directive): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[nodes.Node] node = ifconfig() node.document = self.state.document set_source_info(self, node) @@ -50,16 +56,17 @@ class IfConfig(Directive): def process_ifconfig_nodes(app, doctree, docname): + # type: (Sphinx, nodes.Node, unicode) -> None ns = dict((k, app.config[k]) for k in app.config.values) ns.update(app.config.__dict__.copy()) ns['builder'] = app.builder.name for node in doctree.traverse(ifconfig): try: - res = eval(node['expr'], ns) + res = eval(node['expr'], ns) # type: ignore except Exception as err: # handle exceptions in a clean fashion from traceback import format_exception_only - msg = ''.join(format_exception_only(err.__class__, err)) + msg = ''.join(format_exception_only(err.__class__, err)) # type: ignore newnode = doctree.reporter.error('Exception occured in ' 'ifconfig expression: \n%s' % msg, base_node=node) @@ -72,6 +79,7 @@ def process_ifconfig_nodes(app, doctree, docname): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_node(ifconfig) app.add_directive('ifconfig', IfConfig) app.connect('doctree-resolved', process_ifconfig_nodes) diff --git a/sphinx/ext/imgmath.py b/sphinx/ext/imgmath.py index c800eee65..e559530c3 100644 --- a/sphinx/ext/imgmath.py +++ b/sphinx/ext/imgmath.py @@ -19,21 +19,32 @@ from subprocess import Popen, PIPE from hashlib import sha1 from six import text_type + from docutils import nodes import sphinx from sphinx.locale import _ from sphinx.errors import SphinxError, ExtensionError +from sphinx.util import logging from sphinx.util.png import read_png_depth, write_png_depth from sphinx.util.osutil import ensuredir, ENOENT, cd from sphinx.util.pycompat import sys_encoding from sphinx.ext.mathbase import setup_math as mathbase_setup, wrap_displaymath +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.ext.mathbase import math as math_node, displaymath # NOQA + +logger = logging.getLogger(__name__) + class MathExtError(SphinxError): category = 'Math extension error' def __init__(self, msg, stderr=None, stdout=None): + # type: (unicode, unicode, unicode) -> None if stderr: msg += '\n[stderr]\n' + stderr.decode(sys_encoding, 'replace') if stdout: @@ -72,6 +83,7 @@ depth_re = re.compile(br'\[\d+ depth=(-?\d+)\]') def render_math(self, math): + # type: (nodes.NodeVisitor, unicode) -> Tuple[unicode, int] """Render the LaTeX math expression *math* using latex and dvipng or dvisvgm. @@ -116,9 +128,8 @@ def render_math(self, math): else: tempdir = self.builder._imgmath_tempdir - tf = codecs.open(path.join(tempdir, 'math.tex'), 'w', 'utf-8') - tf.write(latex) - tf.close() + with codecs.open(path.join(tempdir, 'math.tex'), 'w', 'utf-8') as tf: # type: ignore + tf.write(latex) # build latex command; old versions of latex don't have the # --output-directory option, so we have to manually chdir to the @@ -134,9 +145,9 @@ def render_math(self, math): except OSError as err: if err.errno != ENOENT: # No such file or directory raise - self.builder.warn('LaTeX command %r cannot be run (needed for math ' - 'display), check the imgmath_latex setting' % - self.builder.config.imgmath_latex) + logger.warning('LaTeX command %r cannot be run (needed for math ' + 'display), check the imgmath_latex setting', + self.builder.config.imgmath_latex) self.builder._imgmath_warned_latex = True return None, None @@ -175,10 +186,10 @@ def render_math(self, math): except OSError as err: if err.errno != ENOENT: # No such file or directory raise - self.builder.warn('%s command %r cannot be run (needed for math ' - 'display), check the imgmath_%s setting' % - (image_translator, image_translator_executable, - image_translator)) + logger.warning('%s command %r cannot be run (needed for math ' + 'display), check the imgmath_%s setting', + image_translator, image_translator_executable, + image_translator) self.builder._imgmath_warned_image_translator = True return None, None @@ -199,23 +210,26 @@ def render_math(self, math): def cleanup_tempdir(app, exc): + # type: (Sphinx, Exception) -> None if exc: return if not hasattr(app.builder, '_imgmath_tempdir'): return try: - shutil.rmtree(app.builder._mathpng_tempdir) + shutil.rmtree(app.builder._mathpng_tempdir) # type: ignore except Exception: pass def get_tooltip(self, node): + # type: (nodes.NodeVisitor, math_node) -> unicode if self.builder.config.imgmath_add_tooltips: return ' alt="%s"' % self.encode(node['latex']).strip() return '' def html_visit_math(self, node): + # type: (nodes.NodeVisitor, math_node) -> None try: fname, depth = render_math(self, '$'+node['latex']+'$') except MathExtError as exc: @@ -223,7 +237,7 @@ def html_visit_math(self, node): sm = nodes.system_message(msg, type='WARNING', level=2, backrefs=[], source=node['latex']) sm.walkabout(self) - self.builder.warn('display latex %r: ' % node['latex'] + msg) + logger.warning('display latex %r: %s', node['latex'], msg) raise nodes.SkipNode if fname is None: # something failed -- use text-only as a bad substitute @@ -238,6 +252,7 @@ def html_visit_math(self, node): def html_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None if node['nowrap']: latex = node['latex'] else: @@ -250,7 +265,7 @@ def html_visit_displaymath(self, node): sm = nodes.system_message(msg, type='WARNING', level=2, backrefs=[], source=node['latex']) sm.walkabout(self) - self.builder.warn('inline latex %r: ' % node['latex'] + msg) + logger.warning('inline latex %r: %s', node['latex'], msg) raise nodes.SkipNode self.body.append(self.starttag(node, 'div', CLASS='math')) self.body.append('<p>') @@ -269,6 +284,7 @@ def html_visit_displaymath(self, node): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] try: mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None)) except ExtensionError: diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py index e4c9223ec..3b23c845a 100644 --- a/sphinx/ext/inheritance_diagram.py +++ b/sphinx/ext/inheritance_diagram.py @@ -42,20 +42,25 @@ import inspect try: from hashlib import md5 except ImportError: - from md5 import md5 + from md5 import md5 # type: ignore from six import text_type -from six.moves import builtins +from six.moves import builtins # type: ignore from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives import sphinx from sphinx.ext.graphviz import render_dot_html, render_dot_latex, \ render_dot_texinfo, figure_wrapper from sphinx.pycode import ModuleAnalyzer from sphinx.util import force_decode -from sphinx.util.compat import Directive + +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.environment import BuildEnvironment # NOQA module_sig_re = re.compile(r'''^(?:([\w.]*)\.)? # module names @@ -64,6 +69,7 @@ module_sig_re = re.compile(r'''^(?:([\w.]*)\.)? # module names def try_import(objname): + # type: (unicode) -> Any """Import a object or module using *name* and *currentmodule*. *name* should be a relative name from *currentmodule* or a fully-qualified name. @@ -72,9 +78,9 @@ def try_import(objname): """ try: __import__(objname) - return sys.modules.get(objname) + return sys.modules.get(objname) # type: ignore except ImportError: - modname, attrname = module_sig_re.match(objname).groups() + modname, attrname = module_sig_re.match(objname).groups() # type: ignore if modname is None: return None try: @@ -85,6 +91,7 @@ def try_import(objname): def import_classes(name, currmodule): + # type: (unicode, unicode) -> Any """Import a class using its fully-qualified *name*.""" target = None @@ -127,6 +134,7 @@ class InheritanceGraph(object): """ def __init__(self, class_names, currmodule, show_builtins=False, private_bases=False, parts=0): + # type: (unicode, str, bool, bool, int) -> None """*class_names* is a list of child classes to show bases from. If *show_builtins* is True, then Python builtins will be shown @@ -141,13 +149,15 @@ class InheritanceGraph(object): 'inheritance diagram') def _import_classes(self, class_names, currmodule): + # type: (unicode, str) -> List[Any] """Import a list of classes.""" - classes = [] + classes = [] # type: List[Any] for name in class_names: classes.extend(import_classes(name, currmodule)) return classes def _class_info(self, classes, show_builtins, private_bases, parts): + # type: (List[Any], bool, bool, int) -> List[Tuple[unicode, unicode, List[unicode], unicode]] # NOQA """Return name and bases for all classes that are ancestors of *classes*. @@ -158,6 +168,7 @@ class InheritanceGraph(object): py_builtins = vars(builtins).values() def recurse(cls): + # type: (Any) -> None if not show_builtins and cls in py_builtins: return if not private_bases and cls.__name__.startswith('_'): @@ -179,7 +190,7 @@ class InheritanceGraph(object): except Exception: # might raise AttributeError for strange classes pass - baselist = [] + baselist = [] # type: List[unicode] all_classes[cls] = (nodename, fullname, baselist, tooltip) for base in cls.__bases__: if not show_builtins and base in py_builtins: @@ -196,6 +207,7 @@ class InheritanceGraph(object): return list(all_classes.values()) def class_name(self, cls, parts=0): + # type: (Any, int) -> unicode """Given a class object, return a fully-qualified name. This works for things I've tested in matplotlib so far, but may not be @@ -212,8 +224,9 @@ class InheritanceGraph(object): return '.'.join(name_parts[-parts:]) def get_all_class_names(self): + # type: () -> List[unicode] """Get all of the class names involved in the graph.""" - return [fullname for (_, fullname, _, _) in self.class_info] + return [fullname for (_, fullname, _, _) in self.class_info] # type: ignore # These are the default attrs for graphviz default_graph_attrs = { @@ -234,13 +247,16 @@ class InheritanceGraph(object): } def _format_node_attrs(self, attrs): + # type: (Dict) -> unicode return ','.join(['%s=%s' % x for x in sorted(attrs.items())]) def _format_graph_attrs(self, attrs): + # type: (Dict) -> unicode return ''.join(['%s=%s;\n' % x for x in sorted(attrs.items())]) def generate_dot(self, name, urls={}, env=None, graph_attrs={}, node_attrs={}, edge_attrs={}): + # type: (unicode, Dict, BuildEnvironment, Dict, Dict, Dict) -> unicode """Generate a graphviz dot graph from the classes that were passed in to __init__. @@ -262,7 +278,7 @@ class InheritanceGraph(object): n_attrs.update(env.config.inheritance_node_attrs) e_attrs.update(env.config.inheritance_edge_attrs) - res = [] + res = [] # type: List[unicode] res.append('digraph %s {\n' % name) res.append(self._format_graph_attrs(g_attrs)) @@ -308,6 +324,7 @@ class InheritanceDiagram(Directive): } def run(self): + # type: () -> List[nodes.Node] node = inheritance_diagram() node.document = self.state.document env = self.state.document.settings.env @@ -347,11 +364,13 @@ class InheritanceDiagram(Directive): def get_graph_hash(node): + # type: (inheritance_diagram) -> unicode encoded = (node['content'] + str(node['parts'])).encode('utf-8') return md5(encoded).hexdigest()[-10:] def html_visit_inheritance_diagram(self, node): + # type: (nodes.NodeVisitor, inheritance_diagram) -> None """ Output the graph for HTML. This will insert a PNG with clickable image map. @@ -384,6 +403,7 @@ def html_visit_inheritance_diagram(self, node): def latex_visit_inheritance_diagram(self, node): + # type: (nodes.NodeVisitor, inheritance_diagram) -> None """ Output the graph for LaTeX. This will insert a PDF. """ @@ -399,6 +419,7 @@ def latex_visit_inheritance_diagram(self, node): def texinfo_visit_inheritance_diagram(self, node): + # type: (nodes.NodeVisitor, inheritance_diagram) -> None """ Output the graph for Texinfo. This will insert a PNG. """ @@ -414,10 +435,12 @@ def texinfo_visit_inheritance_diagram(self, node): def skip(self, node): + # type: (nodes.NodeVisitor, inheritance_diagram) -> None raise nodes.SkipNode def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.setup_extension('sphinx.ext.graphviz') app.add_node( inheritance_diagram, diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 7513323ef..af39722ce 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -33,23 +33,38 @@ import posixpath from os import path import re -from six import iteritems, string_types +from six import PY3, iteritems, string_types from six.moves.urllib.parse import urlsplit, urlunsplit + from docutils import nodes from docutils.utils import relative_path import sphinx from sphinx.locale import _ from sphinx.builders.html import INVENTORY_FILENAME -from sphinx.util import requests +from sphinx.util import requests, logging + +if False: + # For type annotation + from typing import Any, Callable, Dict, IO, Iterator, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.config import Config # NOQA + from sphinx.environment import BuildEnvironment # NOQA + + if PY3: + unicode = str + Inventory = Dict[unicode, Dict[unicode, Tuple[unicode, unicode, unicode, unicode]]] + +logger = logging.getLogger(__name__) UTF8StreamReader = codecs.lookup('utf-8')[2] def read_inventory_v1(f, uri, join): + # type: (IO, unicode, Callable) -> Inventory f = UTF8StreamReader(f) - invdata = {} + invdata = {} # type: Inventory line = next(f) projname = line.rstrip()[11:] line = next(f) @@ -69,7 +84,8 @@ def read_inventory_v1(f, uri, join): def read_inventory_v2(f, uri, join, bufsize=16*1024): - invdata = {} + # type: (IO, unicode, Callable, int) -> Inventory + invdata = {} # type: Inventory line = f.readline() projname = line.rstrip()[11:].decode('utf-8') line = f.readline() @@ -79,12 +95,14 @@ def read_inventory_v2(f, uri, join, bufsize=16*1024): raise ValueError def read_chunks(): + # type: () -> Iterator[bytes] decompressor = zlib.decompressobj() for chunk in iter(lambda: f.read(bufsize), b''): yield decompressor.decompress(chunk) yield decompressor.flush() def split_lines(iter): + # type: (Iterator[bytes]) -> Iterator[unicode] buf = b'' for chunk in iter: buf += chunk @@ -117,6 +135,7 @@ def read_inventory_v2(f, uri, join, bufsize=16*1024): def read_inventory(f, uri, join, bufsize=16*1024): + # type: (IO, unicode, Callable, int) -> Inventory line = f.readline().rstrip().decode('utf-8') if line == '# Sphinx inventory version 1': return read_inventory_v1(f, uri, join) @@ -125,6 +144,7 @@ def read_inventory(f, uri, join, bufsize=16*1024): def _strip_basic_auth(url): + # type: (unicode) -> unicode """Returns *url* with basic auth credentials removed. Also returns the basic auth username and password if they're present in *url*. @@ -146,6 +166,7 @@ def _strip_basic_auth(url): def _read_from_url(url, config=None): + # type: (unicode, Config) -> IO """Reads data from *url* with an HTTP *GET*. This function supports fetching from resources which use basic HTTP auth as @@ -168,6 +189,7 @@ def _read_from_url(url, config=None): def _get_safe_url(url): + # type: (unicode) -> unicode """Gets version of *url* with basic auth passwords obscured. This function returns results suitable for printing and logging. @@ -193,6 +215,7 @@ def _get_safe_url(url): def fetch_inventory(app, uri, inv): + # type: (Sphinx, unicode, Any) -> Any """Fetch, parse and return an intersphinx inventory file.""" # both *uri* (base URI of the links to generate) and *inv* (actual # location of the inventory file) can be local or remote URIs @@ -206,14 +229,14 @@ def fetch_inventory(app, uri, inv): else: f = open(path.join(app.srcdir, inv), 'rb') except Exception as err: - app.warn('intersphinx inventory %r not fetchable due to ' - '%s: %s' % (inv, err.__class__, err)) + logger.warning('intersphinx inventory %r not fetchable due to %s: %s', + inv, err.__class__, err) return try: if hasattr(f, 'url'): - newinv = f.url + newinv = f.url # type: ignore if inv != newinv: - app.info('intersphinx inventory has moved: %s -> %s' % (inv, newinv)) + logger.info('intersphinx inventory has moved: %s -> %s', inv, newinv) if uri in (inv, path.dirname(inv), path.dirname(inv) + '/'): uri = path.dirname(newinv) @@ -224,29 +247,34 @@ def fetch_inventory(app, uri, inv): except ValueError as exc: raise ValueError('unknown or unsupported inventory version: %r' % exc) except Exception as err: - app.warn('intersphinx inventory %r not readable due to ' - '%s: %s' % (inv, err.__class__.__name__, err)) + logger.warning('intersphinx inventory %r not readable due to %s: %s', + inv, err.__class__.__name__, err) else: return invdata def load_mappings(app): + # type: (Sphinx) -> None """Load all intersphinx mappings into the environment.""" now = int(time.time()) cache_time = now - app.config.intersphinx_cache_limit * 86400 env = app.builder.env if not hasattr(env, 'intersphinx_cache'): - env.intersphinx_cache = {} - env.intersphinx_inventory = {} - env.intersphinx_named_inventory = {} - cache = env.intersphinx_cache + env.intersphinx_cache = {} # type: ignore + env.intersphinx_inventory = {} # type: ignore + env.intersphinx_named_inventory = {} # type: ignore + cache = env.intersphinx_cache # type: ignore update = False for key, value in iteritems(app.config.intersphinx_mapping): + name = None # type: unicode + uri = None # type: unicode + inv = None # type: Union[unicode, Tuple[unicode, ...]] + if isinstance(value, (list, tuple)): # new format - name, (uri, inv) = key, value + name, (uri, inv) = key, value # type: ignore if not isinstance(name, string_types): - app.warn('intersphinx identifier %r is not string. Ignored' % name) + logger.warning('intersphinx identifier %r is not string. Ignored', name) continue else: # old format, no name @@ -257,7 +285,7 @@ def load_mappings(app): if not isinstance(inv, tuple): invs = (inv, ) else: - invs = inv + invs = inv # type: ignore for inv in invs: if not inv: @@ -266,9 +294,8 @@ def load_mappings(app): # files; remote ones only if the cache time is expired if '://' not in inv or uri not in cache \ or cache[uri][1] < cache_time: - safe_inv_url = _get_safe_url(inv) - app.info( - 'loading intersphinx inventory from %s...' % safe_inv_url) + safe_inv_url = _get_safe_url(inv) # type: ignore + logger.info('loading intersphinx inventory from %s...', safe_inv_url) invdata = fetch_inventory(app, uri, inv) if invdata: cache[uri] = (name, now, invdata) @@ -276,8 +303,8 @@ def load_mappings(app): break if update: - env.intersphinx_inventory = {} - env.intersphinx_named_inventory = {} + env.intersphinx_inventory = {} # type: ignore + env.intersphinx_named_inventory = {} # type: ignore # Duplicate values in different inventories will shadow each # other; which one will override which can vary between builds # since they are specified using an unordered dict. To make @@ -290,15 +317,17 @@ def load_mappings(app): unnamed_vals = [v for v in cached_vals if not v[0]] for name, _x, invdata in named_vals + unnamed_vals: if name: - env.intersphinx_named_inventory[name] = invdata + env.intersphinx_named_inventory[name] = invdata # type: ignore for type, objects in iteritems(invdata): - env.intersphinx_inventory.setdefault( + env.intersphinx_inventory.setdefault( # type: ignore type, {}).update(objects) def missing_reference(app, env, node, contnode): + # type: (Sphinx, BuildEnvironment, nodes.Node, nodes.Node) -> None """Attempt to resolve a missing reference via intersphinx references.""" target = node['reftarget'] + objtypes = None # type: List[unicode] if node['reftype'] == 'any': # we search anything! objtypes = ['%s:%s' % (domain.name, objtype) @@ -313,18 +342,18 @@ def missing_reference(app, env, node, contnode): if not domain: # only objects in domains are in the inventory return - objtypes = env.domains[domain].objtypes_for_role(node['reftype']) + objtypes = env.get_domain(domain).objtypes_for_role(node['reftype']) if not objtypes: return objtypes = ['%s:%s' % (domain, objtype) for objtype in objtypes] - to_try = [(env.intersphinx_inventory, target)] + to_try = [(env.intersphinx_inventory, target)] # type: ignore in_set = None if ':' in target: # first part may be the foreign doc set name setname, newtarget = target.split(':', 1) - if setname in env.intersphinx_named_inventory: + if setname in env.intersphinx_named_inventory: # type: ignore in_set = setname - to_try.append((env.intersphinx_named_inventory[setname], newtarget)) + to_try.append((env.intersphinx_named_inventory[setname], newtarget)) # type: ignore # NOQA for inventory, target in to_try: for objtype in objtypes: if objtype not in inventory or target not in inventory[objtype]: @@ -358,6 +387,7 @@ def missing_reference(app, env, node, contnode): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_config_value('intersphinx_mapping', {}, True) app.add_config_value('intersphinx_cache_limit', 5, False) app.add_config_value('intersphinx_timeout', None, False) @@ -377,7 +407,7 @@ if __name__ == '__main__': print(msg, file=sys.stderr) filename = sys.argv[1] - invdata = fetch_inventory(MockApp(), '', filename) + invdata = fetch_inventory(MockApp(), '', filename) # type: ignore for key in sorted(invdata or {}): print(key) for entry, einfo in sorted(invdata[key].items()): diff --git a/sphinx/ext/linkcode.py b/sphinx/ext/linkcode.py index 63bd38727..a9693299e 100644 --- a/sphinx/ext/linkcode.py +++ b/sphinx/ext/linkcode.py @@ -16,12 +16,18 @@ from sphinx import addnodes from sphinx.locale import _ from sphinx.errors import SphinxError +if False: + # For type annotation + from typing import Any # NOQA + from sphinx.application import Sphinx # NOQA + class LinkcodeError(SphinxError): category = "linkcode error" def doctree_read(app, doctree): + # type: (Sphinx, nodes.Node) -> None env = app.builder.env resolve_target = getattr(env.config, 'linkcode_resolve', None) @@ -38,7 +44,7 @@ def doctree_read(app, doctree): for objnode in doctree.traverse(addnodes.desc): domain = objnode.get('domain') - uris = set() + uris = set() # type: Set[unicode] for signode in objnode: if not isinstance(signode, addnodes.desc_signature): continue @@ -72,6 +78,7 @@ def doctree_read(app, doctree): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.connect('doctree-read', doctree_read) app.add_config_value('linkcode_resolve', None, '') return {'version': sphinx.__display_version__, 'parallel_read_safe': True} diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index ae4b439b7..4e12f62f7 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -10,13 +10,20 @@ """ from docutils import nodes, utils -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from sphinx.roles import XRefRole from sphinx.locale import _ from sphinx.domains import Domain from sphinx.util.nodes import make_refnode, set_source_info -from sphinx.util.compat import Directive + +if False: + # For type annotation + from typing import Any, Callable, Iterable, Tuple # NOQA + from docutils.parsers.rst.states import Inliner # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA class math(nodes.Inline, nodes.TextElement): @@ -33,6 +40,7 @@ class eqref(nodes.Inline, nodes.TextElement): class EqXRefRole(XRefRole): def result_nodes(self, document, env, node, is_ref): + # type: (nodes.Node, BuildEnvironment, nodes.Node, bool) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA node['refdomain'] = 'math' return [node], [] @@ -44,22 +52,25 @@ class MathDomain(Domain): initial_data = { 'objects': {}, # labelid -> (docname, eqno) - } + } # type: Dict[unicode, Dict[unicode, Tuple[unicode, int]]] dangling_warnings = { 'eq': 'equation not found: %(target)s', } def clear_doc(self, docname): + # type: (unicode) -> None for labelid, (doc, eqno) in list(self.data['objects'].items()): if doc == docname: del self.data['objects'][labelid] def merge_domaindata(self, docnames, otherdata): + # type: (Iterable[unicode], Dict) -> None for labelid, (doc, eqno) in otherdata['objects'].items(): if doc in docnames: self.data['objects'][labelid] = doc def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA assert typ == 'eq' docname, number = self.data['objects'].get(target, (None, None)) if docname: @@ -76,6 +87,7 @@ class MathDomain(Domain): return None def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + # type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] # NOQA refnode = self.resolve_xref(env, fromdocname, builder, 'eq', target, node, contnode) if refnode is None: return [] @@ -83,9 +95,11 @@ class MathDomain(Domain): return [refnode] def get_objects(self): + # type: () -> List return [] def add_equation(self, env, docname, labelid): + # type: (BuildEnvironment, unicode, unicode) -> int equations = self.data['objects'] if labelid in equations: path = env.doc2path(equations[labelid][0]) @@ -97,12 +111,15 @@ class MathDomain(Domain): return eqno def get_next_equation_number(self, docname): + # type: (unicode) -> int targets = [eq for eq in self.data['objects'].values() if eq[0] == docname] return len(targets) + 1 def wrap_displaymath(math, label, numbering): + # type: (unicode, unicode, bool) -> unicode def is_equation(part): + # type: (unicode) -> unicode return part.strip() if label is None: @@ -137,11 +154,13 @@ def wrap_displaymath(math, label, numbering): def math_role(role, rawtext, text, lineno, inliner, options={}, content=[]): + # type: (unicode, unicode, unicode, int, Inliner, Dict, List[unicode]) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA latex = utils.unescape(text, restore_backslashes=True) return [math(latex=latex)], [] def is_in_section_title(node): + # type: (nodes.Node) -> bool """Determine whether the node is in a section title""" from sphinx.util.nodes import traverse_parent @@ -165,6 +184,7 @@ class MathDirective(Directive): } def run(self): + # type: () -> List[nodes.Node] latex = '\n'.join(self.content) if self.arguments and self.arguments[0]: latex = self.arguments[0] + '\n\n' + latex @@ -186,6 +206,7 @@ class MathDirective(Directive): return ret def add_target(self, ret): + # type: (List[nodes.Node]) -> None node = ret[0] env = self.state.document.settings.env @@ -213,6 +234,7 @@ class MathDirective(Directive): def latex_visit_math(self, node): + # type: (nodes.NodeVisitor, math) -> None if is_in_section_title(node): protect = r'\protect' else: @@ -223,6 +245,7 @@ def latex_visit_math(self, node): def latex_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None if not node['label']: label = None else: @@ -239,17 +262,20 @@ def latex_visit_displaymath(self, node): def latex_visit_eqref(self, node): + # type: (nodes.NodeVisitor, eqref) -> None label = "equation:%s:%s" % (node['docname'], node['target']) self.body.append('\\eqref{%s}' % label) raise nodes.SkipNode def text_visit_math(self, node): + # type: (nodes.NodeVisitor, math) -> None self.add_text(node['latex']) raise nodes.SkipNode def text_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None self.new_state() self.add_text(node['latex']) self.end_state() @@ -257,24 +283,29 @@ def text_visit_displaymath(self, node): def man_visit_math(self, node): + # type: (nodes.NodeVisitor, math) -> None self.body.append(node['latex']) raise nodes.SkipNode def man_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None self.visit_centered(node) def man_depart_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None self.depart_centered(node) def texinfo_visit_math(self, node): + # type: (nodes.NodeVisitor, math) -> None self.body.append('@math{' + self.escape_arg(node['latex']) + '}') raise nodes.SkipNode def texinfo_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None if node.get('label'): self.add_anchor(node['label'], node) self.body.append('\n\n@example\n%s\n@end example\n\n' % @@ -282,10 +313,12 @@ def texinfo_visit_displaymath(self, node): def texinfo_depart_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None pass def setup_math(app, htmlinlinevisitors, htmldisplayvisitors): + # type: (Sphinx, Tuple[Callable, Any], Tuple[Callable, Any]) -> None app.add_config_value('math_number_all', False, 'env') app.add_domain(MathDomain) app.add_node(math, override=True, diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index 651355c57..f6fccac7d 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -14,8 +14,13 @@ import sys from six import PY2, iteritems import sphinx +from sphinx.application import Sphinx from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring +if False: + # For type annotation + from typing import Any # NOQA + class Config(object): """Sphinx napoleon extension settings in `conf.py`. @@ -254,6 +259,7 @@ class Config(object): } def __init__(self, **settings): + # type: (Any) -> None for name, (default, rebuild) in iteritems(self._config_values): setattr(self, name, default) for name, value in iteritems(settings): @@ -261,6 +267,7 @@ class Config(object): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] """Sphinx extension setup function. When the extension is loaded, Sphinx imports this module and executes @@ -282,9 +289,9 @@ def setup(app): `The Extension API <http://sphinx-doc.org/extdev/appapi.html>`_ """ - from sphinx.application import Sphinx if not isinstance(app, Sphinx): - return # probably called by tests + return # type: ignore + # probably called by tests _patch_python_domain() @@ -297,13 +304,14 @@ def setup(app): def _patch_python_domain(): + # type: () -> None try: from sphinx.domains.python import PyTypedField except ImportError: pass else: import sphinx.domains.python - import sphinx.locale + import sphinx.locale # type: ignore l_ = sphinx.locale.lazy_gettext for doc_field in sphinx.domains.python.PyObject.doc_field_types: if doc_field.name == 'parameter': @@ -317,6 +325,7 @@ def _patch_python_domain(): def _process_docstring(app, what, name, obj, options, lines): + # type: (Sphinx, unicode, unicode, Any, Any, List[unicode]) -> None """Process the docstring for a given python object. Called when autodoc has read and processed a docstring. `lines` is a list @@ -353,6 +362,7 @@ def _process_docstring(app, what, name, obj, options, lines): """ result_lines = lines + docstring = None # type: GoogleDocstring if app.config.napoleon_numpy_docstring: docstring = NumpyDocstring(result_lines, app.config, app, what, name, obj, options) @@ -365,6 +375,7 @@ def _process_docstring(app, what, name, obj, options, lines): def _skip_member(app, what, name, obj, skip, options): + # type: (Sphinx, unicode, unicode, Any, bool, Any) -> bool """Determine if private and special class members are included in docs. The following settings in conf.py determine if private and special class @@ -453,4 +464,4 @@ def _skip_member(app, what, name, obj, skip, options): (is_private and inc_private) or (is_init and inc_init)): return False - return skip + return None diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index ef9ff1627..6fee87b34 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -21,6 +21,12 @@ from six.moves import range from sphinx.ext.napoleon.iterators import modify_iter from sphinx.util.pycompat import UnicodeMixin +if False: + # For type annotation + from typing import Any, Callable, Tuple, Union # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.config import Config as SphinxConfig # NOQA + _directive_regex = re.compile(r'\.\. \S+::') _google_section_regex = re.compile(r'^(\s|\w)+:\s*$') @@ -99,19 +105,20 @@ class GoogleDocstring(UnicodeMixin): """ def __init__(self, docstring, config=None, app=None, what='', name='', obj=None, options=None): + # type: (Union[unicode, List[unicode]], SphinxConfig, Sphinx, unicode, unicode, Any, Any) -> None # NOQA self._config = config self._app = app if not self._config: from sphinx.ext.napoleon import Config - self._config = self._app and self._app.config or Config() + self._config = self._app and self._app.config or Config() # type: ignore if not what: if inspect.isclass(obj): what = 'class' elif inspect.ismodule(obj): what = 'module' - elif isinstance(obj, collections.Callable): + elif isinstance(obj, collections.Callable): # type: ignore what = 'function' else: what = 'object' @@ -121,14 +128,14 @@ class GoogleDocstring(UnicodeMixin): self._obj = obj self._opt = options if isinstance(docstring, string_types): - docstring = docstring.splitlines() + docstring = docstring.splitlines() # type: ignore self._lines = docstring self._line_iter = modify_iter(docstring, modifier=lambda s: s.rstrip()) - self._parsed_lines = [] + self._parsed_lines = [] # type: List[unicode] self._is_in_section = False self._section_indent = 0 if not hasattr(self, '_directive_sections'): - self._directive_sections = [] + self._directive_sections = [] # type: List[unicode] if not hasattr(self, '_sections'): self._sections = { 'args': self._parse_parameters_section, @@ -154,10 +161,11 @@ class GoogleDocstring(UnicodeMixin): 'warns': self._parse_warns_section, 'yield': self._parse_yields_section, 'yields': self._parse_yields_section, - } + } # type: Dict[unicode, Callable] self._parse() def __unicode__(self): + # type: () -> unicode """Return the parsed docstring in reStructuredText format. Returns @@ -169,6 +177,7 @@ class GoogleDocstring(UnicodeMixin): return u('\n').join(self.lines()) def lines(self): + # type: () -> List[unicode] """Return the parsed lines of the docstring in reStructuredText format. Returns @@ -180,38 +189,42 @@ class GoogleDocstring(UnicodeMixin): return self._parsed_lines def _consume_indented_block(self, indent=1): + # type: (int) -> List[unicode] lines = [] line = self._line_iter.peek() while(not self._is_section_break() and (not line or self._is_indented(line, indent))): - lines.append(next(self._line_iter)) + lines.append(next(self._line_iter)) # type: ignore line = self._line_iter.peek() return lines def _consume_contiguous(self): + # type: () -> List[unicode] lines = [] while (self._line_iter.has_next() and self._line_iter.peek() and not self._is_section_header()): - lines.append(next(self._line_iter)) + lines.append(next(self._line_iter)) # type: ignore return lines def _consume_empty(self): + # type: () -> List[unicode] lines = [] line = self._line_iter.peek() while self._line_iter.has_next() and not line: - lines.append(next(self._line_iter)) + lines.append(next(self._line_iter)) # type: ignore line = self._line_iter.peek() return lines def _consume_field(self, parse_type=True, prefer_type=False): - line = next(self._line_iter) + # type: (bool, bool) -> Tuple[unicode, unicode, List[unicode]] + line = next(self._line_iter) # type: ignore before, colon, after = self._partition_field_on_colon(line) - _name, _type, _desc = before, '', after + _name, _type, _desc = before, '', after # type: unicode, unicode, unicode if parse_type: - match = _google_typed_arg_regex.match(before) + match = _google_typed_arg_regex.match(before) # type: ignore if match: _name = match.group(1) _type = match.group(2) @@ -221,11 +234,12 @@ class GoogleDocstring(UnicodeMixin): if prefer_type and not _type: _type, _name = _name, _type indent = self._get_indent(line) + 1 - _desc = [_desc] + self._dedent(self._consume_indented_block(indent)) + _desc = [_desc] + self._dedent(self._consume_indented_block(indent)) # type: ignore _desc = self.__class__(_desc, self._config).lines() - return _name, _type, _desc + return _name, _type, _desc # type: ignore def _consume_fields(self, parse_type=True, prefer_type=False): + # type: (bool, bool) -> List[Tuple[unicode, unicode, List[unicode]]] self._consume_empty() fields = [] while not self._is_section_break(): @@ -235,19 +249,21 @@ class GoogleDocstring(UnicodeMixin): return fields def _consume_inline_attribute(self): - line = next(self._line_iter) + # type: () -> Tuple[unicode, List[unicode]] + line = next(self._line_iter) # type: ignore _type, colon, _desc = self._partition_field_on_colon(line) if not colon: _type, _desc = _desc, _type - _desc = [_desc] + self._dedent(self._consume_to_end()) + _desc = [_desc] + self._dedent(self._consume_to_end()) # type: ignore _desc = self.__class__(_desc, self._config).lines() - return _type, _desc + return _type, _desc # type: ignore def _consume_returns_section(self): + # type: () -> List[Tuple[unicode, unicode, List[unicode]]] lines = self._dedent(self._consume_to_next_section()) if lines: before, colon, after = self._partition_field_on_colon(lines[0]) - _name, _type, _desc = '', '', lines + _name, _type, _desc = '', '', lines # type: unicode, unicode, List[unicode] if colon: if after: @@ -263,30 +279,35 @@ class GoogleDocstring(UnicodeMixin): return [] def _consume_usage_section(self): + # type: () -> List[unicode] lines = self._dedent(self._consume_to_next_section()) return lines def _consume_section_header(self): - section = next(self._line_iter) + # type: () -> unicode + section = next(self._line_iter) # type: ignore stripped_section = section.strip(':') if stripped_section.lower() in self._sections: section = stripped_section return section def _consume_to_end(self): + # type: () -> List[unicode] lines = [] while self._line_iter.has_next(): - lines.append(next(self._line_iter)) + lines.append(next(self._line_iter)) # type: ignore return lines def _consume_to_next_section(self): + # type: () -> List[unicode] self._consume_empty() lines = [] while not self._is_section_break(): - lines.append(next(self._line_iter)) + lines.append(next(self._line_iter)) # type: ignore return lines + self._consume_empty() def _dedent(self, lines, full=False): + # type: (List[unicode], bool) -> List[unicode] if full: return [line.lstrip() for line in lines] else: @@ -294,6 +315,7 @@ class GoogleDocstring(UnicodeMixin): return [line[min_indent:] for line in lines] def _escape_args_and_kwargs(self, name): + # type: (unicode) -> unicode if name[:2] == '**': return r'\*\*' + name[2:] elif name[:1] == '*': @@ -302,29 +324,32 @@ class GoogleDocstring(UnicodeMixin): return name def _fix_field_desc(self, desc): + # type: (List[unicode]) -> List[unicode] if self._is_list(desc): - desc = [''] + desc + desc = [''] + desc # type: ignore elif desc[0].endswith('::'): desc_block = desc[1:] indent = self._get_indent(desc[0]) block_indent = self._get_initial_indent(desc_block) if block_indent > indent: - desc = [''] + desc + desc = [''] + desc # type: ignore else: desc = ['', desc[0]] + self._indent(desc_block, 4) return desc def _format_admonition(self, admonition, lines): + # type: (unicode, List[unicode]) -> List[unicode] lines = self._strip_empty(lines) if len(lines) == 1: return ['.. %s:: %s' % (admonition, lines[0].strip()), ''] elif lines: lines = self._indent(self._dedent(lines), 3) - return ['.. %s::' % admonition, ''] + lines + [''] + return ['.. %s::' % admonition, ''] + lines + [''] # type: ignore else: return ['.. %s::' % admonition, ''] def _format_block(self, prefix, lines, padding=None): + # type: (unicode, List[unicode], unicode) -> List[unicode] if lines: if padding is None: padding = ' ' * len(prefix) @@ -342,6 +367,7 @@ class GoogleDocstring(UnicodeMixin): def _format_docutils_params(self, fields, field_role='param', type_role='type'): + # type: (List[Tuple[unicode, unicode, List[unicode]]], unicode, unicode) -> List[unicode] # NOQA lines = [] for _name, _type, _desc in fields: _desc = self._strip_empty(_desc) @@ -357,13 +383,14 @@ class GoogleDocstring(UnicodeMixin): return lines + [''] def _format_field(self, _name, _type, _desc): + # type: (unicode, unicode, List[unicode]) -> List[unicode] _desc = self._strip_empty(_desc) has_desc = any(_desc) separator = has_desc and ' -- ' or '' if _name: if _type: if '`' in _type: - field = '**%s** (%s)%s' % (_name, _type, separator) + field = '**%s** (%s)%s' % (_name, _type, separator) # type: unicode else: field = '**%s** (*%s*)%s' % (_name, _type, separator) else: @@ -386,10 +413,11 @@ class GoogleDocstring(UnicodeMixin): return [field] def _format_fields(self, field_type, fields): + # type: (unicode, List[Tuple[unicode, unicode, List[unicode]]]) -> List[unicode] field_type = ':%s:' % field_type.strip() padding = ' ' * len(field_type) multi = len(fields) > 1 - lines = [] + lines = [] # type: List[unicode] for _name, _type, _desc in fields: field = self._format_field(_name, _type, _desc) if multi: @@ -404,6 +432,7 @@ class GoogleDocstring(UnicodeMixin): return lines def _get_current_indent(self, peek_ahead=0): + # type: (int) -> int line = self._line_iter.peek(peek_ahead + 1)[peek_ahead] while line != self._line_iter.sentinel: if line: @@ -413,18 +442,21 @@ class GoogleDocstring(UnicodeMixin): return 0 def _get_indent(self, line): + # type: (unicode) -> int for i, s in enumerate(line): if not s.isspace(): return i return len(line) def _get_initial_indent(self, lines): + # type: (List[unicode]) -> int for line in lines: if line: return self._get_indent(line) return 0 def _get_min_indent(self, lines): + # type: (List[unicode]) -> int min_indent = None for line in lines: if line: @@ -436,9 +468,11 @@ class GoogleDocstring(UnicodeMixin): return min_indent or 0 def _indent(self, lines, n=4): + # type: (List[unicode], int) -> List[unicode] return [(' ' * n) + line for line in lines] def _is_indented(self, line, indent=1): + # type: (unicode, int) -> bool for i, s in enumerate(line): if i >= indent: return True @@ -447,11 +481,12 @@ class GoogleDocstring(UnicodeMixin): return False def _is_list(self, lines): + # type: (List[unicode]) -> bool if not lines: return False - if _bullet_list_regex.match(lines[0]): + if _bullet_list_regex.match(lines[0]): # type: ignore return True - if _enumerated_list_regex.match(lines[0]): + if _enumerated_list_regex.match(lines[0]): # type: ignore return True if len(lines) < 2 or lines[0].endswith('::'): return False @@ -464,6 +499,7 @@ class GoogleDocstring(UnicodeMixin): return next_indent > indent def _is_section_header(self): + # type: () -> bool section = self._line_iter.peek().lower() match = _google_section_regex.match(section) if match and section.strip(':') in self._sections: @@ -478,6 +514,7 @@ class GoogleDocstring(UnicodeMixin): return False def _is_section_break(self): + # type: () -> bool line = self._line_iter.peek() return (not self._line_iter.has_next() or self._is_section_header() or @@ -486,6 +523,7 @@ class GoogleDocstring(UnicodeMixin): not self._is_indented(line, self._section_indent))) def _parse(self): + # type: () -> None self._parsed_lines = self._consume_empty() if self._name and (self._what == 'attribute' or self._what == 'data'): @@ -498,7 +536,7 @@ class GoogleDocstring(UnicodeMixin): section = self._consume_section_header() self._is_in_section = True self._section_indent = self._get_current_indent() - if _directive_regex.match(section): + if _directive_regex.match(section): # type: ignore lines = [section] + self._consume_to_next_section() else: lines = self._sections[section.lower()](section) @@ -513,42 +551,47 @@ class GoogleDocstring(UnicodeMixin): self._parsed_lines.extend(lines) def _parse_attribute_docstring(self): + # type: () -> List[unicode] _type, _desc = self._consume_inline_attribute() return self._format_field('', _type, _desc) def _parse_attributes_section(self, section): + # type: (unicode) -> List[unicode] lines = [] for _name, _type, _desc in self._consume_fields(): if self._config.napoleon_use_ivar: - field = ':ivar %s: ' % _name + field = ':ivar %s: ' % _name # type: unicode lines.extend(self._format_block(field, _desc)) if _type: lines.append(':vartype %s: %s' % (_name, _type)) else: lines.extend(['.. attribute:: ' + _name, '']) - field = self._format_field('', _type, _desc) - lines.extend(self._indent(field, 3)) + field = self._format_field('', _type, _desc) # type: ignore + lines.extend(self._indent(field, 3)) # type: ignore lines.append('') if self._config.napoleon_use_ivar: lines.append('') return lines def _parse_examples_section(self, section): + # type: (unicode) -> List[unicode] use_admonition = self._config.napoleon_use_admonition_for_examples return self._parse_generic_section(section, use_admonition) def _parse_usage_section(self, section): - header = ['.. rubric:: Usage:', ''] - block = ['.. code-block:: python', ''] + # type: (unicode) -> List[unicode] + header = ['.. rubric:: Usage:', ''] # type: List[unicode] + block = ['.. code-block:: python', ''] # type: List[unicode] lines = self._consume_usage_section() lines = self._indent(lines, 3) return header + block + lines + [''] def _parse_generic_section(self, section, use_admonition): + # type: (unicode, bool) -> List[unicode] lines = self._strip_empty(self._consume_to_next_section()) lines = self._dedent(lines) if use_admonition: - header = '.. admonition:: %s' % section + header = '.. admonition:: %s' % section # type: unicode lines = self._indent(lines, 3) else: header = '.. rubric:: %s' % section @@ -558,6 +601,7 @@ class GoogleDocstring(UnicodeMixin): return [header, ''] def _parse_keyword_arguments_section(self, section): + # type: (unicode) -> List[unicode] fields = self._consume_fields() if self._config.napoleon_use_keyword: return self._format_docutils_params( @@ -568,26 +612,31 @@ class GoogleDocstring(UnicodeMixin): return self._format_fields('Keyword Arguments', fields) def _parse_methods_section(self, section): - lines = [] + # type: (unicode) -> List[unicode] + lines = [] # type: List[unicode] for _name, _, _desc in self._consume_fields(parse_type=False): lines.append('.. method:: %s' % _name) if _desc: - lines.extend([''] + self._indent(_desc, 3)) + lines.extend([''] + self._indent(_desc, 3)) # type: ignore lines.append('') return lines def _parse_note_section(self, section): + # type: (unicode) -> List[unicode] lines = self._consume_to_next_section() return self._format_admonition('note', lines) def _parse_notes_section(self, section): + # type: (unicode) -> List[unicode] use_admonition = self._config.napoleon_use_admonition_for_notes return self._parse_generic_section('Notes', use_admonition) def _parse_other_parameters_section(self, section): + # type: (unicode) -> List[unicode] return self._format_fields('Other Parameters', self._consume_fields()) def _parse_parameters_section(self, section): + # type: (unicode) -> List[unicode] fields = self._consume_fields() if self._config.napoleon_use_param: return self._format_docutils_params(fields) @@ -595,11 +644,12 @@ class GoogleDocstring(UnicodeMixin): return self._format_fields('Parameters', fields) def _parse_raises_section(self, section): + # type: (unicode) -> List[unicode] fields = self._consume_fields(parse_type=False, prefer_type=True) field_type = ':raises:' padding = ' ' * len(field_type) multi = len(fields) > 1 - lines = [] + lines = [] # type: List[unicode] for _, _type, _desc in fields: _desc = self._strip_empty(_desc) has_desc = any(_desc) @@ -633,10 +683,12 @@ class GoogleDocstring(UnicodeMixin): return lines def _parse_references_section(self, section): + # type: (unicode) -> List[unicode] use_admonition = self._config.napoleon_use_admonition_for_references return self._parse_generic_section('References', use_admonition) def _parse_returns_section(self, section): + # type: (unicode) -> List[unicode] fields = self._consume_returns_section() multi = len(fields) > 1 if multi: @@ -644,7 +696,7 @@ class GoogleDocstring(UnicodeMixin): else: use_rtype = self._config.napoleon_use_rtype - lines = [] + lines = [] # type: List[unicode] for _name, _type, _desc in fields: if use_rtype: field = self._format_field(_name, '', _desc) @@ -665,30 +717,36 @@ class GoogleDocstring(UnicodeMixin): return lines def _parse_see_also_section(self, section): + # type: (unicode) -> List[unicode] lines = self._consume_to_next_section() return self._format_admonition('seealso', lines) def _parse_todo_section(self, section): + # type: (unicode) -> List[unicode] lines = self._consume_to_next_section() return self._format_admonition('todo', lines) def _parse_warning_section(self, section): + # type: (unicode) -> List[unicode] lines = self._consume_to_next_section() return self._format_admonition('warning', lines) def _parse_warns_section(self, section): + # type: (unicode) -> List[unicode] return self._format_fields('Warns', self._consume_fields()) def _parse_yields_section(self, section): + # type: (unicode) -> List[unicode] fields = self._consume_returns_section() return self._format_fields('Yields', fields) def _partition_field_on_colon(self, line): + # type: (unicode) -> Tuple[unicode, unicode, unicode] before_colon = [] after_colon = [] colon = '' found_colon = False - for i, source in enumerate(_xref_regex.split(line)): + for i, source in enumerate(_xref_regex.split(line)): # type: ignore if found_colon: after_colon.append(source) else: @@ -706,6 +764,7 @@ class GoogleDocstring(UnicodeMixin): "".join(after_colon).strip()) def _strip_empty(self, lines): + # type: (List[unicode]) -> List[unicode] if lines: start = -1 for i, line in enumerate(lines): @@ -820,12 +879,14 @@ class NumpyDocstring(GoogleDocstring): """ def __init__(self, docstring, config=None, app=None, what='', name='', obj=None, options=None): + # type: (Union[unicode, List[unicode]], SphinxConfig, Sphinx, unicode, unicode, Any, Any) -> None # NOQA self._directive_sections = ['.. index::'] super(NumpyDocstring, self).__init__(docstring, config, app, what, name, obj, options) def _consume_field(self, parse_type=True, prefer_type=False): - line = next(self._line_iter) + # type: (bool, bool) -> Tuple[unicode, unicode, List[unicode]] + line = next(self._line_iter) # type: ignore if parse_type: _name, _, _type = self._partition_field_on_colon(line) else: @@ -841,16 +902,19 @@ class NumpyDocstring(GoogleDocstring): return _name, _type, _desc def _consume_returns_section(self): + # type: () -> List[Tuple[unicode, unicode, List[unicode]]] return self._consume_fields(prefer_type=True) def _consume_section_header(self): - section = next(self._line_iter) + # type: () -> unicode + section = next(self._line_iter) # type: ignore if not _directive_regex.match(section): # Consume the header underline - next(self._line_iter) + next(self._line_iter) # type: ignore return section def _is_section_break(self): + # type: () -> bool line1, line2 = self._line_iter.peek(2) return (not self._line_iter.has_next() or self._is_section_header() or @@ -860,10 +924,11 @@ class NumpyDocstring(GoogleDocstring): not self._is_indented(line1, self._section_indent))) def _is_section_header(self): + # type: () -> bool section, underline = self._line_iter.peek(2) section = section.lower() if section in self._sections and isinstance(underline, string_types): - return bool(_numpy_section_regex.match(underline)) + return bool(_numpy_section_regex.match(underline)) # type: ignore elif self._directive_sections: if _directive_regex.match(section): for directive_section in self._directive_sections: @@ -875,6 +940,7 @@ class NumpyDocstring(GoogleDocstring): r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X) def _parse_see_also_section(self, section): + # type: (unicode) -> List[unicode] lines = self._consume_to_next_section() try: return self._parse_numpydoc_see_also_section(lines) @@ -882,6 +948,7 @@ class NumpyDocstring(GoogleDocstring): return self._format_admonition('seealso', lines) def _parse_numpydoc_see_also_section(self, content): + # type: (List[unicode]) -> List[unicode] """ Derived from the NumpyDoc implementation of _parse_see_also. @@ -914,13 +981,13 @@ class NumpyDocstring(GoogleDocstring): del rest[:] current_func = None - rest = [] + rest = [] # type: List[unicode] for line in content: if not line.strip(): continue - m = self._name_rgx.match(line) + m = self._name_rgx.match(line) # type: ignore if m and line[m.end():].strip().startswith(':'): push_item(current_func, rest) current_func, line = line[:m.end()], line[m.end():] @@ -960,12 +1027,12 @@ class NumpyDocstring(GoogleDocstring): 'const': 'const', 'attribute': 'attr', 'attr': 'attr' - } + } # type: Dict[unicode, unicode] if self._what is None: - func_role = 'obj' + func_role = 'obj' # type: unicode else: func_role = roles.get(self._what, '') - lines = [] + lines = [] # type: List[unicode] last_had_desc = True for func, desc, role in items: if role: diff --git a/sphinx/ext/napoleon/iterators.py b/sphinx/ext/napoleon/iterators.py index f66d67f2c..76544b534 100644 --- a/sphinx/ext/napoleon/iterators.py +++ b/sphinx/ext/napoleon/iterators.py @@ -13,6 +13,10 @@ import collections +if False: + # For type annotation + from typing import Any, Iterable # NOQA + class peek_iter(object): """An iterator object that supports peeking ahead. @@ -48,34 +52,39 @@ class peek_iter(object): """ def __init__(self, *args): + # type: (Any) -> None """__init__(o, sentinel=None)""" - self._iterable = iter(*args) - self._cache = collections.deque() + self._iterable = iter(*args) # type: Iterable + self._cache = collections.deque() # type: collections.deque if len(args) == 2: self.sentinel = args[1] else: self.sentinel = object() def __iter__(self): + # type: () -> peek_iter return self def __next__(self, n=None): + # type: (int) -> Any # note: prevent 2to3 to transform self.next() in next(self) which # causes an infinite loop ! return getattr(self, 'next')(n) def _fillcache(self, n): + # type: (int) -> None """Cache `n` items. If `n` is 0 or None, then 1 item is cached.""" if not n: n = 1 try: while len(self._cache) < n: - self._cache.append(next(self._iterable)) + self._cache.append(next(self._iterable)) # type: ignore except StopIteration: while len(self._cache) < n: self._cache.append(self.sentinel) def has_next(self): + # type: () -> bool """Determine if iterator is exhausted. Returns @@ -91,6 +100,7 @@ class peek_iter(object): return self.peek() != self.sentinel def next(self, n=None): + # type: (int) -> Any """Get the next item or `n` items of the iterator. Parameters @@ -126,6 +136,7 @@ class peek_iter(object): return result def peek(self, n=None): + # type: (int) -> Any """Preview the next item or `n` items of the iterator. The iterator is not advanced when peek is called. @@ -209,6 +220,7 @@ class modify_iter(peek_iter): """ def __init__(self, *args, **kwargs): + # type: (Any, Any) -> None """__init__(o, sentinel=None, modifier=lambda x: x)""" if 'modifier' in kwargs: self.modifier = kwargs['modifier'] @@ -223,6 +235,7 @@ class modify_iter(peek_iter): super(modify_iter, self).__init__(*args) def _fillcache(self, n): + # type: (int) -> None """Cache `n` modified items. If `n` is 0 or None, 1 item is cached. Each item returned by the iterator is passed through the @@ -233,7 +246,7 @@ class modify_iter(peek_iter): n = 1 try: while len(self._cache) < n: - self._cache.append(self.modifier(next(self._iterable))) + self._cache.append(self.modifier(next(self._iterable))) # type: ignore except StopIteration: while len(self._cache) < n: self._cache.append(self.sentinel) diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index 655eb562f..f4431b07f 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -20,20 +20,31 @@ from subprocess import Popen, PIPE from hashlib import sha1 from six import text_type + from docutils import nodes import sphinx from sphinx.errors import SphinxError, ExtensionError +from sphinx.util import logging from sphinx.util.png import read_png_depth, write_png_depth from sphinx.util.osutil import ensuredir, ENOENT, cd from sphinx.util.pycompat import sys_encoding from sphinx.ext.mathbase import setup_math as mathbase_setup, wrap_displaymath +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.ext.mathbase import math as math_node, displaymath # NOQA + +logger = logging.getLogger(__name__) + class MathExtError(SphinxError): category = 'Math extension error' def __init__(self, msg, stderr=None, stdout=None): + # type: (unicode, unicode, unicode) -> None if stderr: msg += '\n[stderr]\n' + stderr.decode(sys_encoding, 'replace') if stdout: @@ -71,6 +82,7 @@ depth_re = re.compile(br'\[\d+ depth=(-?\d+)\]') def render_math(self, math): + # type: (nodes.NodeVisitor, unicode) -> Tuple[unicode, int] """Render the LaTeX math expression *math* using latex and dvipng. Return the filename relative to the built document and the "depth", @@ -107,9 +119,8 @@ def render_math(self, math): else: tempdir = self.builder._mathpng_tempdir - tf = codecs.open(path.join(tempdir, 'math.tex'), 'w', 'utf-8') - tf.write(latex) - tf.close() + with codecs.open(path.join(tempdir, 'math.tex'), 'w', 'utf-8') as tf: # type: ignore + tf.write(latex) # build latex command; old versions of latex don't have the # --output-directory option, so we have to manually chdir to the @@ -125,9 +136,9 @@ def render_math(self, math): except OSError as err: if err.errno != ENOENT: # No such file or directory raise - self.builder.warn('LaTeX command %r cannot be run (needed for math ' - 'display), check the pngmath_latex setting' % - self.builder.config.pngmath_latex) + logger.warning('LaTeX command %r cannot be run (needed for math ' + 'display), check the pngmath_latex setting', + self.builder.config.pngmath_latex) self.builder._mathpng_warned_latex = True return None, None @@ -150,9 +161,9 @@ def render_math(self, math): except OSError as err: if err.errno != ENOENT: # No such file or directory raise - self.builder.warn('dvipng command %r cannot be run (needed for math ' - 'display), check the pngmath_dvipng setting' % - self.builder.config.pngmath_dvipng) + logger.warning('dvipng command %r cannot be run (needed for math ' + 'display), check the pngmath_dvipng setting', + self.builder.config.pngmath_dvipng) self.builder._mathpng_warned_dvipng = True return None, None stdout, stderr = p.communicate() @@ -171,23 +182,26 @@ def render_math(self, math): def cleanup_tempdir(app, exc): + # type: (Sphinx, Exception) -> None if exc: return if not hasattr(app.builder, '_mathpng_tempdir'): return try: - shutil.rmtree(app.builder._mathpng_tempdir) + shutil.rmtree(app.builder._mathpng_tempdir) # type: ignore except Exception: pass def get_tooltip(self, node): + # type: (nodes.NodeVisitor, math_node) -> unicode if self.builder.config.pngmath_add_tooltips: return ' alt="%s"' % self.encode(node['latex']).strip() return '' def html_visit_math(self, node): + # type: (nodes.NodeVisitor, math_node) -> None try: fname, depth = render_math(self, '$'+node['latex']+'$') except MathExtError as exc: @@ -195,7 +209,7 @@ def html_visit_math(self, node): sm = nodes.system_message(msg, type='WARNING', level=2, backrefs=[], source=node['latex']) sm.walkabout(self) - self.builder.warn('display latex %r: ' % node['latex'] + msg) + logger.warning('display latex %r: %s', node['latex'], msg) raise nodes.SkipNode if fname is None: # something failed -- use text-only as a bad substitute @@ -210,6 +224,7 @@ def html_visit_math(self, node): def html_visit_displaymath(self, node): + # type: (nodes.NodeVisitor, displaymath) -> None if node['nowrap']: latex = node['latex'] else: @@ -222,7 +237,7 @@ def html_visit_displaymath(self, node): sm = nodes.system_message(msg, type='WARNING', level=2, backrefs=[], source=node['latex']) sm.walkabout(self) - self.builder.warn('inline latex %r: ' % node['latex'] + msg) + logger.warning('inline latex %r: %s', node['latex'], msg) raise nodes.SkipNode self.body.append(self.starttag(node, 'div', CLASS='math')) self.body.append('<p>') @@ -239,7 +254,9 @@ def html_visit_displaymath(self, node): def setup(app): - app.warn('sphinx.ext.pngmath has been deprecated. Please use sphinx.ext.imgmath instead.') + # type: (Sphinx) -> Dict[unicode, Any] + logger.warning('sphinx.ext.pngmath has been deprecated. ' + 'Please use sphinx.ext.imgmath instead.') try: mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None)) except ExtensionError: diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index f3b526ce6..f575e7462 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -18,10 +18,19 @@ from docutils.parsers.rst import directives import sphinx from sphinx.locale import _ from sphinx.environment import NoUri +from sphinx.util import logging from sphinx.util.nodes import set_source_info from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.admonitions import BaseAdmonition +if False: + # For type annotation + from typing import Any, Iterable # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) + class todo_node(nodes.Admonition, nodes.Element): pass @@ -46,6 +55,7 @@ class Todo(BaseAdmonition): } def run(self): + # type: () -> List[nodes.Node] if not self.options.get('class'): self.options['class'] = ['admonition-todo'] @@ -63,12 +73,13 @@ class Todo(BaseAdmonition): def process_todos(app, doctree): + # type: (Sphinx, nodes.Node) -> None # collect all todos in the environment # this is not done in the directive itself because it some transformations # must have already been run, e.g. substitutions env = app.builder.env if not hasattr(env, 'todo_all_todos'): - env.todo_all_todos = [] + env.todo_all_todos = [] # type: ignore for node in doctree.traverse(todo_node): app.emit('todo-defined', node) @@ -80,7 +91,7 @@ def process_todos(app, doctree): targetnode = None newnode = node.deepcopy() del newnode['ids'] - env.todo_all_todos.append({ + env.todo_all_todos.append({ # type: ignore 'docname': env.docname, 'source': node.source or env.doc2path(env.docname), 'lineno': node.line, @@ -89,7 +100,8 @@ def process_todos(app, doctree): }) if env.config.todo_emit_warnings: - env.warn_node("TODO entry found: %s" % node[1].astext(), node) + logger.warning("TODO entry found: %s", node[1].astext(), + location=node) class TodoList(Directive): @@ -101,15 +113,17 @@ class TodoList(Directive): required_arguments = 0 optional_arguments = 0 final_argument_whitespace = False - option_spec = {} + option_spec = {} # type: Dict def run(self): + # type: () -> List[todolist] # Simply insert an empty todolist node which will be replaced later # when process_todo_nodes is called return [todolist('')] def process_todo_nodes(app, doctree, fromdocname): + # type: (Sphinx, nodes.Node, unicode) -> None if not app.config['todo_include_todos']: for node in doctree.traverse(todo_node): node.parent.remove(node) @@ -119,7 +133,7 @@ def process_todo_nodes(app, doctree, fromdocname): env = app.builder.env if not hasattr(env, 'todo_all_todos'): - env.todo_all_todos = [] + env.todo_all_todos = [] # type: ignore for node in doctree.traverse(todolist): if not app.config['todo_include_todos']: @@ -128,7 +142,7 @@ def process_todo_nodes(app, doctree, fromdocname): content = [] - for todo_info in env.todo_all_todos: + for todo_info in env.todo_all_todos: # type: ignore para = nodes.paragraph(classes=['todo-source']) if app.config['todo_link_only']: description = _('<<original entry>>') @@ -168,30 +182,35 @@ def process_todo_nodes(app, doctree, fromdocname): def purge_todos(app, env, docname): + # type: (Sphinx, BuildEnvironment, unicode) -> None if not hasattr(env, 'todo_all_todos'): return - env.todo_all_todos = [todo for todo in env.todo_all_todos + env.todo_all_todos = [todo for todo in env.todo_all_todos # type: ignore if todo['docname'] != docname] def merge_info(app, env, docnames, other): + # type: (Sphinx, BuildEnvironment, Iterable[unicode], BuildEnvironment) -> None if not hasattr(other, 'todo_all_todos'): return if not hasattr(env, 'todo_all_todos'): - env.todo_all_todos = [] - env.todo_all_todos.extend(other.todo_all_todos) + env.todo_all_todos = [] # type: ignore + env.todo_all_todos.extend(other.todo_all_todos) # type: ignore def visit_todo_node(self, node): + # type: (nodes.NodeVisitor, todo_node) -> None self.visit_admonition(node) # self.visit_admonition(node, 'todo') def depart_todo_node(self, node): + # type: (nodes.NodeVisitor, todo_node) -> None self.depart_admonition(node) def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_event('todo-defined') app.add_config_value('todo_include_todos', False, 'html') app.add_config_value('todo_link_only', False, 'html') diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 276a137d5..c639c6c55 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -12,51 +12,61 @@ import traceback from six import iteritems, text_type + from docutils import nodes import sphinx from sphinx import addnodes from sphinx.locale import _ from sphinx.pycode import ModuleAnalyzer -from sphinx.util import get_full_modname +from sphinx.util import get_full_modname, logging from sphinx.util.nodes import make_refnode -from sphinx.util.console import blue +from sphinx.util.console import blue # type: ignore + +if False: + # For type annotation + from typing import Any, Iterable, Iterator, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.environment import BuildEnvironment # NOQA + +logger = logging.getLogger(__name__) def _get_full_modname(app, modname, attribute): + # type: (Sphinx, str, unicode) -> unicode try: return get_full_modname(modname, attribute) except AttributeError: # sphinx.ext.viewcode can't follow class instance attribute # then AttributeError logging output only verbose mode. - app.verbose('Didn\'t find %s in %s' % (attribute, modname)) + logger.verbose('Didn\'t find %s in %s', attribute, modname) return None except Exception as e: # sphinx.ext.viewcode follow python domain directives. # because of that, if there are no real modules exists that specified # by py:function or other directives, viewcode emits a lot of warnings. # It should be displayed only verbose mode. - app.verbose(traceback.format_exc().rstrip()) - app.verbose('viewcode can\'t import %s, failed with error "%s"' % - (modname, e)) + logger.verbose(traceback.format_exc().rstrip()) + logger.verbose('viewcode can\'t import %s, failed with error "%s"', modname, e) return None def doctree_read(app, doctree): + # type: (Sphinx, nodes.Node) -> None env = app.builder.env if not hasattr(env, '_viewcode_modules'): - env._viewcode_modules = {} + env._viewcode_modules = {} # type: ignore if app.builder.name == "singlehtml": return if app.builder.name.startswith("epub") and not env.config.viewcode_enable_epub: return def has_tag(modname, fullname, docname, refname): - entry = env._viewcode_modules.get(modname, None) + entry = env._viewcode_modules.get(modname, None) # type: ignore try: analyzer = ModuleAnalyzer.for_module(modname) except Exception: - env._viewcode_modules[modname] = False + env._viewcode_modules[modname] = False # type: ignore return if not isinstance(analyzer.code, text_type): code = analyzer.code.decode(analyzer.encoding) @@ -65,7 +75,7 @@ def doctree_read(app, doctree): if entry is None or entry[0] != code: analyzer.find_tags() entry = code, analyzer.tags, {}, refname - env._viewcode_modules[modname] = entry + env._viewcode_modules[modname] = entry # type: ignore elif entry is False: return _, tags, used, _ = entry @@ -76,7 +86,7 @@ def doctree_read(app, doctree): for objnode in doctree.traverse(addnodes.desc): if objnode.get('domain') != 'py': continue - names = set() + names = set() # type: Set[unicode] for signode in objnode: if not isinstance(signode, addnodes.desc_signature): continue @@ -106,16 +116,18 @@ def doctree_read(app, doctree): def env_merge_info(app, env, docnames, other): + # type: (Sphinx, BuildEnvironment, Iterable[unicode], BuildEnvironment) -> None if not hasattr(other, '_viewcode_modules'): return # create a _viewcode_modules dict on the main environment if not hasattr(env, '_viewcode_modules'): - env._viewcode_modules = {} + env._viewcode_modules = {} # type: ignore # now merge in the information from the subprocess - env._viewcode_modules.update(other._viewcode_modules) + env._viewcode_modules.update(other._viewcode_modules) # type: ignore def missing_reference(app, env, node, contnode): + # type: (Sphinx, BuildEnvironment, nodes.Node, nodes.Node) -> nodes.Node # resolve our "viewcode" reference nodes -- they need special treatment if node['reftype'] == 'viewcode': return make_refnode(app.builder, node['refdoc'], node['reftarget'], @@ -123,20 +135,21 @@ def missing_reference(app, env, node, contnode): def collect_pages(app): + # type: (Sphinx) -> Iterator[Tuple[unicode, Dict[unicode, Any], unicode]] env = app.builder.env if not hasattr(env, '_viewcode_modules'): return - highlighter = app.builder.highlighter + highlighter = app.builder.highlighter # type: ignore urito = app.builder.get_relative_uri - modnames = set(env._viewcode_modules) + modnames = set(env._viewcode_modules) # type: ignore # app.builder.info(' (%d module code pages)' % # len(env._viewcode_modules), nonl=1) for modname, entry in app.status_iterator( - iteritems(env._viewcode_modules), 'highlighting module code... ', - blue, len(env._viewcode_modules), lambda x: x[0]): + iteritems(env._viewcode_modules), 'highlighting module code... ', # type:ignore + blue, len(env._viewcode_modules), lambda x: x[0]): # type:ignore if not entry: continue code, tags, used, refname = entry @@ -185,7 +198,7 @@ def collect_pages(app): 'title': modname, 'body': (_('<h1>Source code for %s</h1>') % modname + '\n'.join(lines)), - } + } # type: Dict[unicode, Any] yield (pagename, context, 'page.html') if not modnames: @@ -218,6 +231,7 @@ def collect_pages(app): def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] app.add_config_value('viewcode_import', True, False) app.add_config_value('viewcode_enable_epub', False, False) app.connect('doctree-read', doctree_read) diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 198939197..493ecb7a7 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -11,11 +11,13 @@ from six import text_type +from sphinx.util import logging from sphinx.util.pycompat import htmlescape from sphinx.util.texescape import tex_hl_escape_map_new from sphinx.ext import doctest from pygments import highlight +from pygments.lexer import Lexer # NOQA from pygments.lexers import PythonLexer, Python3Lexer, PythonConsoleLexer, \ CLexer, TextLexer, RstLexer from pygments.lexers import get_lexer_by_name, guess_lexer @@ -25,6 +27,8 @@ from pygments.styles import get_style_by_name from pygments.util import ClassNotFound from sphinx.pygments_styles import SphinxStyle, NoneStyle +logger = logging.getLogger(__name__) + lexers = dict( none = TextLexer(stripnl=False), python = PythonLexer(stripnl=False), @@ -33,7 +37,7 @@ lexers = dict( pycon3 = PythonConsoleLexer(python3=True, stripnl=False), rest = RstLexer(stripnl=False), c = CLexer(stripnl=False), -) +) # type: Dict[unicode, Lexer] for _lexer in lexers.values(): _lexer.add_filter('raiseonerror') @@ -91,7 +95,7 @@ class PygmentsBridge(object): return '\\begin{Verbatim}[commandchars=\\\\\\{\\}]\n' + \ source + '\\end{Verbatim}\n' - def highlight_block(self, source, lang, opts=None, warn=None, force=False, **kwargs): + def highlight_block(self, source, lang, opts=None, location=None, force=False, **kwargs): if not isinstance(source, text_type): source = source.decode() @@ -119,11 +123,9 @@ class PygmentsBridge(object): try: lexer = lexers[lang] = get_lexer_by_name(lang, **(opts or {})) except ClassNotFound: - if warn: - warn('Pygments lexer name %r is not known' % lang) - lexer = lexers['none'] - else: - raise + logger.warning('Pygments lexer name %r is not known', lang, + location=location) + lexer = lexers['none'] else: lexer.add_filter('raiseonerror') @@ -136,17 +138,16 @@ class PygmentsBridge(object): formatter = self.get_formatter(**kwargs) try: hlsource = highlight(source, lexer, formatter) - except ErrorToken as exc: + except ErrorToken: # this is most probably not the selected language, # so let it pass unhighlighted if lang == 'default': pass # automatic highlighting failed. - elif warn: - warn('Could not lex literal_block as "%s". ' - 'Highlighting skipped.' % lang, - type='misc', subtype='highlighting_failure') else: - raise exc + logger.warning('Could not lex literal_block as "%s". ' + 'Highlighting skipped.', lang, + type='misc', subtype='highlighting_failure', + location=location) hlsource = highlight(source, lexers['none'], formatter) if self.dest == 'html': return hlsource diff --git a/sphinx/io.py b/sphinx/io.py index f1386c9a8..e29420d97 100644 --- a/sphinx/io.py +++ b/sphinx/io.py @@ -12,6 +12,7 @@ from docutils.io import FileInput from docutils.readers import standalone from docutils.writers import UnfilteredWriter from six import string_types, text_type +from typing import Any, Union # NOQA from sphinx.transforms import ( ApplySourceWorkaround, ExtraTranslatableNodes, CitationReferences, @@ -23,6 +24,18 @@ from sphinx.transforms.i18n import ( PreserveTranslatableMessages, Locale, RemoveTranslatableInline, ) from sphinx.util import import_object, split_docinfo +from sphinx.util.docutils import LoggingReporter + +if False: + # For type annotation + from typing import Any, Union # NOQA + from docutils import nodes # NOQA + from docutils.io import Input # NOQA + from docutils.parsers import Parser # NOQA + from docutils.transforms import Transform # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA class SphinxBaseReader(standalone.Reader): @@ -30,17 +43,19 @@ class SphinxBaseReader(standalone.Reader): Add our source parsers """ def __init__(self, app, parsers={}, *args, **kwargs): + # type: (Sphinx, Dict[unicode, Parser], Any, Any) -> None standalone.Reader.__init__(self, *args, **kwargs) - self.parser_map = {} + self.parser_map = {} # type: Dict[unicode, Parser] for suffix, parser_class in parsers.items(): if isinstance(parser_class, string_types): - parser_class = import_object(parser_class, 'source parser') + parser_class = import_object(parser_class, 'source parser') # type: ignore parser = parser_class() if hasattr(parser, 'set_application'): parser.set_application(app) self.parser_map[suffix] = parser def read(self, source, parser, settings): + # type: (Input, Parser, Dict) -> nodes.document self.source = source for suffix in self.parser_map: @@ -56,8 +71,17 @@ class SphinxBaseReader(standalone.Reader): return self.document def get_transforms(self): + # type: () -> List[Transform] return standalone.Reader.get_transforms(self) + self.transforms + def new_document(self): + document = standalone.Reader.new_document(self) + reporter = document.reporter + document.reporter = LoggingReporter(reporter.source, reporter.report_level, + reporter.halt_level, reporter.debug_flag, + reporter.error_handler) + return document + class SphinxStandaloneReader(SphinxBaseReader): """ @@ -84,13 +108,16 @@ class SphinxI18nReader(SphinxBaseReader): FilterSystemMessages, RefOnlyBulletListTransform] def __init__(self, *args, **kwargs): + # type: (Any, Any) -> None SphinxBaseReader.__init__(self, *args, **kwargs) - self.lineno = None + self.lineno = None # type: int def set_lineno_for_reporter(self, lineno): + # type: (int) -> None self.lineno = lineno def new_document(self): + # type: () -> nodes.document document = SphinxBaseReader.new_document(self) reporter = document.reporter @@ -105,28 +132,32 @@ class SphinxDummyWriter(UnfilteredWriter): supported = ('html',) # needed to keep "meta" nodes def translate(self): + # type: () -> None pass class SphinxFileInput(FileInput): def __init__(self, app, env, *args, **kwds): + # type: (Sphinx, BuildEnvironment, Any, Any) -> None self.app = app self.env = env kwds['error_handler'] = 'sphinx' # py3: handle error on open. FileInput.__init__(self, *args, **kwds) def decode(self, data): + # type: (Union[unicode, bytes]) -> unicode if isinstance(data, text_type): # py3: `data` already decoded. return data return data.decode(self.encoding, 'sphinx') # py2: decoding def read(self): + # type: () -> unicode def get_parser_type(source_path): for suffix in self.env.config.source_parsers: if source_path.endswith(suffix): parser_class = self.env.config.source_parsers[suffix] if isinstance(parser_class, string_types): - parser_class = import_object(parser_class, 'source parser') + parser_class = import_object(parser_class, 'source parser') # type: ignore # NOQA return parser_class.supported else: return ('restructuredtext',) diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index 6e2ef7186..c1bd04765 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -17,18 +17,28 @@ from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, \ contextfunction from jinja2.utils import open_if_exists from jinja2.sandbox import SandboxedEnvironment +from typing import Any, Callable, Iterator, Tuple # NOQA from sphinx.application import TemplateBridge from sphinx.util.osutil import mtimes_of_files +if False: + # For type annotation + from typing import Any, Callable, Iterator, Tuple # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.environment import BuildEnvironment # NOQA + from sphinx.themes import Theme # NOQA + def _tobool(val): + # type: (unicode) -> bool if isinstance(val, string_types): - return val.lower() in ('true', '1', 'yes', 'on') + return val.lower() in ('true', '1', 'yes', 'on') # type: ignore return bool(val) def _toint(val): + # type: (unicode) -> int try: return int(val) except ValueError: @@ -36,6 +46,7 @@ def _toint(val): def _slice_index(values, slices): + # type: (List, int) -> Iterator[List] seq = list(values) length = 0 for value in values: @@ -57,6 +68,7 @@ def _slice_index(values, slices): def accesskey(context, key): + # type: (Any, unicode) -> unicode """Helper to output each access key only once.""" if '_accesskeys' not in context: context.vars['_accesskeys'] = {} @@ -68,12 +80,15 @@ def accesskey(context, key): class idgen(object): def __init__(self): + # type: () -> None self.id = 0 def current(self): + # type: () -> int return self.id def __next__(self): + # type: () -> int self.id += 1 return self.id next = __next__ # Python 2/Jinja compatibility @@ -86,6 +101,7 @@ class SphinxFileSystemLoader(FileSystemLoader): """ def get_source(self, environment, template): + # type: (BuildEnvironment, unicode) -> Tuple[unicode, unicode, Callable] for searchpath in self.searchpath: filename = path.join(searchpath, template) f = open_if_exists(filename) @@ -113,6 +129,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader): # TemplateBridge interface def init(self, builder, theme=None, dirs=None): + # type: (Builder, Theme, List[unicode]) -> None # create a chain of paths to search if theme: # the theme's own dir and its bases' dirs @@ -155,17 +172,21 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader): builder.app.translator) def render(self, template, context): + # type: (unicode, Dict) -> None return self.environment.get_template(template).render(context) def render_string(self, source, context): + # type: (unicode, Dict) -> unicode return self.environment.from_string(source).render(context) def newest_template_mtime(self): + # type: () -> float return max(mtimes_of_files(self.pathchain, '.html')) # Loader interface def get_source(self, environment, template): + # type: (BuildEnvironment, unicode) -> Tuple[unicode, unicode, Callable] loaders = self.loaders # exclamation mark starts search from theme if template.startswith('!'): diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py index d6ce7329b..44ad64304 100644 --- a/sphinx/locale/__init__.py +++ b/sphinx/locale/__init__.py @@ -14,6 +14,10 @@ import gettext from six import PY3, text_type from six.moves import UserString +if False: + # For type annotation + from typing import Any, Tuple # NOQA + class _TranslationProxy(UserString, object): """ @@ -140,6 +144,7 @@ class _TranslationProxy(UserString, object): def mygettext(string): + # type: (unicode) -> unicode """Used instead of _ when creating TranslationProxies, because _ is not bound yet at that time. """ @@ -147,10 +152,11 @@ def mygettext(string): def lazy_gettext(string): + # type: (unicode) -> unicode """A lazy version of `gettext`.""" # if isinstance(string, _TranslationProxy): # return string - return _TranslationProxy(mygettext, string) + return _TranslationProxy(mygettext, string) # type: ignore l_ = lazy_gettext @@ -184,19 +190,22 @@ pairindextypes = { 'exception': l_('exception'), 'statement': l_('statement'), 'builtin': l_('built-in function'), -} +} # Dict[unicode, _TranslationProxy] -translators = {} +translators = {} # type: Dict[unicode, Any] if PY3: def _(message): + # type: (unicode) -> unicode return translators['sphinx'].gettext(message) else: def _(message): + # type: (unicode) -> unicode return translators['sphinx'].ugettext(message) def init(locale_dirs, language, catalog='sphinx'): + # type: (List, unicode, unicode) -> Tuple[Any, bool] """Look for message catalogs in `locale_dirs` and *ensure* that there is at least a NullTranslations catalog set in `translators`. If called multiple times or if several ``.mo`` files are found, their contents are merged @@ -213,12 +222,12 @@ def init(locale_dirs, language, catalog='sphinx'): # loading for dir_ in locale_dirs: try: - trans = gettext.translation(catalog, localedir=dir_, - languages=[language]) + trans = gettext.translation(catalog, localedir=dir_, # type: ignore + languages=[language]) # type: ignore if translator is None: translator = trans else: - translator._catalog.update(trans._catalog) + translator._catalog.update(trans._catalog) # type: ignore except Exception: # Language couldn't be found in the specified path pass diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py index 6aeeab802..2da5d5b71 100644 --- a/sphinx/make_mode.py +++ b/sphinx/make_mode.py @@ -22,7 +22,7 @@ from os import path from subprocess import call import sphinx -from sphinx.util.console import bold, blue +from sphinx.util.console import bold, blue # type: ignore from sphinx.util.osutil import cd, rmtree proj_name = os.getenv('SPHINXPROJ', '<project>') @@ -59,17 +59,20 @@ BUILDERS = [ class Make(object): def __init__(self, srcdir, builddir, opts): + # type: (unicode, unicode, List[unicode]) -> None self.srcdir = srcdir self.builddir = builddir self.opts = opts self.makecmd = os.environ.get('MAKE', 'make') # refer $MAKE to determine make command def builddir_join(self, *comps): + # type: (unicode) -> unicode return path.join(self.builddir, *comps) def build_clean(self): + # type: () -> int if not path.exists(self.builddir): - return + return 0 elif not path.isdir(self.builddir): print("Error: %r is not a directory!" % self.builddir) return 1 @@ -78,19 +81,22 @@ class Make(object): rmtree(self.builddir_join(item)) def build_help(self): + # type: () -> None print(bold("Sphinx v%s" % sphinx.__display_version__)) - print("Please use `make %s' where %s is one of" % ((blue('target'),)*2)) + print("Please use `make %s' where %s is one of" % ((blue('target'),)*2)) # type: ignore # NOQA for osname, bname, description in BUILDERS: if not osname or os.name == osname: print(' %s %s' % (blue(bname.ljust(10)), description)) def build_html(self): + # type: () -> int if self.run_generic_build('html') > 0: return 1 print() print('Build finished. The HTML pages are in %s.' % self.builddir_join('html')) def build_dirhtml(self): + # type: () -> int if self.run_generic_build('dirhtml') > 0: return 1 print() @@ -98,6 +104,7 @@ class Make(object): self.builddir_join('dirhtml')) def build_singlehtml(self): + # type: () -> int if self.run_generic_build('singlehtml') > 0: return 1 print() @@ -105,18 +112,21 @@ class Make(object): self.builddir_join('singlehtml')) def build_pickle(self): + # type: () -> int if self.run_generic_build('pickle') > 0: return 1 print() print('Build finished; now you can process the pickle files.') def build_json(self): + # type: () -> int if self.run_generic_build('json') > 0: return 1 print() print('Build finished; now you can process the JSON files.') def build_htmlhelp(self): + # type: () -> int if self.run_generic_build('htmlhelp') > 0: return 1 print() @@ -124,6 +134,7 @@ class Make(object): '.hhp project file in %s.' % self.builddir_join('htmlhelp')) def build_qthelp(self): + # type: () -> int if self.run_generic_build('qthelp') > 0: return 1 print() @@ -135,6 +146,7 @@ class Make(object): self.builddir_join('qthelp', proj_name)) def build_devhelp(self): + # type: () -> int if self.run_generic_build('devhelp') > 0: return 1 print() @@ -146,12 +158,14 @@ class Make(object): print("$ devhelp") def build_epub(self): + # type: () -> int if self.run_generic_build('epub') > 0: return 1 print() print('Build finished. The ePub file is in %s.' % self.builddir_join('epub')) def build_latex(self): + # type: () -> int if self.run_generic_build('latex') > 0: return 1 print("Build finished; the LaTeX files are in %s." % self.builddir_join('latex')) @@ -160,24 +174,28 @@ class Make(object): print("(use `make latexpdf' here to do that automatically).") def build_latexpdf(self): + # type: () -> int if self.run_generic_build('latex') > 0: return 1 with cd(self.builddir_join('latex')): os.system('%s all-pdf' % self.makecmd) def build_latexpdfja(self): + # type: () -> int if self.run_generic_build('latex') > 0: return 1 with cd(self.builddir_join('latex')): os.system('%s all-pdf-ja' % self.makecmd) def build_text(self): + # type: () -> int if self.run_generic_build('text') > 0: return 1 print() print('Build finished. The text files are in %s.' % self.builddir_join('text')) def build_texinfo(self): + # type: () -> int if self.run_generic_build('texinfo') > 0: return 1 print("Build finished; the Texinfo files are in %s." % @@ -187,12 +205,14 @@ class Make(object): print("(use `make info' here to do that automatically).") def build_info(self): + # type: () -> int if self.run_generic_build('texinfo') > 0: return 1 with cd(self.builddir_join('texinfo')): os.system('%s info' % self.makecmd) def build_gettext(self): + # type: () -> int dtdir = self.builddir_join('gettext', '.doctrees') if self.run_generic_build('gettext', doctreedir=dtdir) > 0: return 1 @@ -201,6 +221,7 @@ class Make(object): self.builddir_join('gettext')) def build_changes(self): + # type: () -> int if self.run_generic_build('changes') > 0: return 1 print() @@ -208,6 +229,7 @@ class Make(object): self.builddir_join('changes')) def build_linkcheck(self): + # type: () -> int res = self.run_generic_build('linkcheck') print() print('Link check complete; look for any errors in the above output ' @@ -215,12 +237,14 @@ class Make(object): return res def build_doctest(self): + # type: () -> int res = self.run_generic_build('doctest') print("Testing of doctests in the sources finished, look at the " "results in %s." % self.builddir_join('doctest', 'output.txt')) return res def build_coverage(self): + # type: () -> int if self.run_generic_build('coverage') > 0: print("Has the coverage extension been enabled?") return 1 @@ -229,12 +253,14 @@ class Make(object): "results in %s." % self.builddir_join('coverage')) def build_xml(self): + # type: () -> int if self.run_generic_build('xml') > 0: return 1 print() print('Build finished. The XML files are in %s.' % self.builddir_join('xml')) def build_pseudoxml(self): + # type: () -> int if self.run_generic_build('pseudoxml') > 0: return 1 print() @@ -242,11 +268,12 @@ class Make(object): self.builddir_join('pseudoxml')) def run_generic_build(self, builder, doctreedir=None): + # type: (unicode, unicode) -> int # compatibility with old Makefile papersize = os.getenv('PAPER', '') opts = self.opts if papersize in ('a4', 'letter'): - opts.extend(['-D', 'latex_paper_size=' + papersize]) + opts.extend(['-D', 'latex_elements.papersize=' + papersize]) if doctreedir is None: doctreedir = self.builddir_join('doctrees') @@ -262,11 +289,12 @@ class Make(object): # linux, mac: 'sphinx-build' or 'sphinx-build.py' cmd = [sys.executable, orig_cmd] - return call(cmd + ['-b', builder] + opts + - ['-d', doctreedir, self.srcdir, self.builddir_join(builder)]) + return call(cmd + ['-b', builder] + opts + # type: ignore + ['-d', doctreedir, self.srcdir, self.builddir_join(builder)]) # type: ignore # NOQA def run_make_mode(args): + # type: (List[unicode]) -> int if len(args) < 3: print('Error: at least 3 arguments (builder, source ' 'dir, build dir) are required.', file=sys.stderr) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index baf5c0068..2c898560b 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -24,6 +24,10 @@ from sphinx.util import get_module_source, detect_encoding from sphinx.util.pycompat import TextIOWrapper from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc +if False: + # For type annotation + from typing import Any, Tuple # NOQA + # load the Python grammar _grammarfile = path.join(package_dir, 'pycode', @@ -63,10 +67,10 @@ class AttrDocVisitor(nodes.NodeVisitor): self.scope = scope self.in_init = 0 self.encoding = encoding - self.namespace = [] - self.collected = {} + self.namespace = [] # type: List[unicode] + self.collected = {} # type: Dict[Tuple[unicode, unicode], unicode] self.tagnumber = 0 - self.tagorder = {} + self.tagorder = {} # type: Dict[unicode, int] def add_tag(self, name): name = '.'.join(self.namespace + [name]) @@ -102,10 +106,10 @@ class AttrDocVisitor(nodes.NodeVisitor): parent = node.parent idx = parent.children.index(node) + 1 while idx < len(parent): - if parent[idx].type == sym.SEMI: + if parent[idx].type == sym.SEMI: # type: ignore idx += 1 continue # skip over semicolon - if parent[idx].type == sym.NEWLINE: + if parent[idx].type == sym.NEWLINE: # type: ignore prefix = parent[idx].get_prefix() if not isinstance(prefix, text_type): prefix = prefix.decode(self.encoding) @@ -138,8 +142,8 @@ class AttrDocVisitor(nodes.NodeVisitor): prev = node.get_prev_sibling() if not prev: return - if prev.type == sym.simple_stmt and \ - prev[0].type == sym.expr_stmt and _eq in prev[0].children: + if (prev.type == sym.simple_stmt and # type: ignore + prev[0].type == sym.expr_stmt and _eq in prev[0].children): # type: ignore # need to "eval" the string because it's returned in its # original form docstring = literals.evalString(node[0].value, self.encoding) @@ -178,7 +182,7 @@ class AttrDocVisitor(nodes.NodeVisitor): class ModuleAnalyzer(object): # cache for analyzer objects -- caches both by module and file name - cache = {} + cache = {} # type: Dict[Tuple[unicode, unicode], Any] @classmethod def for_string(cls, string, modname, srcname='<string>'): @@ -240,14 +244,14 @@ class ModuleAnalyzer(object): self.source.seek(pos) # will be filled by tokenize() - self.tokens = None + self.tokens = None # type: List[unicode] # will be filled by parse() - self.parsetree = None + self.parsetree = None # type: Any # will be filled by find_attr_docs() - self.attr_docs = None - self.tagorder = None + self.attr_docs = None # type: List[unicode] + self.tagorder = None # type: Dict[unicode, int] # will be filled by find_tags() - self.tags = None + self.tags = None # type: List[unicode] def tokenize(self): """Generate tokens from the source.""" @@ -289,8 +293,8 @@ class ModuleAnalyzer(object): return self.tags self.tokenize() result = {} - namespace = [] - stack = [] + namespace = [] # type: List[unicode] + stack = [] # type: List[Tuple[unicode, unicode, unicode, int]] indent = 0 defline = False expect_indent = False @@ -301,7 +305,7 @@ class ModuleAnalyzer(object): if tokentup[0] not in ignore: yield tokentup tokeniter = tokeniter() - for type, tok, spos, epos, line in tokeniter: + for type, tok, spos, epos, line in tokeniter: # type: ignore if expect_indent and type != token.NL: if type != token.INDENT: # no suite -- one-line definition @@ -312,7 +316,7 @@ class ModuleAnalyzer(object): result[fullname] = (dtype, startline, endline - emptylines) expect_indent = False if tok in ('def', 'class'): - name = next(tokeniter)[1] + name = next(tokeniter)[1] # type: ignore namespace.append(name) fullname = '.'.join(namespace) stack.append((tok, fullname, spos[0], indent)) diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py index ee40f3c0d..b6b3355c0 100644 --- a/sphinx/pycode/nodes.py +++ b/sphinx/pycode/nodes.py @@ -14,7 +14,7 @@ class BaseNode(object): """ Node superclass for both terminal and nonterminal nodes. """ - parent = None + parent = None # type: BaseNode def _eq(self, other): raise NotImplementedError @@ -29,7 +29,7 @@ class BaseNode(object): return NotImplemented return not self._eq(other) - __hash__ = None + __hash__ = None # type: str def get_prev_sibling(self): """Return previous child in parent's children, or None.""" @@ -204,5 +204,5 @@ class NodeVisitor(object): def generic_visit(self, node): """Called if no explicit visitor function exists for a node.""" if isinstance(node, Node): - for child in node: + for child in node: # type: ignore self.visit(child) diff --git a/sphinx/pycode/pgen2/grammar.py b/sphinx/pycode/pgen2/grammar.py index 42e6d72ee..cd6a435d5 100644 --- a/sphinx/pycode/pgen2/grammar.py +++ b/sphinx/pycode/pgen2/grammar.py @@ -19,6 +19,10 @@ import pickle # Local imports from sphinx.pycode.pgen2 import token +if False: + # For type annotation + from typing import Tuple # NOQA + class Grammar(object): """Pgen parsing tables tables conversion class. @@ -75,14 +79,14 @@ class Grammar(object): """ def __init__(self): - self.symbol2number = {} - self.number2symbol = {} - self.states = [] - self.dfas = {} + self.symbol2number = {} # type: Dict[unicode, int] + self.number2symbol = {} # type: Dict[int, unicode] + self.states = [] # type: List[List[List[Tuple[int, int]]]] + self.dfas = {} # type: Dict[int, Tuple[List[List[Tuple[int, int]]], unicode]] self.labels = [(0, "EMPTY")] - self.keywords = {} - self.tokens = {} - self.symbol2label = {} + self.keywords = {} # type: Dict[unicode, unicode] + self.tokens = {} # type: Dict[unicode, unicode] + self.symbol2label = {} # type: Dict[unicode, unicode] self.start = 256 def dump(self, filename): diff --git a/sphinx/pycode/pgen2/parse.py b/sphinx/pycode/pgen2/parse.py index 60eec05ea..43b88b519 100644 --- a/sphinx/pycode/pgen2/parse.py +++ b/sphinx/pycode/pgen2/parse.py @@ -13,6 +13,10 @@ how this parsing engine works. # Local imports from sphinx.pycode.pgen2 import token +if False: + # For type annotation + from typing import Any, Tuple # NOQA + class ParseError(Exception): """Exception to signal the parser is stuck.""" @@ -104,11 +108,12 @@ class Parser(object): # Each stack entry is a tuple: (dfa, state, node). # A node is a tuple: (type, value, context, children), # where children is a list of nodes or None, and context may be None. - newnode = (start, None, None, []) + newnode = (start, None, None, []) # type: Tuple[unicode, unicode, unicode, List] stackentry = (self.grammar.dfas[start], 0, newnode) self.stack = [stackentry] - self.rootnode = None - self.used_names = set() # Aliased to self.rootnode.used_names in pop() + self.rootnode = None # type: Any + self.used_names = set() # type: Set[unicode] + # Aliased to self.rootnode.used_names in pop() def addtoken(self, type, value, context): """Add a token; return True iff this is the end of the program.""" @@ -175,7 +180,7 @@ class Parser(object): def shift(self, type, value, newstate, context): """Shift a token. (Internal)""" dfa, state, node = self.stack[-1] - newnode = (type, value, context, None) + newnode = (type, value, context, None) # type: Tuple[unicode, unicode, unicode, List] newnode = self.convert(self.grammar, newnode) if newnode is not None: node[-1].append(newnode) @@ -184,7 +189,7 @@ class Parser(object): def push(self, type, newdfa, newstate, context): """Push a nonterminal. (Internal)""" dfa, state, node = self.stack[-1] - newnode = (type, None, context, []) + newnode = (type, None, context, []) # type: Tuple[unicode, unicode, unicode, List] self.stack[-1] = (dfa, newstate, node) self.stack.append((newdfa, 0, newnode)) diff --git a/sphinx/pycode/pgen2/pgen.py b/sphinx/pycode/pgen2/pgen.py index 7598e6abc..3fe91e57e 100644 --- a/sphinx/pycode/pgen2/pgen.py +++ b/sphinx/pycode/pgen2/pgen.py @@ -7,9 +7,13 @@ from six import iteritems from collections import OrderedDict # Pgen imports - from sphinx.pycode.pgen2 import grammar, token, tokenize +if False: + # For type annotation + from typing import Any, Tuple # NOQA + + class PgenGrammar(grammar.Grammar): pass @@ -27,7 +31,8 @@ class ParserGenerator(object): self.dfas, self.startsymbol = self.parse() if close_stream is not None: close_stream() - self.first = {} # map from symbol name to set of tokens + self.first = {} # type: Dict[unicode, List[unicode]] + # map from symbol name to set of tokens self.addfirstsets() def make_grammar(self): @@ -42,7 +47,7 @@ class ParserGenerator(object): c.number2symbol[i] = name for name in names: dfa = self.dfas[name] - states = [] + states = [] # type: List[List[Tuple[int, int]]] for state in dfa: arcs = [] for label, next in iteritems(state.arcs): @@ -122,7 +127,7 @@ class ParserGenerator(object): dfa = self.dfas[name] self.first[name] = None # dummy to detect left recursion state = dfa[0] - totalset = {} + totalset = {} # type: Dict[unicode, int] overlapcheck = {} for label, next in iteritems(state.arcs): if label in self.dfas: @@ -138,7 +143,7 @@ class ParserGenerator(object): else: totalset[label] = 1 overlapcheck[label] = {label: 1} - inverse = {} + inverse = {} # type: Dict[unicode, unicode] for label, itsfirst in sorted(overlapcheck.items()): for symbol in sorted(itsfirst): if symbol in inverse: @@ -180,7 +185,7 @@ class ParserGenerator(object): assert isinstance(start, NFAState) assert isinstance(finish, NFAState) def closure(state): - base = {} + base = {} # type: Dict addclosure(state, base) return base def addclosure(state, base): @@ -188,12 +193,12 @@ class ParserGenerator(object): if state in base: return base[state] = 1 - for label, next in state.arcs: + for label, next in state.arcs: # type: ignore if label is None: addclosure(next, base) states = [DFAState(closure(start), finish)] for state in states: # NB states grows while we're iterating - arcs = {} + arcs = {} # type: Dict[unicode, Dict] for nfastate in state.nfaset: for label, next in nfastate.arcs: if label is not None: @@ -343,7 +348,8 @@ class ParserGenerator(object): class NFAState(object): def __init__(self): - self.arcs = [] # list of (label, NFAState) pairs + self.arcs = [] # type: List[Tuple[unicode, Any]] + # list of (label, NFAState) pairs def addarc(self, next, label=None): assert label is None or isinstance(label, str) @@ -361,7 +367,8 @@ class DFAState(object): assert isinstance(final, NFAState) self.nfaset = nfaset self.isfinal = final in nfaset - self.arcs = OrderedDict() # map from label to DFAState + self.arcs = OrderedDict() # type: OrderedDict + # map from label to DFAState def __hash__(self): return hash(tuple(self.arcs)) diff --git a/sphinx/pycode/pgen2/tokenize.py b/sphinx/pycode/pgen2/tokenize.py index c7013bf91..a096795f8 100644 --- a/sphinx/pycode/pgen2/tokenize.py +++ b/sphinx/pycode/pgen2/tokenize.py @@ -183,7 +183,7 @@ def tokenize_loop(readline, tokeneater): class Untokenizer: def __init__(self): - self.tokens = [] + self.tokens = [] # type: List[unicode] self.prev_row = 1 self.prev_col = 0 @@ -294,17 +294,17 @@ def generate_tokens(readline): if contstr: # continued string if not line: - raise TokenError("EOF in multi-line string", strstart) - endmatch = endprog.match(line) + raise TokenError("EOF in multi-line string", strstart) # type: ignore + endmatch = endprog.match(line) # type: ignore if endmatch: pos = end = endmatch.end(0) - yield (STRING, contstr + line[:end], - strstart, (lnum, end), contline + line) + yield (STRING, contstr + line[:end], # type: ignore + strstart, (lnum, end), contline + line) # type: ignore contstr, needcont = '', 0 contline = None elif needcont and line[-2:] != '\\\n' and line[-3:] != '\\\r\n': - yield (ERRORTOKEN, contstr + line, - strstart, (lnum, len(line)), contline) + yield (ERRORTOKEN, contstr + line, # type: ignore + strstart, (lnum, len(line)), contline) # type: ignore contstr = '' contline = None continue @@ -333,7 +333,7 @@ def generate_tokens(readline): yield (NL, line[nl_pos:], (lnum, nl_pos), (lnum, len(line)), line) else: - yield ((NL, COMMENT)[line[pos] == '#'], line[pos:], + yield ((NL, COMMENT)[line[pos] == '#'], line[pos:], # type: ignore (lnum, pos), (lnum, len(line)), line) continue diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 3c7ab3d97..eb5349ede 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -36,8 +36,9 @@ from docutils.utils import column_width from sphinx import __display_version__, package_dir from sphinx.util.osutil import make_filename -from sphinx.util.console import purple, bold, red, turquoise, \ - nocolor, color_terminal +from sphinx.util.console import ( # type: ignore + purple, bold, red, turquoise, nocolor, color_terminal +) from sphinx.util.template import SphinxRenderer from sphinx.util import texescape diff --git a/sphinx/roles.py b/sphinx/roles.py index 71bc83b2d..182a3db21 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -175,7 +175,7 @@ def indexmarkup_role(typ, rawtext, text, lineno, inliner, typ = env.config.default_role else: typ = typ.lower() - has_explicit_title, title, target = split_explicit_title(text) + has_explicit_title, title, target = split_explicit_title(text) # type: bool, unicode, unicode # NOQA title = utils.unescape(title) target = utils.unescape(target) targetid = 'index-%s' % env.new_serialno('index') @@ -186,7 +186,7 @@ def indexmarkup_role(typ, rawtext, text, lineno, inliner, indexnode['entries'] = [ ('single', _('Python Enhancement Proposals; PEP %s') % target, targetid, '', None)] - anchor = '' + anchor = '' # type: unicode anchorindex = target.find('#') if anchorindex > 0: target, anchor = target[:anchorindex], target[anchorindex:] diff --git a/sphinx/search/__init__.py b/sphinx/search/__init__.py index 8f2935227..aff6aec34 100644 --- a/sphinx/search/__init__.py +++ b/sphinx/search/__init__.py @@ -9,17 +9,25 @@ :license: BSD, see LICENSE for details. """ import re +from os import path from six import iteritems, itervalues, text_type, string_types from six.moves import cPickle as pickle + from docutils.nodes import raw, comment, title, Text, NodeVisitor, SkipNode -from os import path import sphinx from sphinx.util import jsdump, rpartition from sphinx.util.pycompat import htmlescape from sphinx.search.jssplitter import splitter_code +if False: + # For type annotation + from typing import Any, IO, Iterable, Tuple, Type # NOQA + from docutils import nodes # NOQA + from sphinx.environment import BuildEnvironment # NOQA + + class SearchLanguage(object): """ This class is the base class for search natural language preprocessors. If @@ -42,10 +50,10 @@ class SearchLanguage(object): This class is used to preprocess search word which Sphinx HTML readers type, before searching index. Default implementation does nothing. """ - lang = None - language_name = None - stopwords = set() - js_stemmer_rawcode = None + lang = None # type: unicode + language_name = None # type: unicode + stopwords = set() # type: Set[unicode] + js_stemmer_rawcode = None # type: unicode js_stemmer_code = """ /** * Dummy stemmer for languages without stemming rules. @@ -60,23 +68,27 @@ var Stemmer = function() { _word_re = re.compile(r'\w+(?u)') def __init__(self, options): + # type: (Dict) -> None self.options = options self.init(options) def init(self, options): + # type: (Dict) -> None """ Initialize the class with the options the user has given. """ def split(self, input): + # type: (unicode) -> List[unicode] """ This method splits a sentence into words. Default splitter splits input at white spaces, which should be enough for most languages except CJK languages. """ - return self._word_re.findall(input) + return self._word_re.findall(input) # type: ignore def stem(self, word): + # type: (unicode) -> unicode """ This method implements stemming algorithm of the Python version. @@ -90,6 +102,7 @@ var Stemmer = function() { return word def word_filter(self, word): + # type: (unicode) -> bool """ Return true if the target word should be registered in the search index. This method is called after stemming. @@ -107,6 +120,7 @@ from sphinx.search.en import SearchEnglish def parse_stop_word(source): + # type: (unicode) -> Set[unicode] """ parse snowball style word list like this: @@ -138,7 +152,7 @@ languages = { 'sv': 'sphinx.search.sv.SearchSwedish', 'tr': 'sphinx.search.tr.SearchTurkish', 'zh': 'sphinx.search.zh.SearchChinese', -} +} # type: Dict[unicode, Any] class _JavaScriptIndex(object): @@ -151,9 +165,11 @@ class _JavaScriptIndex(object): SUFFIX = ')' def dumps(self, data): + # type: (Any) -> unicode return self.PREFIX + jsdump.dumps(data) + self.SUFFIX def loads(self, s): + # type: (str) -> Any data = s[len(self.PREFIX):-len(self.SUFFIX)] if not data or not s.startswith(self.PREFIX) or not \ s.endswith(self.SUFFIX): @@ -161,9 +177,11 @@ class _JavaScriptIndex(object): return jsdump.loads(data) def dump(self, data, f): + # type: (Any, IO) -> None f.write(self.dumps(data)) def load(self, f): + # type: (IO) -> Any return self.loads(f.read()) @@ -176,12 +194,14 @@ class WordCollector(NodeVisitor): """ def __init__(self, document, lang): + # type: (nodes.Node, SearchLanguage) -> None NodeVisitor.__init__(self, document) - self.found_words = [] - self.found_title_words = [] + self.found_words = [] # type: List[unicode] + self.found_title_words = [] # type: List[unicode] self.lang = lang def is_meta_keywords(self, node, nodetype): + # type: (nodes.Node, Type) -> bool if isinstance(node, sphinx.addnodes.meta) and node.get('name') == 'keywords': meta_lang = node.get('lang') if meta_lang is None: # lang not specified @@ -192,6 +212,7 @@ class WordCollector(NodeVisitor): return False def dispatch_visit(self, node): + # type: (nodes.Node) -> None nodetype = type(node) if issubclass(nodetype, comment): raise SkipNode @@ -223,28 +244,29 @@ class IndexBuilder(object): formats = { 'jsdump': jsdump, 'pickle': pickle - } + } # type: Dict[unicode, Any] def __init__(self, env, lang, options, scoring): + # type: (BuildEnvironment, unicode, Dict, unicode) -> None self.env = env - # docname -> title - self._titles = {} - # docname -> filename - self._filenames = {} - # stemmed word -> set(docname) - self._mapping = {} - # stemmed words in titles -> set(docname) - self._title_mapping = {} - # word -> stemmed word - self._stem_cache = {} - # objtype -> index - self._objtypes = {} - # objtype index -> (domain, type, objname (localized)) - self._objnames = {} - # add language-specific SearchLanguage instance - lang_class = languages.get(lang) + self._titles = {} # type: Dict[unicode, unicode] + # docname -> title + self._filenames = {} # type: Dict[unicode, unicode] + # docname -> filename + self._mapping = {} # type: Dict[unicode, Set[unicode]] + # stemmed word -> set(docname) + self._title_mapping = {} # type: Dict[unicode, Set[unicode]] + # stemmed words in titles -> set(docname) + self._stem_cache = {} # type: Dict[unicode, unicode] + # word -> stemmed word + self._objtypes = {} # type: Dict[Tuple[unicode, unicode], int] + # objtype -> index + self._objnames = {} # type: Dict[int, Tuple[unicode, unicode, unicode]] + # objtype index -> (domain, type, objname (localized)) + lang_class = languages.get(lang) # type: Type[SearchLanguage] + # add language-specific SearchLanguage instance if lang_class is None: - self.lang = SearchEnglish(options) + self.lang = SearchEnglish(options) # type: SearchLanguage elif isinstance(lang_class, str): module, classname = lang_class.rsplit('.', 1) lang_class = getattr(__import__(module, None, None, [classname]), @@ -262,9 +284,10 @@ class IndexBuilder(object): self.js_splitter_code = splitter_code def load(self, stream, format): + # type: (IO, Any) -> None """Reconstruct from frozen data.""" if isinstance(format, string_types): - format = self.formats[format] + format = self.formats[format] # type: ignore frozen = format.load(stream) # if an old index is present, we treat it as not existing. if not isinstance(frozen, dict) or \ @@ -274,6 +297,7 @@ class IndexBuilder(object): self._titles = dict(zip(index2fn, frozen['titles'])) def load_terms(mapping): + # type: (Dict[unicode, Any]) -> Dict[unicode, Set[unicode]] rv = {} for k, v in iteritems(mapping): if isinstance(v, int): @@ -287,13 +311,15 @@ class IndexBuilder(object): # no need to load keywords/objtypes def dump(self, stream, format): + # type: (IO, Any) -> None """Dump the frozen index to a stream.""" if isinstance(format, string_types): - format = self.formats[format] - format.dump(self.freeze(), stream) + format = self.formats[format] # type: ignore + format.dump(self.freeze(), stream) # type: ignore def get_objects(self, fn2index): - rv = {} + # type: (Dict[unicode, int]) -> Dict[unicode, Dict[unicode, Tuple[int, int, int, unicode]]] # NOQA + rv = {} # type: Dict[unicode, Dict[unicode, Tuple[int, int, int, unicode]]] otypes = self._objtypes onames = self._objnames for domainname, domain in sorted(iteritems(self.env.domains)): @@ -320,7 +346,7 @@ class IndexBuilder(object): else: onames[typeindex] = (domainname, type, type) if anchor == fullname: - shortanchor = '' + shortanchor = '' # type: unicode elif anchor == type + '-' + fullname: shortanchor = '-' else: @@ -329,7 +355,8 @@ class IndexBuilder(object): return rv def get_terms(self, fn2index): - rvs = {}, {} + # type: (Dict) -> Tuple[Dict[unicode, List[unicode]], Dict[unicode, List[unicode]]] + rvs = {}, {} # type: Tuple[Dict[unicode, List[unicode]], Dict[unicode, List[unicode]]] for rv, mapping in zip(rvs, (self._mapping, self._title_mapping)): for k, v in iteritems(mapping): if len(v) == 1: @@ -341,6 +368,7 @@ class IndexBuilder(object): return rvs def freeze(self): + # type: () -> Dict[unicode, Any] """Create a usable data structure for serializing.""" docnames, titles = zip(*sorted(self._titles.items())) filenames = [self._filenames.get(docname) for docname in docnames] @@ -356,9 +384,11 @@ class IndexBuilder(object): titleterms=title_terms, envversion=self.env.version) def label(self): + # type: () -> unicode return "%s (code: %s)" % (self.lang.language_name, self.lang.lang) def prune(self, filenames): + # type: (Iterable[unicode]) -> None """Remove data for all filenames not in the list.""" new_titles = {} for filename in filenames: @@ -371,6 +401,7 @@ class IndexBuilder(object): wordnames.intersection_update(filenames) def feed(self, docname, filename, title, doctree): + # type: (unicode, unicode, unicode, nodes.Node) -> None """Feed a doctree to the index.""" self._titles[docname] = title self._filenames[docname] = filename @@ -380,6 +411,7 @@ class IndexBuilder(object): # memoize self.lang.stem def stem(word): + # type: (unicode) -> unicode try: return self._stem_cache[word] except KeyError: @@ -399,11 +431,12 @@ class IndexBuilder(object): # again, stemmer must not remove words from search index if not _filter(stemmed_word) and _filter(word): stemmed_word = word - already_indexed = docname in self._title_mapping.get(stemmed_word, []) + already_indexed = docname in self._title_mapping.get(stemmed_word, set()) if _filter(stemmed_word) and not already_indexed: self._mapping.setdefault(stemmed_word, set()).add(docname) def context_for_searchtool(self): + # type: () -> Dict[unicode, Any] return dict( search_language_stemming_code = self.lang.js_stemmer_code, search_language_stop_words = jsdump.dumps(sorted(self.lang.stopwords)), @@ -412,6 +445,7 @@ class IndexBuilder(object): ) def get_js_stemmer_rawcode(self): + # type: () -> unicode if self.lang.js_stemmer_rawcode: return path.join( sphinx.package_dir, 'search', diff --git a/sphinx/search/en.py b/sphinx/search/en.py index d5259bed7..c6658ffdc 100644 --- a/sphinx/search/en.py +++ b/sphinx/search/en.py @@ -10,13 +10,7 @@ """ from sphinx.search import SearchLanguage - -try: - from Stemmer import Stemmer as PyStemmer - PYSTEMMER = True -except ImportError: - from sphinx.util.stemmer import PorterStemmer - PYSTEMMER = False +from sphinx.util.stemmer import get_stemmer english_stopwords = set(""" a and are as at @@ -224,22 +218,9 @@ class SearchEnglish(SearchLanguage): stopwords = english_stopwords def init(self, options): - if PYSTEMMER: - class Stemmer(object): - def __init__(self): - self.stemmer = PyStemmer('porter') - - def stem(self, word): - return self.stemmer.stemWord(word) - else: - class Stemmer(PorterStemmer): - """All those porter stemmer implementations look hideous; - make at least the stem method nicer. - """ - def stem(self, word): - return PorterStemmer.stem(self, word, 0, len(word) - 1) - - self.stemmer = Stemmer() + # type: (Dict) -> None + self.stemmer = get_stemmer() def stem(self, word): + # type: (unicode) -> unicode return self.stemmer.stem(word.lower()) diff --git a/sphinx/search/ja.py b/sphinx/search/ja.py index 0d4d01b9c..cf3b67c00 100644 --- a/sphinx/search/ja.py +++ b/sphinx/search/ja.py @@ -43,9 +43,11 @@ from sphinx.util import import_object class BaseSplitter(object): def __init__(self, options): + # type: (Dict) -> None self.options = options def split(self, input): + # type: (unicode) -> List[unicode] """ :param str input: @@ -57,9 +59,10 @@ class BaseSplitter(object): class MecabSplitter(BaseSplitter): def __init__(self, options): + # type: (Dict) -> None super(MecabSplitter, self).__init__(options) - self.ctypes_libmecab = None - self.ctypes_mecab = None + self.ctypes_libmecab = None # type: ignore + self.ctypes_mecab = None # type: ignore if not native_module: self.init_ctypes(options) else: @@ -67,6 +70,7 @@ class MecabSplitter(BaseSplitter): self.dict_encode = options.get('dic_enc', 'utf-8') def split(self, input): + # type: (unicode) -> List[unicode] input2 = input if PY3 else input.encode(self.dict_encode) if native_module: result = self.native.parse(input2) @@ -79,6 +83,7 @@ class MecabSplitter(BaseSplitter): return result.decode(self.dict_encode).split(' ') def init_native(self, options): + # type: (Dict) -> None param = '-Owakati' dict = options.get('dict') if dict: @@ -86,6 +91,7 @@ class MecabSplitter(BaseSplitter): self.native = MeCab.Tagger(param) def init_ctypes(self, options): + # type: (Dict) -> None import ctypes.util lib = options.get('lib') @@ -122,6 +128,7 @@ class MecabSplitter(BaseSplitter): raise SphinxError('mecab initialization failed') def __del__(self): + # type: () -> None if self.ctypes_libmecab: self.ctypes_libmecab.mecab_destroy(self.ctypes_mecab) @@ -130,17 +137,20 @@ MeCabBinder = MecabSplitter # keep backward compatibility until Sphinx-1.6 class JanomeSplitter(BaseSplitter): def __init__(self, options): + # type: (Dict) -> None super(JanomeSplitter, self).__init__(options) self.user_dict = options.get('user_dic') self.user_dict_enc = options.get('user_dic_enc', 'utf8') self.init_tokenizer() def init_tokenizer(self): + # type: () -> None if not janome_module: raise RuntimeError('Janome is not available') self.tokenizer = janome.tokenizer.Tokenizer(udic=self.user_dict, udic_enc=self.user_dict_enc) def split(self, input): + # type: (unicode) -> List[unicode] result = u' '.join(token.surface for token in self.tokenizer.tokenize(input)) return result.split(u' ') @@ -417,6 +427,7 @@ class DefaultSplitter(BaseSplitter): # ctype_ def ctype_(self, char): + # type: (unicode) -> unicode for pattern, value in iteritems(self.patterns_): if pattern.match(char): return value @@ -424,12 +435,14 @@ class DefaultSplitter(BaseSplitter): # ts_ def ts_(self, dict, key): + # type: (Dict[unicode, int], unicode) -> int if key in dict: return dict[key] return 0 # segment def split(self, input): + # type: (unicode) -> List[unicode] if not input: return [] @@ -538,6 +551,7 @@ class SearchJapanese(SearchLanguage): } def init(self, options): + # type: (Dict) -> None type = options.get('type', 'default') if type in self.splitters: dotted_path = self.splitters[type] @@ -550,10 +564,13 @@ class SearchJapanese(SearchLanguage): dotted_path) def split(self, input): + # type: (unicode) -> List[unicode] return self.splitter.split(input) def word_filter(self, stemmed_word): + # type: (unicode) -> bool return len(stemmed_word) > 1 def stem(self, word): + # type: (unicode) -> unicode return word diff --git a/sphinx/search/ro.py b/sphinx/search/ro.py index 78ae01851..f44f38e34 100644 --- a/sphinx/search/ro.py +++ b/sphinx/search/ro.py @@ -24,10 +24,12 @@ class SearchRomanian(SearchLanguage): language_name = 'Romanian' js_stemmer_rawcode = 'romanian-stemmer.js' js_stemmer_code = js_stemmer - stopwords = [] + stopwords = [] # type: List[unicode] def init(self, options): + # type: (Dict) -> None self.stemmer = snowballstemmer.stemmer('romanian') def stem(self, word): + # type: (unicode) -> unicode return self.stemmer.stemWord(word) diff --git a/sphinx/search/tr.py b/sphinx/search/tr.py index 33c5c5192..14cc710f8 100644 --- a/sphinx/search/tr.py +++ b/sphinx/search/tr.py @@ -24,10 +24,12 @@ class SearchTurkish(SearchLanguage): language_name = 'Turkish' js_stemmer_rawcode = 'turkish-stemmer.js' js_stemmer_code = js_stemmer - stopwords = [] + stopwords = [] # type: List[unicode] def init(self, options): + # type: (Dict) -> None self.stemmer = snowballstemmer.stemmer('turkish') def stem(self, word): + # type: (unicode) -> unicode return self.stemmer.stemWord(word) diff --git a/sphinx/search/zh.py b/sphinx/search/zh.py index c1fecefc6..520dd6493 100644 --- a/sphinx/search/zh.py +++ b/sphinx/search/zh.py @@ -13,13 +13,7 @@ import os import re from sphinx.search import SearchLanguage - -try: - from Stemmer import Stemmer as PyStemmer - PYSTEMMER = True -except ImportError: - from sphinx.util.stemmer import PorterStemmer - PYSTEMMER = False +from sphinx.util.stemmer import get_stemmer try: import jieba @@ -238,38 +232,27 @@ class SearchChinese(SearchLanguage): latin1_letters = re.compile(r'\w+(?u)[\u0000-\u00ff]') def init(self, options): + # type: (Dict) -> None if JIEBA: dict_path = options.get('dict') if dict_path and os.path.isfile(dict_path): jieba.set_dictionary(dict_path) - if PYSTEMMER: - class Stemmer(object): - def __init__(self): - self.stemmer = PyStemmer('porter') - - def stem(self, word): - return self.stemmer.stemWord(word) - else: - class Stemmer(PorterStemmer): - """All those porter stemmer implementations look hideous; - make at least the stem method nicer. - """ - def stem(self, word): - return PorterStemmer.stem(self, word, 0, len(word) - 1) - - self.stemmer = Stemmer() + self.stemmer = get_stemmer() def split(self, input): - chinese = [] + # type: (unicode) -> List[unicode] + chinese = [] # type: List[unicode] if JIEBA: chinese = list(jieba.cut_for_search(input)) - latin1 = self.latin1_letters.findall(input) + latin1 = self.latin1_letters.findall(input) # type: ignore return chinese + latin1 def word_filter(self, stemmed_word): + # type: (unicode) -> bool return len(stemmed_word) > 1 def stem(self, word): + # type: (unicode) -> unicode return self.stemmer.stem(word) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index 0c49b0e89..ca0cdd88a 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -18,7 +18,7 @@ import os from six import StringIO, string_types from distutils.cmd import Command -from distutils.errors import DistutilsOptionError, DistutilsExecError +from distutils.errors import DistutilsOptionError, DistutilsExecError # type: ignore from sphinx.application import Sphinx from sphinx.cmdline import handle_exception @@ -26,6 +26,10 @@ from sphinx.util.console import nocolor, color_terminal from sphinx.util.docutils import docutils_namespace from sphinx.util.osutil import abspath +if False: + # For type annotation + from typing import Any # NOQA + class BuildDoc(Command): """ @@ -87,22 +91,24 @@ class BuildDoc(Command): 'link-index'] def initialize_options(self): + # type: () -> None self.fresh_env = self.all_files = False self.pdb = False - self.source_dir = self.build_dir = None + self.source_dir = self.build_dir = None # type: unicode self.builder = 'html' self.warning_is_error = False self.project = '' self.version = '' self.release = '' self.today = '' - self.config_dir = None + self.config_dir = None # type: unicode self.link_index = False self.copyright = '' self.verbosity = 0 self.traceback = False def _guess_source_dir(self): + # type: () -> unicode for guess in ('doc', 'docs'): if not os.path.isdir(guess): continue @@ -115,6 +121,7 @@ class BuildDoc(Command): # unicode, causing finalize_options to fail if invoked again. Workaround # for http://bugs.python.org/issue19570 def _ensure_stringlike(self, option, what, default=None): + # type: (unicode, unicode, Any) -> Any val = getattr(self, option) if val is None: setattr(self, option, default) @@ -125,10 +132,11 @@ class BuildDoc(Command): return val def finalize_options(self): + # type: () -> None if self.source_dir is None: self.source_dir = self._guess_source_dir() - self.announce('Using source directory %s' % self.source_dir) - self.ensure_dirname('source_dir') + self.announce('Using source directory %s' % self.source_dir) # type: ignore + self.ensure_dirname('source_dir') # type: ignore if self.source_dir is None: self.source_dir = os.curdir self.source_dir = abspath(self.source_dir) @@ -137,22 +145,23 @@ class BuildDoc(Command): self.config_dir = abspath(self.config_dir) if self.build_dir is None: - build = self.get_finalized_command('build') + build = self.get_finalized_command('build') # type: ignore self.build_dir = os.path.join(abspath(build.build_base), 'sphinx') - self.mkpath(self.build_dir) + self.mkpath(self.build_dir) # type: ignore self.build_dir = abspath(self.build_dir) self.doctree_dir = os.path.join(self.build_dir, 'doctrees') - self.mkpath(self.doctree_dir) + self.mkpath(self.doctree_dir) # type: ignore self.builder_target_dir = os.path.join(self.build_dir, self.builder) - self.mkpath(self.builder_target_dir) + self.mkpath(self.builder_target_dir) # type: ignore def run(self): + # type: () -> None if not color_terminal(): nocolor() - if not self.verbose: + if not self.verbose: # type: ignore status_stream = StringIO() else: - status_stream = sys.stdout + status_stream = sys.stdout # type: ignore confoverrides = {} if self.project: confoverrides['project'] = self.project @@ -183,6 +192,6 @@ class BuildDoc(Command): raise SystemExit(1) if self.link_index: - src = app.config.master_doc + app.builder.out_suffix - dst = app.builder.get_outfilename('index') + src = app.config.master_doc + app.builder.out_suffix # type: ignore + dst = app.builder.get_outfilename('index') # type: ignore os.symlink(src, dst) diff --git a/sphinx/templates/quickstart/make.bat_t b/sphinx/templates/quickstart/make.bat_t index 8f993a7b1..8438b5f7e 100644 --- a/sphinx/templates/quickstart/make.bat_t +++ b/sphinx/templates/quickstart/make.bat_t @@ -11,8 +11,8 @@ set BUILDDIR={{ rbuilddir }} set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% {{ rsrcdir }} set I18NSPHINXOPTS=%SPHINXOPTS% {{ rsrcdir }} if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% + set ALLSPHINXOPTS=-D latex_elements.papersize=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_elements.papersize=%PAPER% %I18NSPHINXOPTS% ) if "%1" == "" goto help diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 8d43661ba..cc85ef935 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,7 +6,7 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2016/12/14 v1.5.2 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2016/12/14 v1.6 LaTeX package (Sphinx markup)] % we delay handling of options to after having loaded packages, because % of the need to use \definecolor. @@ -894,33 +894,25 @@ \raggedright} {\end{list}} -% Redefine \includegraphics to resize images larger than the line width, +% \sphinxincludegraphics defined to resize images larger than the line width, % except if height or width option present. % % If scale is present, rescale before fitting to line width. (since 1.5) -% -% Warning: future version of Sphinx will not modify original \includegraphics, -% below code will be definition only of \sphinxincludegraphics. -\let\py@Oldincludegraphics\includegraphics \newbox\spx@image@box -\renewcommand*{\includegraphics}[2][]{% +\newcommand*{\sphinxincludegraphics}[2][]{% \in@{height}{#1}\ifin@\else\in@{width}{#1}\fi \ifin@ % height or width present - \py@Oldincludegraphics[#1]{#2}% + \includegraphics[#1]{#2}% \else % no height nor width (but #1 may be "scale=...") - \setbox\spx@image@box\hbox{\py@Oldincludegraphics[#1,draft]{#2}}% + \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}% \ifdim \wd\spx@image@box>\linewidth \setbox\spx@image@box\box\voidb@x % clear memory - \py@Oldincludegraphics[#1,width=\linewidth]{#2}% + \includegraphics[#1,width=\linewidth]{#2}% \else - \py@Oldincludegraphics[#1]{#2}% + \includegraphics[#1]{#2}% \fi \fi } -% Writer will put \sphinxincludegraphics in LaTeX source, and with this, -% documents which used their own modified \includegraphics will compile -% as before. But see warning above. -\newcommand*{\sphinxincludegraphics}{\includegraphics} % to make pdf with correct encoded bookmarks in Japanese % this should precede the hyperref package diff --git a/sphinx/themes/basic/defindex.html b/sphinx/themes/basic/defindex.html deleted file mode 100644 index 190680724..000000000 --- a/sphinx/themes/basic/defindex.html +++ /dev/null @@ -1,35 +0,0 @@ -{# - basic/defindex.html - ~~~~~~~~~~~~~~~~~~~ - - Default template for the "index" page. - - :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#}{{ warn('Now base template defindex.html is deprecated.') }} -{%- extends "layout.html" %} -{% set title = _('Overview') %} -{% block body %} - <h1>{{ docstitle|e }}</h1> - <p> - {{ _('Welcome! This is') }} - {% block description %}{{ _('the documentation for') }} {{ project|e }} - {{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}{% endblock %}. - </p> - {% block tables %} - <p><strong>{{ _('Indices and tables:') }}</strong></p> - <table class="contentstable"><tr> - <td style="width: 50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{{ _('Complete Table of Contents') }}</a><br> - <span class="linkdescr">{{ _('lists all sections and subsections') }}</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{{ _('Search Page') }}</a><br> - <span class="linkdescr">{{ _('search this documentation') }}</span></p> - </td><td style="width: 50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">{{ _('Global Module Index') }}</a><br> - <span class="linkdescr">{{ _('quick access to all modules') }}</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{{ _('General Index') }}</a><br> - <span class="linkdescr">{{ _('all functions, classes, terms') }}</span></p> - </td></tr> - </table> - {% endblock %} -{% endblock %} diff --git a/sphinx/themes/basic/static/basic.css_t b/sphinx/themes/basic/static/basic.css_t index d70003d42..c6a304f14 100644 --- a/sphinx/themes/basic/static/basic.css_t +++ b/sphinx/themes/basic/static/basic.css_t @@ -398,6 +398,13 @@ table.field-list td, table.field-list th { margin: 0; } +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + /* -- other body styles ----------------------------------------------------- */ ol.arabic { diff --git a/sphinx/theming.py b/sphinx/theming.py index 42e4448db..ec7867b3b 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -16,7 +16,8 @@ import tempfile from os import path from six import string_types, iteritems -from six.moves import configparser +from six.moves import configparser # type: ignore +from typing import Any, Callable, Tuple # NOQA try: import pkg_resources @@ -25,6 +26,13 @@ except ImportError: from sphinx import package_dir from sphinx.errors import ThemeError +from sphinx.util import logging + +logger = logging.getLogger(__name__) + +if False: + # For type annotation + from typing import Any, Callable, Tuple # NOQA NODEFAULT = object() THEMECONF = 'theme.conf' @@ -34,10 +42,12 @@ class Theme(object): """ Represents the theme chosen in the configuration. """ - themes = {} + themes = {} # type: Dict[unicode, Tuple[unicode, zipfile.ZipFile]] + themepath = [] # type: List[unicode] @classmethod - def init_themes(cls, confdir, theme_path, warn=None): + def init_themes(cls, confdir, theme_path): + # type: (unicode, unicode) -> None """Search all theme paths for available themes.""" cls.themepath = list(theme_path) cls.themepath.append(path.join(package_dir, 'themes')) @@ -49,15 +59,14 @@ class Theme(object): for theme in os.listdir(themedir): if theme.lower().endswith('.zip'): try: - zfile = zipfile.ZipFile(path.join(themedir, theme)) + zfile = zipfile.ZipFile(path.join(themedir, theme)) # type: ignore if THEMECONF not in zfile.namelist(): continue tname = theme[:-4] tinfo = zfile except Exception: - if warn: - warn('file %r on theme path is not a valid ' - 'zipfile or contains no theme' % theme) + logger.warning('file %r on theme path is not a valid ' + 'zipfile or contains no theme', theme) continue else: if not path.isfile(path.join(themedir, theme, THEMECONF)): @@ -68,6 +77,7 @@ class Theme(object): @classmethod def load_extra_theme(cls, name): + # type: (unicode) -> None themes = ['alabaster'] try: import sphinx_rtd_theme @@ -97,7 +107,8 @@ class Theme(object): cls.themes[name] = (path.join(themedir, name), None) return - def __init__(self, name, warn=None): + def __init__(self, name): + # type: (unicode) -> None if name not in self.themes: self.load_extra_theme(name) if name not in self.themes: @@ -153,9 +164,10 @@ class Theme(object): raise ThemeError('no theme named %r found, inherited by %r' % (inherit, name)) else: - self.base = Theme(inherit, warn=warn) + self.base = Theme(inherit) def get_confstr(self, section, name, default=NODEFAULT): + # type: (unicode, unicode, Any) -> Any """Return the value for a theme configuration setting, searching the base theme chain. """ @@ -171,13 +183,14 @@ class Theme(object): return default def get_options(self, overrides): + # type: (Dict) -> Any """Return a dictionary of theme options and their values.""" chain = [self.themeconf] base = self.base while base is not None: chain.append(base.themeconf) base = base.base - options = {} + options = {} # type: Dict[unicode, Any] for conf in reversed(chain): try: options.update(conf.items('options')) @@ -190,6 +203,7 @@ class Theme(object): return options def get_dirchain(self): + # type: () -> List[unicode] """Return a list of theme directories, beginning with this theme's, then the base theme's, then that one's base theme's, etc. """ @@ -201,6 +215,7 @@ class Theme(object): return chain def cleanup(self): + # type: () -> None """Remove temporary directories.""" if self.themedir_created: try: @@ -212,6 +227,7 @@ class Theme(object): def load_theme_plugins(): + # type: () -> List[unicode] """load plugins by using``sphinx_themes`` section in setuptools entry_points. This API will return list of directory that contain some theme directory. """ @@ -219,7 +235,7 @@ def load_theme_plugins(): if not pkg_resources: return [] - theme_paths = [] + theme_paths = [] # type: List[unicode] for plugin in pkg_resources.iter_entry_points('sphinx_themes'): func_or_path = plugin.load() @@ -229,7 +245,7 @@ def load_theme_plugins(): path = func_or_path if isinstance(path, string_types): - theme_paths.append(path) + theme_paths.append(path) # type: ignore else: raise ThemeError('Plugin %r does not response correctly.' % plugin.module_name) diff --git a/sphinx/transforms/__init__.py b/sphinx/transforms/__init__.py index 461d9117d..4eb65af6e 100644 --- a/sphinx/transforms/__init__.py +++ b/sphinx/transforms/__init__.py @@ -15,9 +15,13 @@ from docutils.transforms.parts import ContentsFilter from sphinx import addnodes from sphinx.locale import _ +from sphinx.util import logging from sphinx.util.i18n import format_date from sphinx.util.nodes import apply_source_workaround + +logger = logging.getLogger(__name__) + default_substitutions = set([ 'version', 'release', @@ -33,7 +37,7 @@ class DefaultSubstitutions(Transform): default_priority = 210 def apply(self): - env = self.document.settings.env + # type: () -> None config = self.document.settings.env.config # only handle those not otherwise defined in the document to_handle = default_substitutions - set(self.document.substitution_defs) @@ -44,7 +48,7 @@ class DefaultSubstitutions(Transform): if refname == 'today' and not text: # special handling: can also specify a strftime format text = format_date(config.today_fmt or _('%b %d, %Y'), - language=config.language, warn=env.warn) + language=config.language) ref.replace_self(nodes.Text(text, text)) @@ -58,6 +62,7 @@ class MoveModuleTargets(Transform): default_priority = 210 def apply(self): + # type: () -> None for node in self.document.traverse(nodes.target): if not node['ids']: continue @@ -76,6 +81,7 @@ class HandleCodeBlocks(Transform): default_priority = 210 def apply(self): + # type: () -> None # move doctest blocks out of blockquotes for node in self.document.traverse(nodes.block_quote): if all(isinstance(child, nodes.doctest_block) for child @@ -100,7 +106,8 @@ class AutoNumbering(Transform): default_priority = 210 def apply(self): - domain = self.document.settings.env.domains['std'] + # type: () -> None + domain = self.document.settings.env.get_domain('std') for node in self.document.traverse(nodes.Element): if domain.is_enumerable_node(node) and domain.get_numfig_title(node) is not None: @@ -114,6 +121,7 @@ class SortIds(Transform): default_priority = 261 def apply(self): + # type: () -> None for node in self.document.traverse(nodes.section): if len(node['ids']) > 1 and node['ids'][0].startswith('id'): node['ids'] = node['ids'][1:] + [node['ids'][0]] @@ -127,6 +135,7 @@ class CitationReferences(Transform): default_priority = 619 def apply(self): + # type: () -> None for citnode in self.document.traverse(nodes.citation_reference): cittext = citnode.astext() refnode = addnodes.pending_xref(cittext, refdomain='std', reftype='citation', @@ -154,6 +163,7 @@ class ApplySourceWorkaround(Transform): default_priority = 10 def apply(self): + # type: () -> None for n in self.document.traverse(): if isinstance(n, (nodes.TextElement, nodes.image)): apply_source_workaround(n) @@ -166,12 +176,12 @@ class AutoIndexUpgrader(Transform): default_priority = 210 def apply(self): - env = self.document.settings.env + # type: () -> None for node in self.document.traverse(addnodes.index): if 'entries' in node and any(len(entry) == 4 for entry in node['entries']): msg = ('4 column based index found. ' 'It might be a bug of extensions you use: %r' % node['entries']) - env.warn_node(msg, node) + logger.warning(msg, location=node) for i, entry in enumerate(node['entries']): if len(entry) == 4: node['entries'][i] = entry + (None,) @@ -184,12 +194,14 @@ class ExtraTranslatableNodes(Transform): default_priority = 10 def apply(self): + # type: () -> None targets = self.document.settings.env.config.gettext_additional_targets target_nodes = [v for k, v in TRANSLATABLE_NODES.items() if k in targets] if not target_nodes: return def is_translatable_node(node): + # type: (nodes.Node) -> bool return isinstance(node, tuple(target_nodes)) for node in self.document.traverse(is_translatable_node): @@ -201,11 +213,12 @@ class FilterSystemMessages(Transform): default_priority = 999 def apply(self): + # type: () -> None env = self.document.settings.env filterlevel = env.config.keep_warnings and 2 or 5 for node in self.document.traverse(nodes.system_message): if node['level'] < filterlevel: - env.app.debug('%s [filtered system message]', node.astext()) + logger.debug('%s [filtered system message]', node.astext()) node.parent.remove(node) @@ -215,9 +228,11 @@ class SphinxContentsFilter(ContentsFilter): within table-of-contents link nodes. """ def visit_pending_xref(self, node): + # type: (nodes.Node) -> None text = node.astext() self.parent.append(nodes.literal(text, text)) raise nodes.SkipNode def visit_image(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode diff --git a/sphinx/transforms/compact_bullet_list.py b/sphinx/transforms/compact_bullet_list.py index 61b23f382..0fe2e8b83 100644 --- a/sphinx/transforms/compact_bullet_list.py +++ b/sphinx/transforms/compact_bullet_list.py @@ -23,12 +23,15 @@ class RefOnlyListChecker(nodes.GenericNodeVisitor): """ def default_visit(self, node): + # type: (nodes.Node) -> None raise nodes.NodeFound def visit_bullet_list(self, node): + # type: (nodes.Node) -> None pass def visit_list_item(self, node): + # type: (nodes.Node) -> None children = [] for child in node.children: if not isinstance(child, nodes.Invisible): @@ -45,6 +48,7 @@ class RefOnlyListChecker(nodes.GenericNodeVisitor): raise nodes.SkipChildren def invisible_visit(self, node): + # type: (nodes.Node) -> None """Invisible nodes should be ignored.""" pass @@ -58,11 +62,13 @@ class RefOnlyBulletListTransform(Transform): default_priority = 100 def apply(self): + # type: () -> None env = self.document.settings.env if env.config.html_compact_lists: return def check_refonly_list(node): + # type: (nodes.Node) -> bool """Check for list with only references in it.""" visitor = RefOnlyListChecker(self.document) try: diff --git a/sphinx/transforms/i18n.py b/sphinx/transforms/i18n.py index 38c5aef25..8663c573d 100644 --- a/sphinx/transforms/i18n.py +++ b/sphinx/transforms/i18n.py @@ -17,7 +17,7 @@ from docutils.utils import relative_path from docutils.transforms import Transform from sphinx import addnodes -from sphinx.util import split_index_msg +from sphinx.util import split_index_msg, logging from sphinx.util.i18n import find_catalog from sphinx.util.nodes import ( LITERAL_TYPE_NODES, IMAGE_TYPE_NODES, @@ -27,8 +27,17 @@ from sphinx.util.pycompat import indent from sphinx.locale import init as init_locale from sphinx.domains.std import make_glossary_term, split_term_classifiers +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.config import Config # NOQA + +logger = logging.getLogger(__name__) + def publish_msgstr(app, source, source_path, source_line, config, settings): + # type: (Sphinx, unicode, unicode, int, Config, Dict) -> nodes.document """Publish msgstr (single line) into docutils document :param sphinx.application.Sphinx app: sphinx application @@ -66,6 +75,7 @@ class PreserveTranslatableMessages(Transform): default_priority = 10 # this MUST be invoked before Locale transform def apply(self): + # type: () -> None for node in self.document.traverse(addnodes.translatable): node.preserve_original_messages() @@ -77,6 +87,7 @@ class Locale(Transform): default_priority = 20 def apply(self): + # type: () -> None env = self.document.settings.env settings, source = self.document.settings, self.document['source'] # XXX check if this is reliable @@ -176,6 +187,7 @@ class Locale(Transform): # replace target's refname to new target name def is_named_target(node): + # type: (nodes.Node) -> bool return isinstance(node, nodes.target) and \ node.get('refname') == old_name for old_target in self.document.traverse(is_named_target): @@ -249,10 +261,12 @@ class Locale(Transform): # auto-numbered foot note reference should use original 'ids'. def is_autonumber_footnote_ref(node): + # type: (nodes.Node) -> bool return isinstance(node, nodes.footnote_reference) and \ node.get('auto') == 1 def list_replace_or_append(lst, old, new): + # type: (List, Any, Any) -> None if old in lst: lst[lst.index(old)] = new else: @@ -260,9 +274,9 @@ class Locale(Transform): old_foot_refs = node.traverse(is_autonumber_footnote_ref) new_foot_refs = patch.traverse(is_autonumber_footnote_ref) if len(old_foot_refs) != len(new_foot_refs): - env.warn_node('inconsistent footnote references in ' - 'translated message', node) - old_foot_namerefs = {} + logger.warning('inconsistent footnote references in translated message', + location=node) + old_foot_namerefs = {} # type: Dict[unicode, List[nodes.footnote_reference]] for r in old_foot_refs: old_foot_namerefs.setdefault(r.get('refname'), []).append(r) for new in new_foot_refs: @@ -295,8 +309,8 @@ class Locale(Transform): old_refs = node.traverse(is_refnamed_ref) new_refs = patch.traverse(is_refnamed_ref) if len(old_refs) != len(new_refs): - env.warn_node('inconsistent references in ' - 'translated message', node) + logger.warning('inconsistent references in translated message', + location=node) old_ref_names = [r['refname'] for r in old_refs] new_ref_names = [r['refname'] for r in new_refs] orphans = list(set(old_ref_names) - set(new_ref_names)) @@ -315,6 +329,7 @@ class Locale(Transform): # refnamed footnote and citation should use original 'ids'. def is_refnamed_footnote_ref(node): + # type: (nodes.Node) -> bool footnote_ref_classes = (nodes.footnote_reference, nodes.citation_reference) return isinstance(node, footnote_ref_classes) and \ @@ -323,8 +338,8 @@ class Locale(Transform): new_refs = patch.traverse(is_refnamed_footnote_ref) refname_ids_map = {} if len(old_refs) != len(new_refs): - env.warn_node('inconsistent references in ' - 'translated message', node) + logger.warning('inconsistent references in translated message', + location=node) for old in old_refs: refname_ids_map[old["refname"]] = old["ids"] for new in new_refs: @@ -339,10 +354,11 @@ class Locale(Transform): new_refs = patch.traverse(addnodes.pending_xref) xref_reftarget_map = {} if len(old_refs) != len(new_refs): - env.warn_node('inconsistent term references in ' - 'translated message', node) + logger.warning('inconsistent term references in translated message', + location=node) def get_ref_key(node): + # type: (nodes.Node) -> Tuple[unicode, unicode, unicode] case = node["refdomain"], node["reftype"] if case == ('std', 'term'): return None @@ -384,7 +400,7 @@ class Locale(Transform): if 'index' in env.config.gettext_additional_targets: # Extract and translate messages for index entries. for node, entries in traverse_translatable_index(self.document): - new_entries = [] + new_entries = [] # type: List[Tuple[unicode, unicode, unicode, unicode, unicode]] # NOQA for type, msg, tid, main, key_ in entries: msg_parts = split_index_msg(type, msg) msgstr_parts = [] @@ -407,6 +423,7 @@ class RemoveTranslatableInline(Transform): default_priority = 999 def apply(self): + # type: () -> None from sphinx.builders.gettext import MessageCatalogBuilder env = self.document.settings.env builder = env.app.builder diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index e650f7aa9..11e48b4a1 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -28,6 +28,7 @@ from six.moves.urllib.parse import urlsplit, urlunsplit, quote_plus, parse_qsl, from docutils.utils import relative_path from sphinx.errors import PycodeError, SphinxParallelError, ExtensionError +from sphinx.util import logging from sphinx.util.console import strip_colors from sphinx.util.fileutil import copy_asset_file from sphinx.util.osutil import fs_encoding @@ -42,19 +43,28 @@ from sphinx.util.nodes import ( # noqa caption_ref_re) from sphinx.util.matching import patfilter # noqa +if False: + # For type annotation + from typing import Any, Callable, Iterable, Pattern, Sequence, Tuple # NOQA + + +logger = logging.getLogger(__name__) + # Generally useful regular expressions. -ws_re = re.compile(r'\s+') -url_re = re.compile(r'(?P<schema>.+)://.*') +ws_re = re.compile(r'\s+') # type: Pattern +url_re = re.compile(r'(?P<schema>.+)://.*') # type: Pattern # High-level utility functions. def docname_join(basedocname, docname): + # type: (unicode, unicode) -> unicode return posixpath.normpath( posixpath.join('/' + basedocname, '..', docname))[1:] def path_stabilize(filepath): + # type: (unicode) -> unicode "normalize path separater and unicode string" newpath = filepath.replace(os.path.sep, SEP) if isinstance(newpath, text_type): @@ -63,6 +73,7 @@ def path_stabilize(filepath): def get_matching_files(dirname, exclude_matchers=()): + # type: (unicode, Tuple[Callable[[unicode], bool], ...]) -> Iterable[unicode] """Get all file names in a directory, recursively. Exclude files and dirs matching some matcher in *exclude_matchers*. @@ -75,9 +86,9 @@ def get_matching_files(dirname, exclude_matchers=()): relativeroot = root[dirlen:] qdirs = enumerate(path_stabilize(path.join(relativeroot, dn)) - for dn in dirs) + for dn in dirs) # type: Iterable[Tuple[int, unicode]] qfiles = enumerate(path_stabilize(path.join(relativeroot, fn)) - for fn in files) + for fn in files) # type: Iterable[Tuple[int, unicode]] for matcher in exclude_matchers: qdirs = [entry for entry in qdirs if not matcher(entry[1])] qfiles = [entry for entry in qfiles if not matcher(entry[1])] @@ -89,6 +100,7 @@ def get_matching_files(dirname, exclude_matchers=()): def get_matching_docs(dirname, suffixes, exclude_matchers=()): + # type: (unicode, List[unicode], Tuple[Callable[[unicode], bool], ...]) -> Iterable[unicode] # NOQA """Get all file names (without suffixes) matching a suffix in a directory, recursively. @@ -97,7 +109,7 @@ def get_matching_docs(dirname, suffixes, exclude_matchers=()): suffixpatterns = ['*' + s for s in suffixes] for filename in get_matching_files(dirname, exclude_matchers): for suffixpattern in suffixpatterns: - if fnmatch.fnmatch(filename, suffixpattern): + if fnmatch.fnmatch(filename, suffixpattern): # type: ignore yield filename[:-len(suffixpattern)+1] break @@ -109,9 +121,10 @@ class FilenameUniqDict(dict): appear in. Used for images and downloadable files in the environment. """ def __init__(self): - self._existing = set() + self._existing = set() # type: Set[unicode] def add_file(self, docname, newfile): + # type: (unicode, unicode) -> unicode if newfile in self: self[newfile][0].add(docname) return self[newfile][1] @@ -126,6 +139,7 @@ class FilenameUniqDict(dict): return uniquename def purge_doc(self, docname): + # type: (unicode) -> None for filename, (docs, unique) in list(self.items()): docs.discard(docname) if not docs: @@ -133,6 +147,7 @@ class FilenameUniqDict(dict): self._existing.discard(unique) def merge_other(self, docnames, other): + # type: (List[unicode], Dict[unicode, Tuple[Set[unicode], Any]]) -> None for filename, (docs, unique) in other.items(): for doc in docs & docnames: self.add_file(doc, filename) @@ -146,6 +161,7 @@ class FilenameUniqDict(dict): def copy_static_entry(source, targetdir, builder, context={}, exclude_matchers=(), level=0): + # type: (unicode, unicode, Any, Dict, Tuple[Callable, ...], int) -> None """[DEPRECATED] Copy a HTML builder static_path entry from source to targetdir. Handles all possible cases of files, directories and subdirectories. @@ -183,6 +199,7 @@ _DEBUG_HEADER = '''\ def save_traceback(app): + # type: (Any) -> unicode """Save the current exception's traceback in a temporary file.""" import sphinx import jinja2 @@ -190,7 +207,7 @@ def save_traceback(app): import platform exc = sys.exc_info()[1] if isinstance(exc, SphinxParallelError): - exc_format = '(Error in parallel process)\n' + exc.traceback + exc_format = '(Error in parallel process)\n' + exc.traceback # type: ignore else: exc_format = traceback.format_exc() fd, path = tempfile.mkstemp('.log', 'sphinx-err-') @@ -221,6 +238,7 @@ def save_traceback(app): def get_module_source(modname): + # type: (str) -> Tuple[unicode, unicode] """Try to find the source code for a module. Can return ('file', 'filename') in which case the source is in the given @@ -260,6 +278,7 @@ def get_module_source(modname): def get_full_modname(modname, attribute): + # type: (str, unicode) -> unicode __import__(modname) module = sys.modules[modname] @@ -278,6 +297,7 @@ _coding_re = re.compile(r'coding[:=]\s*([-\w.]+)') def detect_encoding(readline): + # type: (Callable) -> unicode """Like tokenize.detect_encoding() from Py3k, but a bit simplified.""" def read_or_stop(): @@ -434,10 +454,11 @@ def split_index_msg(type, value): def format_exception_cut_frames(x=1): + # type: (int) -> unicode """Format an exception with traceback, but only the last x frames.""" typ, val, tb = sys.exc_info() # res = ['Traceback (most recent call last):\n'] - res = [] + res = [] # type: List[unicode] tbres = traceback.format_tb(tb) res += tbres[-x:] res += traceback.format_exception_only(typ, val) @@ -450,7 +471,7 @@ class PeekableIterator(object): what's the next item. """ def __init__(self, iterable): - self.remaining = deque() + self.remaining = deque() # type: deque self._iterator = iter(iterable) def __iter__(self): @@ -478,6 +499,7 @@ class PeekableIterator(object): def import_object(objname, source=None): + # type: (str, unicode) -> Any try: module, name = objname.rsplit('.', 1) except ValueError as err: @@ -497,7 +519,8 @@ def import_object(objname, source=None): def encode_uri(uri): - split = list(urlsplit(uri)) + # type: (unicode) -> unicode + split = list(urlsplit(uri)) # type: Any split[1] = split[1].encode('idna').decode('ascii') split[2] = quote_plus(split[2].encode('utf-8'), '/').decode('ascii') query = list((q, quote_plus(v.encode('utf-8'))) @@ -507,8 +530,9 @@ def encode_uri(uri): def split_docinfo(text): + # type: (unicode) -> Sequence[unicode] docinfo_re = re.compile('\A((?:\s*:\w+:.*?\n(?:[ \t]+.*?\n)*)+)', re.M) - result = docinfo_re.split(text, 1) + result = docinfo_re.split(text, 1) # type: ignore if len(result) == 1: return '', result[0] else: diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index 0af65cbe3..a9348ce75 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -10,12 +10,17 @@ """ from __future__ import absolute_import +import sys import warnings from docutils import nodes from docutils.parsers.rst import Directive # noqa +from docutils.parsers.rst import Directive # noqa from docutils import __version__ as _du_version + +from sphinx.deprecation import RemovedInSphinx17Warning + docutils_version = tuple(int(x) for x in _du_version.split('.')[:2]) @@ -38,3 +43,24 @@ def make_admonition(node_class, name, arguments, options, content, lineno, admonition_node['classes'] += classes state.nested_parse(content, content_offset, admonition_node) return [admonition_node] + + +class _DeprecationWrapper(object): + def __init__(self, mod, deprecated): + self._mod = mod + self._deprecated = deprecated + + def __getattr__(self, attr): + if attr in self._deprecated: + warnings.warn("sphinx.util.compat.%s is deprecated and will be " + "removed in Sphinx 1.7, please use the standard " + "library version instead." % attr, + RemovedInSphinx17Warning, stacklevel=2) + return self._deprecated[attr] + return getattr(self._mod, attr) + + +sys.modules[__name__] = _DeprecationWrapper(sys.modules[__name__], dict( # type: ignore + docutils_version = docutils_version, + Directive = Directive, +)) diff --git a/sphinx/util/console.py b/sphinx/util/console.py index 593634b11..6dc4b88ca 100644 --- a/sphinx/util/console.py +++ b/sphinx/util/console.py @@ -20,10 +20,11 @@ except ImportError: colorama = None _ansi_re = re.compile('\x1b\\[(\\d\\d;){0,2}\\d\\dm') -codes = {} +codes = {} # type: Dict[str, str] def get_terminal_width(): + # type: () -> int """Borrowed from the py lib.""" try: import termios @@ -35,7 +36,7 @@ def get_terminal_width(): terminal_width = width except Exception: # FALLBACK - terminal_width = int(os.environ.get('COLUMNS', 80)) - 1 + terminal_width = int(os.environ.get('COLUMNS', "80")) - 1 return terminal_width @@ -43,6 +44,7 @@ _tw = get_terminal_width() def term_width_line(text): + # type: (str) -> str if not codes: # if no coloring, don't output fancy backspaces return text + '\n' @@ -52,6 +54,7 @@ def term_width_line(text): def color_terminal(): + # type: () -> bool if sys.platform == 'win32' and colorama is not None: colorama.init() return True @@ -68,24 +71,29 @@ def color_terminal(): def nocolor(): + # type: () -> None if sys.platform == 'win32' and colorama is not None: colorama.deinit() codes.clear() def coloron(): + # type: () -> None codes.update(_orig_codes) def colorize(name, text): + # type: (str, str) -> str return codes.get(name, '') + text + codes.get('reset', '') def strip_colors(s): + # type: (str) -> str return re.compile('\x1b.*?m').sub('', s) def create_color_func(name): + # type: (str) -> None def inner(text): return colorize(name, text) globals()[name] = inner diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py index d5cb4038f..6bf38ebed 100644 --- a/sphinx/util/docfields.py +++ b/sphinx/util/docfields.py @@ -15,8 +15,14 @@ from docutils import nodes from sphinx import addnodes +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.domains import Domain # NOQA + def _is_single_paragraph(node): + # type: (nodes.Node) -> bool """True if the node only contains one paragraph (and system messages).""" if len(node) == 0: return False @@ -47,6 +53,7 @@ class Field(object): def __init__(self, name, names=(), label=None, has_arg=True, rolename=None, bodyrolename=None): + # type: (unicode, Tuple[unicode, ...], unicode, bool, unicode, unicode) -> None self.name = name self.names = names self.label = label @@ -56,6 +63,7 @@ class Field(object): def make_xref(self, rolename, domain, target, innernode=addnodes.literal_emphasis, contnode=None): + # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node if not rolename: return contnode or innernode(target, target) refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False, @@ -65,12 +73,15 @@ class Field(object): def make_xrefs(self, rolename, domain, target, innernode=addnodes.literal_emphasis, contnode=None): + # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> List[nodes.Node] return [self.make_xref(rolename, domain, target, innernode, contnode)] def make_entry(self, fieldarg, content): + # type: (List, unicode) -> Tuple[List, unicode] return (fieldarg, content) def make_field(self, types, domain, item): + # type: (List, unicode, Tuple) -> nodes.field fieldarg, content = item fieldname = nodes.field_name('', self.label) if fieldarg: @@ -106,10 +117,12 @@ class GroupedField(Field): def __init__(self, name, names=(), label=None, rolename=None, can_collapse=False): + # type: (unicode, Tuple[unicode, ...], unicode, unicode, bool) -> None Field.__init__(self, name, names, label, True, rolename) self.can_collapse = can_collapse def make_field(self, types, domain, items): + # type: (List, unicode, Tuple) -> nodes.field fieldname = nodes.field_name('', self.label) listnode = self.list_type() for fieldarg, content in items: @@ -151,11 +164,13 @@ class TypedField(GroupedField): def __init__(self, name, names=(), typenames=(), label=None, rolename=None, typerolename=None, can_collapse=False): + # type: (unicode, Tuple[unicode, ...], Tuple[unicode, ...], unicode, unicode, unicode, bool) -> None # NOQA GroupedField.__init__(self, name, names, label, rolename, can_collapse) self.typenames = typenames self.typerolename = typerolename def make_field(self, types, domain, items): + # type: (List, unicode, Tuple) -> nodes.field def handle_item(fieldarg, content): par = nodes.paragraph() par.extend(self.make_xrefs(self.rolename, domain, fieldarg, @@ -196,6 +211,7 @@ class DocFieldTransformer(object): """ def __init__(self, directive): + # type: (Any) -> None self.domain = directive.domain if '_doc_field_type_map' not in directive.__class__.__dict__: directive.__class__._doc_field_type_map = \ @@ -203,6 +219,7 @@ class DocFieldTransformer(object): self.typemap = directive._doc_field_type_map def preprocess_fieldtypes(self, types): + # type: (List) -> Dict[unicode, Tuple[Any, bool]] typemap = {} for fieldtype in types: for name in fieldtype.names: @@ -213,6 +230,7 @@ class DocFieldTransformer(object): return typemap def transform_all(self, node): + # type: (nodes.Node) -> None """Transform all field list children of a node.""" # don't traverse, only handle field lists that are immediate children for child in node: @@ -220,12 +238,13 @@ class DocFieldTransformer(object): self.transform(child) def transform(self, node): + # type: (nodes.Node) -> None """Transform a single field list *node*.""" typemap = self.typemap entries = [] - groupindices = {} - types = {} + groupindices = {} # type: Dict[unicode, int] + types = {} # type: Dict[unicode, Dict] # step 1: traverse all fields and collect field types and content for field in node: diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index 8d1d58cf8..ad80ac7a7 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -10,17 +10,33 @@ """ from __future__ import absolute_import +import re from copy import copy from contextlib import contextmanager + import docutils +from docutils.utils import Reporter from docutils.parsers.rst import directives, roles +from sphinx.util import logging + +logger = logging.getLogger(__name__) +report_re = re.compile('^(.+?:\d+): \((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\d+)?\) (.+?)\n?$') + + +if False: + # For type annotation + from typing import Any, Callable, Iterator, Tuple # NOQA + from docutils import nodes # NOQA + from sphinx.environment import BuildEnvironment # NOQA + __version_info__ = tuple(map(int, docutils.__version__.split('.'))) @contextmanager def docutils_namespace(): + # type: () -> Iterator[None] """Create namespace for reST parsers.""" try: _directives = copy(directives._directives) @@ -41,9 +57,10 @@ class sphinx_domains(object): markup takes precedence. """ def __init__(self, env): + # type: (BuildEnvironment) -> None self.env = env - self.directive_func = None - self.roles_func = None + self.directive_func = None # type: Callable + self.roles_func = None # type: Callable def __enter__(self): self.enable() @@ -63,6 +80,7 @@ class sphinx_domains(object): roles.role = self.role_func def lookup_domain_element(self, type, name): + # type: (unicode, unicode) -> Tuple[Any, List] """Lookup a markup element (directive or role), given its name which can be a full name (with domain). """ @@ -71,7 +89,7 @@ class sphinx_domains(object): if ':' in name: domain_name, name = name.split(':', 1) if domain_name in self.env.domains: - domain = self.env.domains[domain_name] + domain = self.env.get_domain(domain_name) element = getattr(domain, type)(name) if element is not None: return element, [] @@ -84,20 +102,43 @@ class sphinx_domains(object): return element, [] # always look in the std domain - element = getattr(self.env.domains['std'], type)(name) + element = getattr(self.env.get_domain('std'), type)(name) if element is not None: return element, [] raise ElementLookupError def lookup_directive(self, name, lang_module, document): + # type: (unicode, unicode, nodes.document) -> Tuple[Any, List] try: return self.lookup_domain_element('directive', name) except ElementLookupError: return self.directive_func(name, lang_module, document) def lookup_role(self, name, lang_module, lineno, reporter): + # type: (unicode, unicode, int, Any) -> Tuple[Any, List] try: return self.lookup_domain_element('role', name) except ElementLookupError: return self.role_func(name, lang_module, lineno, reporter) + + +class WarningStream(object): + def write(self, text): + matched = report_re.search(text) + if not matched: + logger.warning(text.rstrip("\r\n")) + else: + location, type, level, message = matched.groups() + logger.log(type, message, location=location) + + +class LoggingReporter(Reporter): + def __init__(self, source, report_level, halt_level, + debug=False, error_handler='backslashreplace'): + stream = WarningStream() + Reporter.__init__(self, source, report_level, halt_level, + stream, debug, error_handler=error_handler) + + def set_conditions(self, category, report_level, halt_level, debug=False): + Reporter.set_conditions(self, category, report_level, halt_level, debug=debug) diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py index 41a9c5e20..72059d634 100644 --- a/sphinx/util/i18n.py +++ b/sphinx/util/i18n.py @@ -12,7 +12,6 @@ import gettext import io import os import re -import warnings from os import path from datetime import datetime from collections import namedtuple @@ -22,10 +21,15 @@ from babel.messages.pofile import read_po from babel.messages.mofile import write_mo from sphinx.errors import SphinxError -from sphinx.deprecation import RemovedInSphinx16Warning -from sphinx.util.osutil import walk -from sphinx.util import SEP +from sphinx.util import logging +from sphinx.util.osutil import SEP, walk +logger = logging.getLogger(__name__) + +if False: + # For type annotation + from typing import Callable # NOQA + from sphinx.environment import BuildEnvironment # NOQA LocaleFileInfoBase = namedtuple('CatalogInfo', 'base_dir,domain,charset') @@ -34,32 +38,39 @@ class CatalogInfo(LocaleFileInfoBase): @property def po_file(self): + # type: () -> unicode return self.domain + '.po' @property def mo_file(self): + # type: () -> unicode return self.domain + '.mo' @property def po_path(self): + # type: () -> unicode return path.join(self.base_dir, self.po_file) @property def mo_path(self): + # type: () -> unicode return path.join(self.base_dir, self.mo_file) def is_outdated(self): + # type: () -> bool return ( not path.exists(self.mo_path) or path.getmtime(self.mo_path) < path.getmtime(self.po_path)) def write_mo(self, locale): + # type: (unicode) -> None with io.open(self.po_path, 'rt', encoding=self.charset) as po: with io.open(self.mo_path, 'wb') as mo: write_mo(mo, read_po(po, locale)) def find_catalog(docname, compaction): + # type: (unicode, bool) -> unicode if compaction: ret = docname.split(SEP, 1)[0] else: @@ -69,18 +80,20 @@ def find_catalog(docname, compaction): def find_catalog_files(docname, srcdir, locale_dirs, lang, compaction): + # type: (unicode, unicode, List[unicode], unicode, bool) -> List[unicode] if not(lang and locale_dirs): return [] domain = find_catalog(docname, compaction) - files = [gettext.find(domain, path.join(srcdir, dir_), [lang]) - for dir_ in locale_dirs] - files = [path.relpath(f, srcdir) for f in files if f] - return files + files = [gettext.find(domain, path.join(srcdir, dir_), [lang]) # type: ignore + for dir_ in locale_dirs] # type: ignore + files = [path.relpath(f, srcdir) for f in files if f] # type: ignore + return files # type: ignore def find_catalog_source_files(locale_dirs, locale, domains=None, gettext_compact=False, charset='utf-8', force_all=False): + # type: (List[unicode], unicode, List[unicode], bool, unicode, bool) -> Set[CatalogInfo] """ :param list locale_dirs: list of path as `['locale_dir1', 'locale_dir2', ...]` to find @@ -97,10 +110,11 @@ def find_catalog_source_files(locale_dirs, locale, domains=None, gettext_compact default is False. :return: [CatalogInfo(), ...] """ + catalogs = set() # type: Set[CatalogInfo] + if not locale: - return [] # locale is not specified + return catalogs # locale is not specified - catalogs = set() for locale_dir in locale_dirs: if not locale_dir: continue # skip system locale directory @@ -158,7 +172,8 @@ date_format_mappings = { } -def babel_format_date(date, format, locale, warn=None, formatter=babel.dates.format_date): +def babel_format_date(date, format, locale, formatter=babel.dates.format_date): + # type: (datetime, unicode, unicode, Callable) -> unicode if locale is None: locale = 'en' @@ -173,17 +188,13 @@ def babel_format_date(date, format, locale, warn=None, formatter=babel.dates.for # fallback to English return formatter(date, format, locale='en') except AttributeError: - if warn: - warn('Invalid date format. Quote the string by single quote ' - 'if you want to output it directly: %s' % format) - + logger.warning('Invalid date format. Quote the string by single quote ' + 'if you want to output it directly: %s', format) return format -def format_date(format, date=None, language=None, warn=None): - if format is None: - format = 'medium' - +def format_date(format, date=None, language=None): + # type: (str, datetime, unicode) -> unicode if date is None: # If time is not specified, try to use $SOURCE_DATE_EPOCH variable # See https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal @@ -193,40 +204,32 @@ def format_date(format, date=None, language=None, warn=None): else: date = datetime.now() - if re.match('EEE|MMM|dd|DDD|MM|WW|medium|YY', format): - # consider the format as babel's - warnings.warn('LDML format support will be dropped at Sphinx-1.6', - RemovedInSphinx16Warning) - - return babel_format_date(date, format, locale=language, warn=warn, - formatter=babel.dates.format_datetime) - else: - # consider the format as ustrftime's and try to convert it to babel's - result = [] - tokens = re.split('(%.)', format) - for token in tokens: - if token in date_format_mappings: - babel_format = date_format_mappings.get(token, '') - - # Check if we have to use a different babel formatter then - # format_datetime, because we only want to format a date - # or a time. - if token == '%x': - function = babel.dates.format_date - elif token == '%X': - function = babel.dates.format_time - else: - function = babel.dates.format_datetime - - result.append(babel_format_date(date, babel_format, locale=language, - formatter=function)) + result = [] + tokens = re.split('(%.)', format) + for token in tokens: + if token in date_format_mappings: + babel_format = date_format_mappings.get(token, '') + + # Check if we have to use a different babel formatter then + # format_datetime, because we only want to format a date + # or a time. + if token == '%x': + function = babel.dates.format_date + elif token == '%X': + function = babel.dates.format_time else: - result.append(token) + function = babel.dates.format_datetime + + result.append(babel_format_date(date, babel_format, locale=language, + formatter=function)) + else: + result.append(token) - return "".join(result) + return "".join(result) def get_image_filename_for_language(filename, env): + # type: (unicode, BuildEnvironment) -> unicode if not env.config.language: return filename @@ -246,6 +249,7 @@ def get_image_filename_for_language(filename, env): def search_image_for_language(filename, env): + # type: (unicode, BuildEnvironment) -> unicode if not env.config.language: return filename diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py index 942a73654..28bc877b3 100644 --- a/sphinx/util/inspect.py +++ b/sphinx/util/inspect.py @@ -12,10 +12,14 @@ import re from six import PY3, binary_type -from six.moves import builtins +from six.moves import builtins # type: ignore from sphinx.util import force_decode +if False: + # For type annotation + from typing import Any, Callable, Tuple # NOQA + # this imports the standard library inspect module without resorting to # relatively import this module inspect = __import__('inspect') @@ -67,7 +71,7 @@ else: # 2.7 """Like inspect.getargspec but supports functools.partial as well.""" if inspect.ismethod(func): func = func.__func__ - parts = 0, () + parts = 0, () # type: Tuple[int, Tuple[unicode, ...]] if type(func) is partial: keywords = func.keywords if keywords is None: @@ -108,6 +112,7 @@ def isenumclass(x): def isenumattribute(x): + # type: (Any) -> bool """Check if the object is attribute of enum.""" if enum is None: return False @@ -115,6 +120,7 @@ def isenumattribute(x): def isdescriptor(x): + # type: (Any) -> bool """Check if the object is some kind of descriptor.""" for item in '__get__', '__set__', '__delete__': if hasattr(safe_getattr(x, item, None), '__call__'): @@ -123,6 +129,7 @@ def isdescriptor(x): def safe_getattr(obj, name, *defargs): + # type: (Any, unicode, unicode) -> object """A getattr() that turns all exceptions into AttributeErrors.""" try: return getattr(obj, name, *defargs) @@ -145,8 +152,9 @@ def safe_getattr(obj, name, *defargs): def safe_getmembers(object, predicate=None, attr_getter=safe_getattr): + # type: (Any, Callable[[unicode], bool], Callable) -> List[Tuple[unicode, Any]] """A version of inspect.getmembers() that uses safe_getattr().""" - results = [] + results = [] # type: List[Tuple[unicode, Any]] for key in dir(object): try: value = attr_getter(object, key, None) @@ -159,6 +167,7 @@ def safe_getmembers(object, predicate=None, attr_getter=safe_getattr): def object_description(object): + # type: (Any) -> unicode """A repr() implementation that returns text safe to use in reST context.""" try: s = repr(object) @@ -173,6 +182,7 @@ def object_description(object): def is_builtin_class_method(obj, attr_name): + # type: (Any, unicode) -> bool """If attr_name is implemented at builtin class, return True. >>> is_builtin_class_method(int, '__init__') @@ -184,6 +194,6 @@ def is_builtin_class_method(obj, attr_name): classes = [c for c in inspect.getmro(obj) if attr_name in c.__dict__] cls = classes[0] if classes else object - if not hasattr(builtins, safe_getattr(cls, '__name__', '')): + if not hasattr(builtins, safe_getattr(cls, '__name__', '')): # type: ignore return False - return getattr(builtins, safe_getattr(cls, '__name__', '')) is cls + return getattr(builtins, safe_getattr(cls, '__name__', '')) is cls # type: ignore diff --git a/sphinx/util/jsdump.py b/sphinx/util/jsdump.py index 5a2148c5b..330b5c0ee 100644 --- a/sphinx/util/jsdump.py +++ b/sphinx/util/jsdump.py @@ -16,6 +16,10 @@ from six import iteritems, integer_types, string_types from sphinx.util.pycompat import u +if False: + # For type annotation + from typing import Any, IO, Union # NOQA + _str_re = re.compile(r'"(\\\\|\\"|[^"])*"') _int_re = re.compile(r'\d+') _name_re = re.compile(r'[a-zA-Z_]\w*') @@ -37,6 +41,7 @@ ESCAPED = re.compile(r'\\u.{4}|\\.') def encode_string(s): + # type: (str) -> str def replace(match): s = match.group(0) try: @@ -55,6 +60,7 @@ def encode_string(s): def decode_string(s): + # type: (str) -> str return ESCAPED.sub(lambda m: eval(u + '"' + m.group() + '"'), s) @@ -77,6 +83,7 @@ double in super""".split()) def dumps(obj, key=False): + # type: (Any, bool) -> str if key: if not isinstance(obj, string_types): obj = str(obj) @@ -88,7 +95,7 @@ def dumps(obj, key=False): return 'null' elif obj is True or obj is False: return obj and 'true' or 'false' - elif isinstance(obj, integer_types + (float,)): + elif isinstance(obj, integer_types + (float,)): # type: ignore return str(obj) elif isinstance(obj, dict): return '{%s}' % ','.join(sorted('%s:%s' % ( @@ -100,20 +107,22 @@ def dumps(obj, key=False): elif isinstance(obj, (tuple, list)): return '[%s]' % ','.join(dumps(x) for x in obj) elif isinstance(obj, string_types): - return encode_string(obj) + return encode_string(obj) # type: ignore raise TypeError(type(obj)) def dump(obj, f): + # type: (Any, IO) -> None f.write(dumps(obj)) def loads(x): + # type: (str) -> Any """Loader that can read the JS subset the indexer produces.""" nothing = object() i = 0 n = len(x) - stack = [] + stack = [] # type: List[Union[List, Dict]] obj = nothing key = False keys = [] @@ -164,6 +173,7 @@ def loads(x): raise ValueError("multiple values") key = False else: + y = None # type: Any m = _str_re.match(x, i) if m: y = decode_string(m.group()[1:-1]) @@ -193,11 +203,12 @@ def loads(x): obj[keys[-1]] = y key = False else: - obj.append(y) + obj.append(y) # type: ignore if obj is nothing: raise ValueError("nothing loaded from string") return obj def load(f): + # type: (IO) -> Any return loads(f.read()) diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index ef91b728b..b4f8f5796 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -8,9 +8,269 @@ :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ +from __future__ import absolute_import + +import logging +import logging.handlers +from contextlib import contextmanager +from collections import defaultdict + +from six import PY2, StringIO +from docutils import nodes +from docutils.utils import get_source_line + +from sphinx.errors import SphinxWarning +from sphinx.util.console import colorize + +if False: + # For type annotation + from typing import Any, Generator, IO, Tuple, Union # NOQA + from docutils import nodes # NOQA + from sphinx.application import Sphinx # NOQA + + +VERBOSE = 15 + +LEVEL_NAMES = defaultdict(lambda: logging.WARNING) # type: Dict[str, int] +LEVEL_NAMES.update({ + 'CRITICAL': logging.CRITICAL, + 'SEVERE': logging.CRITICAL, + 'ERROR': logging.ERROR, + 'WARNING': logging.WARNING, + 'INFO': logging.INFO, + 'VERBOSE': VERBOSE, + 'DEBUG': logging.DEBUG, +}) + +VERBOSITY_MAP = defaultdict(lambda: 0) # type: Dict[int, int] +VERBOSITY_MAP.update({ + 0: logging.INFO, + 1: VERBOSE, + 2: logging.DEBUG, +}) + +COLOR_MAP = defaultdict(lambda text: text) # type: Dict[int, unicode] +COLOR_MAP.update({ + logging.WARNING: 'darkred', + logging.DEBUG: 'darkgray', +}) + + +def getLogger(name): + # type: (str) -> SphinxLoggerAdapter + """Get logger wrapped by SphinxLoggerAdapter.""" + return SphinxLoggerAdapter(logging.getLogger(name), {}) + + +def convert_serializable(records): + """Convert LogRecord serializable.""" + for r in records: + # extract arguments to a message and clear them + r.msg = r.getMessage() + r.args = () + + +class SphinxWarningLogRecord(logging.LogRecord): + """Log record class supporting location""" + location = None # type: Any + + def getMessage(self): + # type: () -> str + message = super(SphinxWarningLogRecord, self).getMessage() + location = getattr(self, 'location', None) + if location: + message = '%s: WARNING: %s' % (location, message) + elif 'WARNING:' not in message: + message = 'WARNING: %s' % message + + return message + + +class SphinxLoggerAdapter(logging.LoggerAdapter): + """LoggerAdapter allowing ``type`` and ``subtype`` keywords.""" + + def log(self, level, msg, *args, **kwargs): + # type: (Union[int, str], unicode, Any, Any) -> None + if isinstance(level, int): + super(SphinxLoggerAdapter, self).log(level, msg, *args, **kwargs) + else: + levelno = LEVEL_NAMES[level] + super(SphinxLoggerAdapter, self).log(levelno, msg, *args, **kwargs) + + def verbose(self, msg, *args, **kwargs): + # type: (unicode, Any, Any) -> None + self.log(VERBOSE, msg, *args, **kwargs) + + def process(self, msg, kwargs): # type: ignore + # type: (unicode, Dict) -> Tuple[unicode, Dict] + extra = kwargs.setdefault('extra', {}) + if 'type' in kwargs: + extra['type'] = kwargs.pop('type') + if 'subtype' in kwargs: + extra['subtype'] = kwargs.pop('subtype') + if 'location' in kwargs: + extra['location'] = kwargs.pop('location') + if 'nonl' in kwargs: + extra['nonl'] = kwargs.pop('nonl') + if 'color' in kwargs: + extra['color'] = kwargs.pop('color') + + return msg, kwargs + + def handle(self, record): + # type: (logging.LogRecord) -> None + self.logger.handle(record) # type: ignore + + +class WarningStreamHandler(logging.StreamHandler): + """StreamHandler for warnings.""" + pass + + +class NewLineStreamHandlerPY2(logging.StreamHandler): + """StreamHandler which switches line terminator by record.nonl flag.""" + + def emit(self, record): + # type: (logging.LogRecord) -> None + try: + self.acquire() + stream = self.stream # type: ignore + if getattr(record, 'nonl', False): + # remove return code forcely when nonl=True + self.stream = StringIO() + super(NewLineStreamHandlerPY2, self).emit(record) + stream.write(self.stream.getvalue()[:-1]) + stream.flush() + else: + super(NewLineStreamHandlerPY2, self).emit(record) + finally: + self.stream = stream + self.release() + + +class NewLineStreamHandlerPY3(logging.StreamHandler): + """StreamHandler which switches line terminator by record.nonl flag.""" + + def emit(self, record): + # type: (logging.LogRecord) -> None + try: + self.acquire() + if getattr(record, 'nonl', False): + # skip appending terminator when nonl=True + self.terminator = '' + super(NewLineStreamHandlerPY3, self).emit(record) + finally: + self.terminator = '\n' + self.release() + + +if PY2: + NewLineStreamHandler = NewLineStreamHandlerPY2 +else: + NewLineStreamHandler = NewLineStreamHandlerPY3 + + +class MemoryHandler(logging.handlers.BufferingHandler): + """Handler buffering all logs.""" + + def __init__(self): + super(MemoryHandler, self).__init__(-1) + + def shouldFlush(self, record): + # type: (logging.LogRecord) -> bool + return False # never flush + + def flushTo(self, logger): + # type: (logging.Logger) -> None + self.acquire() + try: + for record in self.buffer: + logger.handle(record) + self.buffer = [] # type: List[logging.LogRecord] + finally: + self.release() + + def clear(self): + # type: () -> List[logging.LogRecord] + buffer, self.buffer = self.buffer, [] + return buffer + + +@contextmanager +def pending_warnings(): + # type: () -> Generator + """contextmanager to pend logging warnings temporary.""" + logger = logging.getLogger() + memhandler = MemoryHandler() + memhandler.setLevel(logging.WARNING) + + try: + handlers = [] + for handler in logger.handlers[:]: + if isinstance(handler, WarningStreamHandler): + logger.removeHandler(handler) + handlers.append(handler) + + logger.addHandler(memhandler) + yield memhandler + finally: + logger.removeHandler(memhandler) + + for handler in handlers: + logger.addHandler(handler) + + memhandler.flushTo(logger) + + +@contextmanager +def pending_logging(): + # type: () -> Generator + """contextmanager to pend logging all logs temporary.""" + logger = logging.getLogger() + memhandler = MemoryHandler() + + try: + handlers = [] + for handler in logger.handlers[:]: + logger.removeHandler(handler) + handlers.append(handler) + + logger.addHandler(memhandler) + yield memhandler + finally: + logger.removeHandler(memhandler) + + for handler in handlers: + logger.addHandler(handler) + + memhandler.flushTo(logger) + + +class LogCollector(object): + def __init__(self): + self.logs = [] # type: logging.LogRecord + + @contextmanager + def collect(self): + with pending_logging() as memhandler: + yield + + self.logs = memhandler.clear() + + +class InfoFilter(logging.Filter): + """Filter error and warning messages.""" + + def filter(self, record): + # type: (logging.LogRecord) -> bool + if record.levelno < logging.WARNING: + return True + else: + return False def is_suppressed_warning(type, subtype, suppress_warnings): + # type: (unicode, unicode, List[unicode]) -> bool """Check the warning is suppressed or not.""" if type is None: return False @@ -27,3 +287,137 @@ def is_suppressed_warning(type, subtype, suppress_warnings): return True return False + + +class WarningSuppressor(logging.Filter): + """Filter logs by `suppress_warnings`.""" + + def __init__(self, app): + # type: (Sphinx) -> None + self.app = app + super(WarningSuppressor, self).__init__() + + def filter(self, record): + # type: (logging.LogRecord) -> bool + type = getattr(record, 'type', None) + subtype = getattr(record, 'subtype', None) + + if is_suppressed_warning(type, subtype, self.app.config.suppress_warnings): + return False + else: + self.app._warncount += 1 + return True + + +class WarningIsErrorFilter(logging.Filter): + """Raise exception if warning emitted.""" + + def __init__(self, app): + # type: (Sphinx) -> None + self.app = app + super(WarningIsErrorFilter, self).__init__() + + def filter(self, record): + # type: (logging.LogRecord) -> bool + if self.app.warningiserror: + raise SphinxWarning(record.msg % record.args) + else: + return True + + +class WarningLogRecordTranslator(logging.Filter): + """Converts a log record to one Sphinx expects + + * Make a instance of SphinxWarningLogRecord + * docname to path if location given + """ + def __init__(self, app): + # type: (Sphinx) -> None + self.app = app + super(WarningLogRecordTranslator, self).__init__() + + def filter(self, record): # type: ignore + # type: (SphinxWarningLogRecord) -> bool + if isinstance(record, logging.LogRecord): + record.__class__ = SphinxWarningLogRecord # force subclassing to handle location + + location = getattr(record, 'location', None) + if isinstance(location, tuple): + docname, lineno = location + if docname and lineno: + record.location = '%s:%s' % (self.app.env.doc2path(docname), lineno) + elif docname: + record.location = '%s' % self.app.env.doc2path(docname) + else: + record.location = None + elif isinstance(location, nodes.Node): + (source, line) = get_source_line(location) + if source and line: + record.location = "%s:%s" % (source, line) + elif source: + record.location = "%s:" % source + elif line: + record.location = "<unknown>:%s" % line + else: + record.location = None + elif location and ':' not in location: + record.location = '%s' % self.app.env.doc2path(location) + + return True + + +class ColorizeFormatter(logging.Formatter): + def format(self, record): + message = super(ColorizeFormatter, self).format(record) + color = getattr(record, 'color', None) + if color is None: + color = COLOR_MAP.get(record.levelno) + + if color: + return colorize(color, message) + else: + return message + + +class SafeEncodingWriter(object): + """Stream writer which ignores UnicodeEncodeError silently""" + def __init__(self, stream): + self.stream = stream + self.encoding = getattr(stream, 'encoding', 'ascii') or 'ascii' + + def write(self, data): + try: + self.stream.write(data) + except UnicodeEncodeError: + # stream accept only str, not bytes. So, we encode and replace + # non-encodable characters, then decode them. + self.stream.write(data.encode(self.encoding, 'replace').decode(self.encoding)) + + def flush(self): + if hasattr(self.stream, 'flush'): + self.stream.flush() + + +def setup(app, status, warning): + # type: (Sphinx, IO, IO) -> None + """Setup root logger for Sphinx""" + logger = logging.getLogger() + logger.setLevel(logging.NOTSET) + + # clear all handlers + for handler in logger.handlers[:]: + logger.removeHandler(handler) + + info_handler = NewLineStreamHandler(SafeEncodingWriter(status)) # type: ignore + info_handler.addFilter(InfoFilter()) + info_handler.setLevel(VERBOSITY_MAP[app.verbosity]) + info_handler.setFormatter(ColorizeFormatter()) + + warning_handler = WarningStreamHandler(SafeEncodingWriter(warning)) # type: ignore + warning_handler.addFilter(WarningSuppressor(app)) + warning_handler.addFilter(WarningIsErrorFilter(app)) + warning_handler.addFilter(WarningLogRecordTranslator(app)) + warning_handler.setLevel(logging.WARNING) + warning_handler.setFormatter(ColorizeFormatter()) + logger.addHandler(info_handler) + logger.addHandler(warning_handler) diff --git a/sphinx/util/matching.py b/sphinx/util/matching.py index fc7750be9..be4bfee34 100644 --- a/sphinx/util/matching.py +++ b/sphinx/util/matching.py @@ -11,15 +11,20 @@ import re +if False: + # For type annotation + from typing import Callable, Match, Pattern # NOQA + def _translate_pattern(pat): + # type: (unicode) -> unicode """Translate a shell-style glob pattern to a regular expression. Adapted from the fnmatch module, but enhanced so that single stars don't match slashes. """ i, n = 0, len(pat) - res = '' + res = '' # type: unicode while i < n: c = pat[i] i += 1 @@ -59,6 +64,7 @@ def _translate_pattern(pat): def compile_matchers(patterns): + # type: (List[unicode]) -> List[Callable[[unicode], Match[unicode]]] return [re.compile(_translate_pattern(pat)).match for pat in patterns] @@ -70,23 +76,27 @@ class Matcher(object): """ def __init__(self, patterns): + # type: (List[unicode]) -> None expanded = [pat[3:] for pat in patterns if pat.startswith('**/')] self.patterns = compile_matchers(patterns + expanded) def __call__(self, string): + # type: (unicode) -> bool return self.match(string) def match(self, string): + # type: (unicode) -> bool return any(pat(string) for pat in self.patterns) DOTFILES = Matcher(['**/.*']) -_pat_cache = {} +_pat_cache = {} # type: Dict[unicode, Pattern] def patmatch(name, pat): + # type: (unicode, unicode) -> re.Match """Return if name matches pat. Adapted from fnmatch module.""" if pat not in _pat_cache: _pat_cache[pat] = re.compile(_translate_pattern(pat)) @@ -94,6 +104,7 @@ def patmatch(name, pat): def patfilter(names, pat): + # type: (List[unicode], unicode) -> List[unicode] """Return the subset of the list NAMES that match PAT. Adapted from fnmatch module. diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py index 1da3f69d8..4c574c242 100644 --- a/sphinx/util/nodes.py +++ b/sphinx/util/nodes.py @@ -13,19 +13,31 @@ from __future__ import absolute_import import re from six import text_type + from docutils import nodes from sphinx import addnodes from sphinx.locale import pairindextypes +from sphinx.util import logging + +if False: + # For type annotation + from typing import Any, Callable, Iterable, Tuple, Union # NOQA + from sphinx.builders import Builder # NOQA + from sphinx.utils.tags import Tags # NOQA + +logger = logging.getLogger(__name__) class WarningStream(object): def __init__(self, warnfunc): + # type: (Callable) -> None self.warnfunc = warnfunc self._re = re.compile(r'\((DEBUG|INFO|WARNING|ERROR|SEVERE)/[0-4]\)') def write(self, text): + # type: (str) -> None text = text.strip() if text: self.warnfunc(self._re.sub(r'\1:', text), None, '') @@ -37,6 +49,7 @@ caption_ref_re = explicit_title_re # b/w compat alias def apply_source_workaround(node): + # type: (nodes.Node) -> None # workaround: nodes.term have wrong rawsource if classifier is specified. # The behavior of docutils-0.11, 0.12 is: # * when ``term text : classifier1 : classifier2`` is specified, @@ -90,6 +103,7 @@ IGNORED_NODES = ( def is_pending_meta(node): + # type: (nodes.Node) -> bool if (isinstance(node, nodes.pending) and isinstance(node.details.get('nodes', [None])[0], addnodes.meta)): return True @@ -98,6 +112,7 @@ def is_pending_meta(node): def is_translatable(node): + # type: (nodes.Node) -> bool if isinstance(node, addnodes.translatable): return True @@ -140,6 +155,7 @@ META_TYPE_NODES = ( def extract_messages(doctree): + # type: (nodes.Node) -> Iterable[Tuple[nodes.Node, unicode]] """Extract translatable messages from a document tree.""" for node in doctree.traverse(is_translatable): if isinstance(node, addnodes.translatable): @@ -167,12 +183,14 @@ def extract_messages(doctree): def find_source_node(node): + # type: (nodes.Node) -> unicode for pnode in traverse_parent(node): if pnode.source: return pnode.source def traverse_parent(node, cls=None): + # type: (nodes.Node, Any) -> Iterable[nodes.Node] while node: if cls is None or isinstance(node, cls): yield node @@ -180,6 +198,7 @@ def traverse_parent(node, cls=None): def traverse_translatable_index(doctree): + # type: (nodes.Node) -> Iterable[Tuple[nodes.Node, List[unicode]]] """Traverse translatable index node from a document tree.""" def is_block_index(node): return isinstance(node, addnodes.index) and \ @@ -193,6 +212,7 @@ def traverse_translatable_index(doctree): def nested_parse_with_titles(state, content, node): + # type: (Any, List[unicode], nodes.Node) -> unicode """Version of state.nested_parse() that allows titles and does not require titles to have the same decoration as the calling document. @@ -212,6 +232,7 @@ def nested_parse_with_titles(state, content, node): def clean_astext(node): + # type: (nodes.Node) -> unicode """Like node.astext(), but ignore images.""" node = node.deepcopy() for img in node.traverse(nodes.image): @@ -222,6 +243,7 @@ def clean_astext(node): def split_explicit_title(text): + # type: (str) -> Tuple[bool, unicode, unicode] """Split role content into title and target, if given.""" match = explicit_title_re.match(text) if match: @@ -235,7 +257,8 @@ indextypes = [ def process_index_entry(entry, targetid): - indexentries = [] + # type: (unicode, unicode) -> List[Tuple[unicode, unicode, unicode, unicode, unicode]] + indexentries = [] # type: List[Tuple[unicode, unicode, unicode, unicode, unicode]] entry = entry.strip() oentry = entry main = '' @@ -271,6 +294,7 @@ def process_index_entry(entry, targetid): def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed): + # type: (Builder, Set[unicode], unicode, nodes.Node, Callable, nodes.Node) -> nodes.Node """Inline all toctrees in the *tree*. Record all docnames in *docnameset*, and output docnames with *colorfunc*. @@ -283,15 +307,14 @@ def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed if includefile not in traversed: try: traversed.append(includefile) - builder.info(colorfunc(includefile) + " ", nonl=1) + logger.info(colorfunc(includefile) + " ", nonl=1) subtree = inline_all_toctrees(builder, docnameset, includefile, builder.env.get_doctree(includefile), colorfunc, traversed) docnameset.add(includefile) except Exception: - builder.warn('toctree contains ref to nonexisting ' - 'file %r' % includefile, - builder.env.doc2path(docname)) + logger.warning('toctree contains ref to nonexisting file %r', + includefile, location=docname) else: sof = addnodes.start_of_file(docname=includefile) sof.children = subtree.children @@ -304,6 +327,7 @@ def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed def make_refnode(builder, fromdocname, todocname, targetid, child, title=None): + # type: (Builder, unicode, unicode, unicode, nodes.Node, unicode) -> nodes.reference """Shortcut to create a reference node.""" node = nodes.reference('', '', internal=True) if fromdocname == todocname: @@ -318,15 +342,18 @@ def make_refnode(builder, fromdocname, todocname, targetid, child, title=None): def set_source_info(directive, node): + # type: (Any, nodes.Node) -> None node.source, node.line = \ directive.state_machine.get_source_and_line(directive.lineno) def set_role_source_info(inliner, lineno, node): + # type: (Any, unicode, nodes.Node) -> None node.source, node.line = inliner.reporter.get_source_and_line(lineno) -def process_only_nodes(doctree, tags, warn_node=None): +def process_only_nodes(doctree, tags): + # type: (nodes.Node, Tags) -> None # A comment on the comment() nodes being inserted: replacing by [] would # result in a "Losing ids" exception if there is a target node before # the only node, so we make sure docutils can transfer the id to @@ -335,10 +362,8 @@ def process_only_nodes(doctree, tags, warn_node=None): try: ret = tags.eval_condition(node['expr']) except Exception as err: - if warn_node is None: - raise err - warn_node('exception while evaluating only ' - 'directive expression: %s' % err, node) + logger.warning('exception while evaluating only directive expression: %s', err, + location=node) node.replace_self(node.children or nodes.comment()) else: if ret: @@ -350,6 +375,7 @@ def process_only_nodes(doctree, tags, warn_node=None): # monkey-patch Element.copy to copy the rawsource and line def _new_copy(self): + # type: (nodes.Node) -> nodes.Node newnode = self.__class__(self.rawsource, **self.attributes) if isinstance(self, nodes.Element): newnode.source = self.source diff --git a/sphinx/util/osutil.py b/sphinx/util/osutil.py index b8fffb220..5561f0ddb 100644 --- a/sphinx/util/osutil.py +++ b/sphinx/util/osutil.py @@ -21,9 +21,12 @@ import filecmp from os import path import contextlib from io import BytesIO, StringIO - from six import PY2, text_type +if False: + # For type annotation + from typing import Any, Iterator, Tuple, Union # NOQA + # Errnos that we need. EEXIST = getattr(errno, 'EEXIST', 0) ENOENT = getattr(errno, 'ENOENT', 0) @@ -39,15 +42,18 @@ SEP = "/" def os_path(canonicalpath): + # type: (unicode) -> unicode return canonicalpath.replace(SEP, path.sep) def canon_path(nativepath): + # type: (unicode) -> unicode """Return path in OS-independent form""" return nativepath.replace(path.sep, SEP) def relative_uri(base, to): + # type: (unicode, unicode) -> unicode """Return a relative URL from ``base`` to ``to``.""" if to.startswith(SEP): return to @@ -71,6 +77,7 @@ def relative_uri(base, to): def ensuredir(path): + # type: (unicode) -> None """Ensure that a path exists.""" try: os.makedirs(path) @@ -84,6 +91,7 @@ def ensuredir(path): # that check UnicodeError. # The customization obstacle to replace the function with the os.walk. def walk(top, topdown=True, followlinks=False): + # type: (unicode, bool, bool) -> Iterator[Tuple[unicode, List[unicode], List[unicode]]] """Backport of os.walk from 2.6, where the *followlinks* argument was added. """ @@ -115,6 +123,7 @@ def walk(top, topdown=True, followlinks=False): def mtimes_of_files(dirnames, suffix): + # type: (List[unicode], unicode) -> Iterator[float] for dirname in dirnames: for root, dirs, files in os.walk(dirname): for sfile in files: @@ -126,6 +135,7 @@ def mtimes_of_files(dirnames, suffix): def movefile(source, dest): + # type: (unicode, unicode) -> None """Move a file, removing the destination if it exists.""" if os.path.exists(dest): try: @@ -136,6 +146,7 @@ def movefile(source, dest): def copytimes(source, dest): + # type: (unicode, unicode) -> None """Copy a file's modification times.""" st = os.stat(source) if hasattr(os, 'utime'): @@ -143,6 +154,7 @@ def copytimes(source, dest): def copyfile(source, dest): + # type: (unicode, unicode) -> None """Copy a file and its modification times, if possible. Note: ``copyfile`` skips copying if the file has not been changed""" @@ -159,10 +171,12 @@ no_fn_re = re.compile(r'[^a-zA-Z0-9_-]') def make_filename(string): + # type: (str) -> unicode return no_fn_re.sub('', string) or 'sphinx' def ustrftime(format, *args): + # type: (unicode, Any) -> unicode # [DEPRECATED] strftime for unicode strings # It will be removed at Sphinx-1.5 if not args: @@ -171,7 +185,7 @@ def ustrftime(format, *args): source_date_epoch = os.getenv('SOURCE_DATE_EPOCH') if source_date_epoch is not None: time_struct = time.gmtime(float(source_date_epoch)) - args = [time_struct] + args = [time_struct] # type: ignore if PY2: # if a locale is set, the time strings are encoded in the encoding # given by LC_TIME; if that is available, use it @@ -188,16 +202,18 @@ def ustrftime(format, *args): def safe_relpath(path, start=None): + # type: (unicode, unicode) -> unicode try: return os.path.relpath(path, start) except ValueError: return path -fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding() +fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding() # type: unicode def abspath(pathdir): + # type: (unicode) -> unicode pathdir = path.abspath(pathdir) if isinstance(pathdir, bytes): pathdir = pathdir.decode(fs_encoding) @@ -205,6 +221,7 @@ def abspath(pathdir): def getcwd(): + # type: () -> unicode if hasattr(os, 'getcwdu'): return os.getcwdu() return os.getcwd() @@ -212,6 +229,7 @@ def getcwd(): @contextlib.contextmanager def cd(target_dir): + # type: (unicode) -> Iterator[None] cwd = getcwd() try: os.chdir(target_dir) @@ -233,10 +251,12 @@ class FileAvoidWrite(object): Objects can be used as context managers. """ def __init__(self, path): + # type: (unicode) -> None self._path = path - self._io = None + self._io = None # type: Union[StringIO, BytesIO] def write(self, data): + # type: (Union[str, bytes]) -> None if not self._io: if isinstance(data, text_type): self._io = StringIO() @@ -246,6 +266,7 @@ class FileAvoidWrite(object): self._io.write(data) def close(self): + # type: () -> None """Stop accepting writes and write file, if needed.""" if not self._io: raise Exception('FileAvoidWrite does not support empty files.') @@ -288,6 +309,7 @@ class FileAvoidWrite(object): def rmtree(path): + # type: (unicode) -> None if os.path.isdir(path): shutil.rmtree(path) else: diff --git a/sphinx/util/parallel.py b/sphinx/util/parallel.py index 4f4cd5c46..1d97a511c 100644 --- a/sphinx/util/parallel.py +++ b/sphinx/util/parallel.py @@ -13,15 +13,22 @@ import os import time import traceback from math import sqrt +from six import iteritems try: import multiprocessing except ImportError: multiprocessing = None -from six import iteritems - from sphinx.errors import SphinxParallelError +from sphinx.util import logging + +if False: + # For type annotation + from typing import Any, Callable, Sequence # NOQA + +logger = logging.getLogger(__name__) + # our parallel functionality only works for the forking Process parallel_available = multiprocessing and (os.name == 'posix') @@ -31,9 +38,11 @@ class SerialTasks(object): """Has the same interface as ParallelTasks, but executes tasks directly.""" def __init__(self, nproc=1): + # type: (int) -> None pass def add_task(self, task_func, arg=None, result_func=None): + # type: (Callable, Any, Callable) -> None if arg is not None: res = task_func(arg) else: @@ -42,6 +51,7 @@ class SerialTasks(object): result_func(res) def join(self): + # type: () -> None pass @@ -49,37 +59,45 @@ class ParallelTasks(object): """Executes *nproc* tasks in parallel after forking.""" def __init__(self, nproc): + # type: (int) -> None self.nproc = nproc # (optional) function performed by each task on the result of main task - self._result_funcs = {} + self._result_funcs = {} # type: Dict[int, Callable] # task arguments - self._args = {} + self._args = {} # type: Dict[int, List[Any]] # list of subprocesses (both started and waiting) - self._procs = {} + self._procs = {} # type: Dict[int, multiprocessing.Process] # list of receiving pipe connections of running subprocesses - self._precvs = {} + self._precvs = {} # type: Dict[int, Any] # list of receiving pipe connections of waiting subprocesses - self._precvsWaiting = {} + self._precvsWaiting = {} # type: Dict[int, Any] # number of working subprocesses self._pworking = 0 # task number of each subprocess self._taskid = 0 def _process(self, pipe, func, arg): + # type: (Any, Callable, Any) -> None try: - if arg is None: - ret = func() - else: - ret = func(arg) - pipe.send((False, ret)) + collector = logging.LogCollector() + with collector.collect(): + if arg is None: + ret = func() + else: + ret = func(arg) + failed = False except BaseException as err: - errmsg = traceback.format_exception_only(err.__class__, err)[0].strip() - pipe.send((True, (errmsg, traceback.format_exc()))) + failed = True + errmsg = traceback.format_exception_only(err.__class__, err)[0].strip() # type: ignore # NOQA + ret = (errmsg, traceback.format_exc()) + logging.convert_serializable(collector.logs) + pipe.send((failed, collector.logs, ret)) def add_task(self, task_func, arg=None, result_func=None): + # type: (Callable, Any, Callable) -> None tid = self._taskid self._taskid += 1 - self._result_funcs[tid] = result_func or (lambda arg: None) + self._result_funcs[tid] = result_func or (lambda arg, result: None) self._args[tid] = arg precv, psend = multiprocessing.Pipe(False) proc = multiprocessing.Process(target=self._process, @@ -89,15 +107,19 @@ class ParallelTasks(object): self._join_one() def join(self): + # type: () -> None while self._pworking: self._join_one() def _join_one(self): + # type: () -> None for tid, pipe in iteritems(self._precvs): if pipe.poll(): - exc, result = pipe.recv() + exc, logs, result = pipe.recv() if exc: raise SphinxParallelError(*result) + for log in logs: + logger.handle(log) self._result_funcs.pop(tid)(self._args.pop(tid), result) self._procs[tid].join() self._pworking -= 1 @@ -112,6 +134,7 @@ class ParallelTasks(object): def make_chunks(arguments, nproc, maxbatch=10): + # type: (Sequence[unicode], int, int) -> List[Any] # determine how many documents to read in one go nargs = len(arguments) chunksize = nargs // nproc diff --git a/sphinx/util/pycompat.py b/sphinx/util/pycompat.py index 69a5e07cf..185772cce 100644 --- a/sphinx/util/pycompat.py +++ b/sphinx/util/pycompat.py @@ -14,33 +14,62 @@ import sys import codecs import warnings -from six import class_types -from six import PY3, text_type, exec_ +from six import PY3, class_types, text_type, exec_ from six.moves import zip_longest from itertools import product from sphinx.deprecation import RemovedInSphinx16Warning +if False: + # For type annotation + from typing import Any, Callable # NOQA + + NoneType = type(None) # ------------------------------------------------------------------------------ # Python 2/3 compatibility +# prefix for Unicode strings if PY3: - # Python 3 - # prefix for Unicode strings u = '' +else: + u = 'u' + + +# TextIOWrapper +if PY3: from io import TextIOWrapper +else: + def TextIOWrapper(stream, encoding): + # type: (file, str) -> unicode + return codecs.lookup(encoding or 'ascii')[2](stream) - # safely encode a string for printing to the terminal + +# sys_encoding: some kind of default system encoding; should be used with +# a lenient error handler +if PY3: + sys_encoding = sys.getdefaultencoding() +else: + sys_encoding = __import__('locale').getpreferredencoding() + + +# terminal_safe(): safely encode a string for printing to the terminal +if PY3: def terminal_safe(s): + # type: (unicode) -> unicode return s.encode('ascii', 'backslashreplace').decode('ascii') - # some kind of default system encoding; should be used with a lenient - # error handler - sys_encoding = sys.getdefaultencoding() +else: + def terminal_safe(s): + # type: (unicode) -> unicode + return s.encode('ascii', 'backslashreplace') + +# convert_with_2to3(): +if PY3: # support for running 2to3 over config files def convert_with_2to3(filepath): + # type: (unicode) -> unicode from lib2to3.refactor import RefactoringTool, get_fixers_from_package from lib2to3.pgen2.parse import ParseError fixers = get_fixers_from_package('lib2to3.fixes') @@ -54,35 +83,27 @@ if PY3: # try to match ParseError details with SyntaxError details raise SyntaxError(err.msg, (filepath, lineno, offset, err.value)) return text_type(tree) - from html import escape as htmlescape # noqa: >= Python 3.2 +else: + # no need to refactor on 2.x versions + convert_with_2to3 = None # type: ignore + + +# htmlescape() +if PY3: + from html import escape as htmlescape +else: + from cgi import escape as htmlescape # NOQA + +# UnicodeMixin +if PY3: class UnicodeMixin(object): """Mixin class to handle defining the proper __str__/__unicode__ methods in Python 2 or 3.""" def __str__(self): return self.__unicode__() - - from textwrap import indent - else: - # Python 2 - u = 'u' - # no need to refactor on 2.x versions - convert_with_2to3 = None - - def TextIOWrapper(stream, encoding): - return codecs.lookup(encoding or 'ascii')[2](stream) - - # safely encode a string for printing to the terminal - def terminal_safe(s): - return s.encode('ascii', 'backslashreplace') - # some kind of default system encoding; should be used with a lenient - # error handler - sys_encoding = __import__('locale').getpreferredencoding() - # use Python 3 name - from cgi import escape as htmlescape # noqa: F401 - class UnicodeMixin(object): """Mixin class to handle defining the proper __str__/__unicode__ methods in Python 2 or 3.""" @@ -90,8 +111,14 @@ else: def __str__(self): return self.__unicode__().encode('utf8') + +# indent() +if PY3: + from textwrap import indent +else: # backport from python3 def indent(text, prefix, predicate=None): + # type: (unicode, unicode, Callable) -> unicode if predicate is None: def predicate(line): return line.strip() @@ -103,6 +130,7 @@ else: def execfile_(filepath, _globals, open=open): + # type: (unicode, Any, Callable) -> None from sphinx.util.osutil import fs_encoding # get config source -- 'b' is a no-op under 2.x, while 'U' is # ignored under 3.x (but 3.x compile() accepts \r\n newlines) @@ -134,6 +162,7 @@ def execfile_(filepath, _globals, open=open): class _DeprecationWrapper(object): def __init__(self, mod, deprecated): + # type: (Any, Dict) -> None self._mod = mod self._deprecated = deprecated @@ -147,7 +176,7 @@ class _DeprecationWrapper(object): return getattr(self._mod, attr) -sys.modules[__name__] = _DeprecationWrapper(sys.modules[__name__], dict( +sys.modules[__name__] = _DeprecationWrapper(sys.modules[__name__], dict( # type: ignore zip_longest = zip_longest, product = product, all = all, diff --git a/sphinx/util/requests.py b/sphinx/util/requests.py index 8b7204c2f..03e815c2c 100644 --- a/sphinx/util/requests.py +++ b/sphinx/util/requests.py @@ -22,7 +22,7 @@ try: except ImportError: # python-requests package in Debian jessie does not provide ``requests.packages.urllib3``. # So try to import the exceptions from urllib3 package. - from urllib3.exceptions import SSLError, InsecureRequestWarning + from urllib3.exceptions import SSLError, InsecureRequestWarning # type: ignore # try to load requests[security] try: @@ -77,7 +77,7 @@ def _get_tls_cacert(url, config): certs = getattr(config, 'tls_cacerts', None) if not certs: return True - elif isinstance(certs, (string_types, tuple)): + elif isinstance(certs, (string_types, tuple)): # type: ignore return certs else: hostname = urlsplit(url)[1] diff --git a/sphinx/util/stemmer/__init__.py b/sphinx/util/stemmer/__init__.py new file mode 100644 index 000000000..f36924223 --- /dev/null +++ b/sphinx/util/stemmer/__init__.py @@ -0,0 +1,51 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.stemmer + ~~~~~~~~~~~~~~~~~~~ + + Word stemming utilities for Sphinx. + + :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from sphinx.util.stemmer.porter import PorterStemmer + +try: + from Stemmer import Stemmer as _PyStemmer + PYSTEMMER = True +except ImportError: + PYSTEMMER = False + + +class BaseStemmer(object): + def stem(self, word): + # type: (unicode) -> unicode + raise NotImplemented + + +class PyStemmer(BaseStemmer): + def __init__(self): + # type: () -> None + self.stemmer = _PyStemmer('porter') + + def stem(self, word): + # type: (unicode) -> unicode + return self.stemmer.stemWord(word) + + +class StandardStemmer(BaseStemmer, PorterStemmer): # type: ignore + """All those porter stemmer implementations look hideous; + make at least the stem method nicer. + """ + def stem(self, word): # type: ignore + # type: (unicode) -> unicode + return PorterStemmer.stem(self, word, 0, len(word) - 1) + + +def get_stemmer(): + # type: () -> BaseStemmer + if PYSTEMMER: + return PyStemmer() + else: + return StandardStemmer() diff --git a/sphinx/util/stemmer.py b/sphinx/util/stemmer/porter.py index 47fc41e87..7cff74b6c 100644 --- a/sphinx/util/stemmer.py +++ b/sphinx/util/stemmer/porter.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """ - sphinx.util.stemmer - ~~~~~~~~~~~~~~~~~~~ + sphinx.util.stemmer.porter + ~~~~~~~~~~~~~~~~~~~~~~~~~~ Porter Stemming Algorithm diff --git a/sphinx/versioning.py b/sphinx/versioning.py index f6c446b4f..0f862ac67 100644 --- a/sphinx/versioning.py +++ b/sphinx/versioning.py @@ -16,6 +16,11 @@ from itertools import product from six import iteritems from six.moves import range, zip_longest +if False: + # For type annotation + from typing import Any, Iterator # NOQA + from docutils import nodes # NOQA + try: import Levenshtein IS_SPEEDUP = True @@ -27,6 +32,7 @@ VERSIONING_RATIO = 65 def add_uids(doctree, condition): + # type: (nodes.Node, Any) -> Iterator[nodes.Node] """Add a unique id to every node in the `doctree` which matches the condition and yield the nodes. @@ -42,6 +48,7 @@ def add_uids(doctree, condition): def merge_doctrees(old, new, condition): + # type: (nodes.Node, nodes.Node, Any) -> Iterator[nodes.Node] """Merge the `old` doctree with the `new` one while looking at nodes matching the `condition`. @@ -90,7 +97,7 @@ def merge_doctrees(old, new, condition): # choose the old node with the best ratio for each new node and set the uid # as long as the ratio is under a certain value, in which case we consider # them not changed but different - ratios = sorted(iteritems(ratios), key=itemgetter(1)) + ratios = sorted(iteritems(ratios), key=itemgetter(1)) # type: ignore for (old_node, new_node), ratio in ratios: if new_node in seen: continue @@ -109,6 +116,7 @@ def merge_doctrees(old, new, condition): def get_ratio(old, new): + # type: (unicode, unicode) -> float """Return a "similiarity ratio" (in percent) representing the similarity between the two strings where 0 is equal and anything above less than equal. """ @@ -122,6 +130,7 @@ def get_ratio(old, new): def levenshtein_distance(a, b): + # type: (unicode, unicode) -> int """Return the Levenshtein edit distance between two strings *a* and *b*.""" if a == b: return 0 @@ -137,5 +146,5 @@ def levenshtein_distance(a, b): deletions = current_row[j] + 1 substitutions = previous_row[j] + (column1 != column2) current_row.append(min(insertions, deletions, substitutions)) - previous_row = current_row + previous_row = current_row # type: ignore return previous_row[-1] diff --git a/sphinx/websupport/__init__.py b/sphinx/websupport/__init__.py index 69914da95..f7b215f83 100644 --- a/sphinx/websupport/__init__.py +++ b/sphinx/websupport/__init__.py @@ -66,7 +66,7 @@ class WebSupport(object): self._init_search(search) self._init_storage(storage) - self._globalcontext = None + self._globalcontext = None # type: ignore self._make_base_comment_options() @@ -119,7 +119,7 @@ class WebSupport(object): raise RuntimeError('No srcdir associated with WebSupport object') app = Sphinx(self.srcdir, self.srcdir, self.outdir, self.doctreedir, 'websupport', status=self.status, warning=self.warning) - app.builder.set_webinfo(self.staticdir, self.staticroot, + app.builder.set_webinfo(self.staticdir, self.staticroot, # type: ignore self.search, self.storage) self.storage.pre_build() @@ -384,7 +384,7 @@ class WebSupport(object): that remains the same throughout the lifetime of the :class:`~sphinx.websupport.WebSupport` object. """ - self.base_comment_opts = {} + self.base_comment_opts = {} # type: Dict[unicode, unicode] if self.docroot != '': comment_urls = [ diff --git a/sphinx/websupport/storage/sqlalchemy_db.py b/sphinx/websupport/storage/sqlalchemy_db.py index b412ad488..16418ec8f 100644 --- a/sphinx/websupport/storage/sqlalchemy_db.py +++ b/sphinx/websupport/storage/sqlalchemy_db.py @@ -14,7 +14,7 @@ from datetime import datetime from sqlalchemy import Column, Integer, Text, String, Boolean, \ ForeignKey, DateTime -from sqlalchemy.orm import relation, sessionmaker, aliased +from sqlalchemy.orm import relation, sessionmaker, aliased # type: ignore from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() @@ -23,7 +23,7 @@ Session = sessionmaker() db_prefix = 'sphinx_' -class Node(Base): +class Node(Base): # type: ignore """Data about a Node in a doctree.""" __tablename__ = db_prefix + 'nodes' @@ -74,7 +74,7 @@ class Node(Base): :param results: the flat list of comments :param username: the name of the user requesting the comments. """ - comments = [] + comments = [] # type: List list_stack = [comments] for r in results: if username: @@ -101,7 +101,7 @@ class Node(Base): self.source = source -class CommentVote(Base): +class CommentVote(Base): # type: ignore """A vote a user has made on a Comment.""" __tablename__ = db_prefix + 'commentvote' @@ -117,7 +117,7 @@ class CommentVote(Base): self.value = value -class Comment(Base): +class Comment(Base): # type: ignore """An individual Comment being stored.""" __tablename__ = db_prefix + 'comments' diff --git a/sphinx/websupport/storage/sqlalchemystorage.py b/sphinx/websupport/storage/sqlalchemystorage.py index c8794f75c..8b7d76714 100644 --- a/sphinx/websupport/storage/sqlalchemystorage.py +++ b/sphinx/websupport/storage/sqlalchemystorage.py @@ -12,7 +12,7 @@ from datetime import datetime import sqlalchemy -from sqlalchemy.orm import aliased +from sqlalchemy.orm import aliased # type: ignore from sqlalchemy.sql import func from sphinx.websupport.errors import CommentNotAllowedError, \ @@ -22,7 +22,7 @@ from sphinx.websupport.storage.sqlalchemy_db import Base, Node, \ Comment, CommentVote, Session from sphinx.websupport.storage.differ import CombinedHtmlDiff -if sqlalchemy.__version__[:3] < '0.5': +if sqlalchemy.__version__[:3] < '0.5': # type: ignore raise ImportError('SQLAlchemy version 0.5 or greater is required for this ' 'storage backend; you have version %s' % sqlalchemy.__version__) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 016c04bd6..4cc669a36 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -13,18 +13,19 @@ import sys import posixpath import os import copy -import warnings from six import string_types from docutils import nodes from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator from sphinx import addnodes -from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.locale import admonitionlabels, _ +from sphinx.util import logging from sphinx.util.images import get_image_size from sphinx.util.smartypants import sphinx_smarty_pants +logger = logging.getLogger(__name__) + # A good overview of the purpose behind these classes can be found here: # http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html @@ -289,7 +290,7 @@ class HTMLTranslator(BaseTranslator): prefix = self.builder.config.numfig_format.get(figtype) if prefix is None: msg = 'numfig_format is not defined for %s' % figtype - self.builder.warn(msg) + logger.warning(msg) else: numbers = self.builder.fignumbers[key][figure_id] self.body.append(prefix % '.'.join(map(str, numbers)) + ' ') @@ -299,7 +300,7 @@ class HTMLTranslator(BaseTranslator): if figtype: if len(node['ids']) == 0: msg = 'Any IDs not assigned for %s node' % node.tagname - self.builder.env.warn_node(msg, node) + logger.warning(msg, location=node) else: append_fignumber(figtype, node['ids'][0]) @@ -385,11 +386,10 @@ class HTMLTranslator(BaseTranslator): else: opts = {} - def warner(msg, **kwargs): - self.builder.warn(msg, (self.builder.current_docname, node.line), **kwargs) highlighted = self.highlighter.highlight_block( - node.rawsource, lang, opts=opts, warn=warner, linenos=linenos, - **highlight_args) + node.rawsource, lang, opts=opts, linenos=linenos, + location=(self.builder.current_docname, node.line), **highlight_args + ) starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) self.body.append(starttag + highlighted + '</div>\n') @@ -544,8 +544,8 @@ class HTMLTranslator(BaseTranslator): if not ('width' in node and 'height' in node): size = get_image_size(os.path.join(self.builder.srcdir, olduri)) if size is None: - self.builder.env.warn_node('Could not obtain image size. ' - ':scale: option is ignored.', node) + logger.warning('Could not obtain image size. :scale: option is ignored.', + location=node) else: if 'width' not in node: node['width'] = str(size[0]) @@ -716,14 +716,6 @@ class HTMLTranslator(BaseTranslator): def depart_definition(self, node): self.body.append('</dd>\n') - def visit_termsep(self, node): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6. ' - 'This warning is displayed because some Sphinx extension ' - 'uses sphinx.addnodes.termsep. Please report it to ' - 'author of the extension.', RemovedInSphinx16Warning) - self.body.append('<br />') - raise nodes.SkipNode - def visit_manpage(self, node): return self.visit_literal_emphasis(node) @@ -758,10 +750,10 @@ class HTMLTranslator(BaseTranslator): self.body.append(self.starttag(node, 'tr', '', CLASS='field')) def visit_math(self, node, math_env=''): - self.builder.warn('using "math" markup without a Sphinx math extension ' - 'active, please use one of the math extensions ' - 'described at http://sphinx-doc.org/ext/math.html', - (self.builder.current_docname, node.line)) + logger.warning('using "math" markup without a Sphinx math extension ' + 'active, please use one of the math extensions ' + 'described at http://sphinx-doc.org/ext/math.html', + location=(self.builder.current_docname, node.line)) raise nodes.SkipNode def unknown_visit(self, node): diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 70a9c6f68..221d2b2ac 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -15,7 +15,6 @@ import re import sys from os import path -import warnings from six import itervalues, text_type from docutils import nodes, writers @@ -24,15 +23,20 @@ from docutils.writers.latex2e import Babel from sphinx import addnodes from sphinx import highlighting from sphinx.errors import SphinxError -from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.locale import admonitionlabels, _ -from sphinx.util import split_into +from sphinx.util import split_into, logging from sphinx.util.i18n import format_date from sphinx.util.nodes import clean_astext, traverse_parent from sphinx.util.template import LaTeXRenderer from sphinx.util.texescape import tex_escape_map, tex_replace_map from sphinx.util.smartypants import educate_quotes_latex +if False: + # For type annotation + from typing import Any, Callable, Iterator, Pattern, Tuple, Union # NOQA + from sphinx.builder import Builder # NOQA + +logger = logging.getLogger(__name__) BEGIN_DOC = r''' \begin{document} @@ -97,7 +101,7 @@ DEFAULT_SETTINGS = { 'tocdepth': '', 'secnumdepth': '', 'pageautorefname': '', -} +} # type: Dict[unicode, unicode] ADDITIONAL_SETTINGS = { 'pdflatex': { @@ -123,7 +127,7 @@ ADDITIONAL_SETTINGS = { 'platex': { 'latex_engine': 'platex', }, -} +} # type: Dict[unicode, Dict[unicode, unicode]] class collected_footnote(nodes.footnote): @@ -143,17 +147,19 @@ class LaTeXWriter(writers.Writer): ('Document class', ['--docclass'], {'default': 'manual'}), ('Author', ['--author'], {'default': ''}), )) - settings_defaults = {} + settings_defaults = {} # type: Dict output = None def __init__(self, builder): + # type: (Builder) -> None writers.Writer.__init__(self) self.builder = builder self.translator_class = ( self.builder.translator_class or LaTeXTranslator) def translate(self): + # type: () -> None transform = ShowUrlsTransform(self.document) transform.apply() visitor = self.translator_class(self.document, self.builder) @@ -165,10 +171,12 @@ class LaTeXWriter(writers.Writer): class ExtBabel(Babel): def __init__(self, language_code): + # type: (unicode) -> None super(ExtBabel, self).__init__(language_code or '') self.language_code = language_code def get_shorthandoff(self): + # type: () -> unicode shortlang = self.language.split('_')[0] if shortlang in ('de', 'ngerman', 'sl', 'slovene', 'pt', 'portuges', 'es', 'spanish', 'nl', 'dutch', 'pl', 'polish', 'it', @@ -179,15 +187,18 @@ class ExtBabel(Babel): return '' def uses_cyrillic(self): + # type: () -> bool shortlang = self.language.split('_')[0] return shortlang in ('bg', 'bulgarian', 'kk', 'kazakh', 'mn', 'mongolian', 'ru', 'russian', 'uk', 'ukrainian') def is_supported_language(self): + # type: () -> bool return bool(super(ExtBabel, self).get_language()) def get_language(self): + # type: () -> unicode language = super(ExtBabel, self).get_language() if not language: return 'english' # fallback to english @@ -199,9 +210,11 @@ class ShowUrlsTransform(object): expanded = False def __init__(self, document): + # type: (nodes.Node) -> None self.document = document def apply(self): + # type: () -> None # replace id_prefix temporarily id_prefix = self.document.settings.id_prefix self.document.settings.id_prefix = 'show_urls' @@ -214,6 +227,7 @@ class ShowUrlsTransform(object): self.document.settings.id_prefix = id_prefix def expand_show_urls(self): + # type: () -> None show_urls = self.document.settings.env.config.latex_show_urls if show_urls is False or show_urls == 'no': return @@ -236,6 +250,7 @@ class ShowUrlsTransform(object): node.parent.insert(index + 1, textnode) def create_footnote(self, uri): + # type: (unicode) -> List[Union[nodes.footnote, nodes.footnote_ref]] label = nodes.label('', '#') para = nodes.paragraph() para.append(nodes.reference('', nodes.Text(uri), refuri=uri, nolinkurl=True)) @@ -252,7 +267,9 @@ class ShowUrlsTransform(object): return [footnote, footnote_ref] def renumber_footnotes(self): + # type: () -> None def is_used_number(number): + # type: (unicode) -> bool for node in self.document.traverse(nodes.footnote): if not node.get('auto') and number in node['names']: return True @@ -260,13 +277,16 @@ class ShowUrlsTransform(object): return False def is_auto_footnote(node): + # type: (nodes.Node) -> bool return isinstance(node, nodes.footnote) and node.get('auto') def footnote_ref_by(node): + # type: (nodes.Node) -> Callable[[nodes.Node], bool] ids = node['ids'] parent = list(traverse_parent(node, (nodes.document, addnodes.start_of_file)))[0] def is_footnote_ref(node): + # type: (nodes.Node) -> bool return (isinstance(node, nodes.footnote_reference) and ids[0] == node['refid'] and parent in list(traverse_parent(node))) @@ -295,23 +315,26 @@ class ShowUrlsTransform(object): class Table(object): def __init__(self): + # type: () -> None self.col = 0 self.colcount = 0 - self.colspec = None + self.colspec = None # type: unicode self.rowcount = 0 self.had_head = False self.has_problematic = False self.has_verbatim = False - self.caption = None + self.caption = None # type: List[unicode] self.longtable = False def escape_abbr(text): + # type: (unicode) -> unicode """Adjust spacing after abbreviations.""" return re.sub('\.(?=\s|$)', '.\\@', text) def rstdim_to_latexdim(width_str): + # type: (unicode) -> unicode """Convert `width_str` with rst length to LaTeX length.""" match = re.match('^(\d*\.?\d*)\s*(\S*)$', width_str) if not match: @@ -338,9 +361,10 @@ class LaTeXTranslator(nodes.NodeVisitor): docclasses = ('howto', 'manual') def __init__(self, document, builder): + # type: (nodes.Node, Builder) -> None nodes.NodeVisitor.__init__(self, document) self.builder = builder - self.body = [] + self.body = [] # type: List[unicode] # flags self.in_title = 0 @@ -357,8 +381,8 @@ class LaTeXTranslator(nodes.NodeVisitor): self.no_contractions = 0 self.compact_list = 0 self.first_param = 0 - self.remember_multirow = {} - self.remember_multirowcol = {} + self.remember_multirow = {} # type: Dict[int, int] + self.remember_multirowcol = {} # type: Dict[int, int] # determine top section level if builder.config.latex_toplevel_sectioning: @@ -413,8 +437,8 @@ class LaTeXTranslator(nodes.NodeVisitor): if builder.config.language and not self.babel.is_supported_language(): # emit warning if specified language is invalid # (only emitting, nothing changed to processing) - self.builder.warn('no Babel option known for language %r' % - builder.config.language) + logger.warning('no Babel option known for language %r', + builder.config.language) # simply use babel.get_language() always, as get_language() returns # 'english' even if language is invalid or empty @@ -448,6 +472,7 @@ class LaTeXTranslator(nodes.NodeVisitor): if getattr(builder, 'usepackages', None): def declare_package(packagename, options=None): + # type:(unicode, unicode) -> unicode if options: return '\\usepackage[%s]{%s}' % (options, packagename) else: @@ -464,7 +489,7 @@ class LaTeXTranslator(nodes.NodeVisitor): tocdepth = document['tocdepth'] + self.top_sectionlevel - 2 maxdepth = len(self.sectionnames) - self.top_sectionlevel if tocdepth > maxdepth: - self.builder.warn('too large :maxdepth:, ignored.') + logger.warning('too large :maxdepth:, ignored.') tocdepth = maxdepth self.elements['tocdepth'] = '\\setcounter{tocdepth}{%d}' % tocdepth @@ -495,54 +520,61 @@ class LaTeXTranslator(nodes.NodeVisitor): self.highlighter = highlighting.PygmentsBridge( 'latex', builder.config.pygments_style, builder.config.trim_doctest_flags) - self.context = [] - self.descstack = [] - self.bibitems = [] - self.table = None - self.next_table_colspec = None + self.context = [] # type: List[Any] + self.descstack = [] # type: List[unicode] + self.bibitems = [] # type: List[List[unicode]] + self.table = None # type: Table + self.next_table_colspec = None # type: unicode # stack of [language, linenothreshold] settings per file # the first item here is the default and must not be changed # the second item is the default for the master file and can be changed # by .. highlight:: directive in the master file self.hlsettingstack = 2 * [[builder.config.highlight_language, sys.maxsize]] - self.bodystack = [] - self.footnotestack = [] + self.bodystack = [] # type: List[List[unicode]] + self.footnotestack = [] # type: List[Dict[unicode, List[Union[collected_footnote, bool]]]] # NOQA self.footnote_restricted = False - self.pending_footnotes = [] - self.curfilestack = [] - self.handled_abbrs = set() - self.next_hyperlink_ids = {} - self.next_section_ids = set() + self.pending_footnotes = [] # type: List[nodes.footnote_reference] + self.curfilestack = [] # type: List[unicode] + self.handled_abbrs = set() # type: Set[unicode] + self.next_hyperlink_ids = {} # type: Dict[unicode, Set[unicode]] + self.next_section_ids = set() # type: Set[unicode] def pushbody(self, newbody): + # type: (List[unicode]) -> None self.bodystack.append(self.body) self.body = newbody def popbody(self): + # type: () -> List[unicode] body = self.body self.body = self.bodystack.pop() return body def push_hyperlink_ids(self, figtype, ids): + # type: (unicode, Set[unicode]) -> None hyperlink_ids = self.next_hyperlink_ids.setdefault(figtype, set()) hyperlink_ids.update(ids) def pop_hyperlink_ids(self, figtype): + # type: (unicode) -> Set[unicode] return self.next_hyperlink_ids.pop(figtype, set()) def check_latex_elements(self): + # type: () -> None for key in self.builder.config.latex_elements: if key not in self.elements: msg = _("Unknown configure key: latex_elements[%r] is ignored.") - self.builder.warn(msg % key) + logger.warning(msg % key) def restrict_footnote(self, node): + # type: (nodes.Node) -> None if self.footnote_restricted is False: self.footnote_restricted = node self.pending_footnotes = [] def unrestrict_footnote(self, node): + # type: (nodes.Node) -> None if self.footnote_restricted == node: self.footnote_restricted = False for footnode in self.pending_footnotes: @@ -551,6 +583,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.pending_footnotes = [] def format_docclass(self, docclass): + # type: (unicode) -> unicode """ prepends prefix to sphinx document classes """ if docclass in self.docclasses: @@ -558,6 +591,7 @@ class LaTeXTranslator(nodes.NodeVisitor): return docclass def astext(self): + # type: () -> unicode self.elements.update({ 'body': u''.join(self.body), 'indices': self.generate_indices() @@ -570,23 +604,28 @@ class LaTeXTranslator(nodes.NodeVisitor): return LaTeXRenderer().render(DEFAULT_TEMPLATE, self.elements) def hypertarget(self, id, withdoc=True, anchor=True): + # type: (unicode, bool, bool) -> unicode if withdoc: id = self.curfilestack[-1] + ':' + id return (anchor and '\\phantomsection' or '') + \ '\\label{%s}' % self.idescape(id) def hyperlink(self, id): + # type: (unicode) -> unicode return '{\\hyperref[%s]{' % self.idescape(id) def hyperpageref(self, id): + # type: (unicode) -> unicode return '\\autopageref*{%s}' % self.idescape(id) def idescape(self, id): + # type: (unicode) -> unicode return '\\detokenize{%s}' % text_type(id).translate(tex_replace_map).\ encode('ascii', 'backslashreplace').decode('ascii').\ replace('\\', '_') def babel_renewcommand(self, command, definition): + # type: (unicode, unicode) -> unicode if self.elements['multilingual']: prefix = '\\addto\\captions%s{' % self.babel.get_language() suffix = '}' @@ -597,6 +636,7 @@ class LaTeXTranslator(nodes.NodeVisitor): return ('%s\\renewcommand{%s}{%s}%s\n' % (prefix, command, definition, suffix)) def babel_defmacro(self, name, definition): + # type: (unicode, unicode) -> unicode if self.elements['babel']: prefix = '\\addto\\extras%s{' % self.babel.get_language() suffix = '}' @@ -607,7 +647,8 @@ class LaTeXTranslator(nodes.NodeVisitor): return ('%s\\def%s{%s}%s\n' % (prefix, name, definition, suffix)) def generate_numfig_format(self, builder): - ret = [] + # type: (Builder) -> unicode + ret = [] # type: List[unicode] figure = self.builder.config.numfig_format['figure'].split('%s', 1) if len(figure) == 1: ret.append('\\def\\fnum@figure{%s}\n' % @@ -646,7 +687,9 @@ class LaTeXTranslator(nodes.NodeVisitor): return ''.join(ret) def generate_indices(self): + # type: (Builder) -> unicode def generate(content, collapsed): + # type: (List[Tuple[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]]], bool) -> unicode # NOQA ret.append('\\begin{sphinxtheindex}\n') ret.append('\\def\\bigletter#1{{\\Large\\sffamily#1}' '\\nopagebreak\\vspace{1mm}}\n') @@ -676,10 +719,6 @@ class LaTeXTranslator(nodes.NodeVisitor): if isinstance(indices_config, list): if indexname not in indices_config: continue - # deprecated config value - if indexname == 'py-modindex' and \ - not self.builder.config.latex_use_modindex: - continue content, collapsed = indexcls(domain).generate( self.builder.docnames) if not content: @@ -691,6 +730,7 @@ class LaTeXTranslator(nodes.NodeVisitor): return ''.join(ret) def visit_document(self, node): + # type: (nodes.Node) -> None self.footnotestack.append(self.collect_footnotes(node)) self.curfilestack.append(node.get('docname', '')) if self.first_document == 1: @@ -707,8 +747,9 @@ class LaTeXTranslator(nodes.NodeVisitor): self.sectionlevel = self.top_sectionlevel - 1 def depart_document(self, node): + # type: (nodes.Node) -> None if self.bibitems: - widest_label = "" + widest_label = "" # type: unicode for bi in self.bibitems: if len(widest_label) < len(bi[0]): widest_label = bi[0] @@ -723,6 +764,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.bibitems = [] def visit_start_of_file(self, node): + # type: (nodes.Node) -> None # collect new footnotes self.footnotestack.append(self.collect_footnotes(node)) # also add a document target @@ -732,7 +774,9 @@ class LaTeXTranslator(nodes.NodeVisitor): self.hlsettingstack.append(self.hlsettingstack[0]) def collect_footnotes(self, node): + # type: (nodes.Node) -> Dict[unicode, List[Union[collected_footnote, bool]]] def footnotes_under(n): + # type: (nodes.Node) -> Iterator[nodes.Node] if isinstance(n, nodes.footnote): yield n else: @@ -741,7 +785,8 @@ class LaTeXTranslator(nodes.NodeVisitor): continue for k in footnotes_under(c): yield k - fnotes = {} + + fnotes = {} # type: Dict[unicode, List[Union[collected_footnote, bool]]] for fn in footnotes_under(node): num = fn.children[0].astext().strip() newnode = collected_footnote(*fn.children, number=num) @@ -749,15 +794,18 @@ class LaTeXTranslator(nodes.NodeVisitor): return fnotes def depart_start_of_file(self, node): + # type: (nodes.Node) -> None self.footnotestack.pop() self.curfilestack.pop() self.hlsettingstack.pop() def visit_highlightlang(self, node): + # type: (nodes.Node) -> None self.hlsettingstack[-1] = [node['lang'], node['linenothreshold']] raise nodes.SkipNode def visit_section(self, node): + # type: (nodes.Node) -> None if not self.this_is_the_title: self.sectionlevel += 1 self.body.append('\n\n') @@ -765,40 +813,50 @@ class LaTeXTranslator(nodes.NodeVisitor): self.next_section_ids.update(node['ids']) def depart_section(self, node): + # type: (nodes.Node) -> None self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) def visit_problematic(self, node): + # type: (nodes.Node) -> None self.body.append(r'{\color{red}\bfseries{}') def depart_problematic(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_topic(self, node): + # type: (nodes.Node) -> None self.in_minipage = 1 self.body.append('\n\\begin{sphinxShadowBox}\n') def depart_topic(self, node): + # type: (nodes.Node) -> None self.in_minipage = 0 self.body.append('\\end{sphinxShadowBox}\n') visit_sidebar = visit_topic depart_sidebar = depart_topic def visit_glossary(self, node): + # type: (nodes.Node) -> None pass def depart_glossary(self, node): + # type: (nodes.Node) -> None pass def visit_productionlist(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n\\begin{productionlist}\n') self.in_production_list = 1 def depart_productionlist(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{productionlist}\n\n') self.in_production_list = 0 def visit_production(self, node): + # type: (nodes.Node) -> None if node['tokenname']: tn = node['tokenname'] self.body.append(self.hypertarget('grammar-token-' + tn)) @@ -807,15 +865,19 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\\productioncont{') def depart_production(self, node): + # type: (nodes.Node) -> None self.body.append('}\n') def visit_transition(self, node): + # type: (nodes.Node) -> None self.body.append(self.elements['transition']) def depart_transition(self, node): + # type: (nodes.Node) -> None pass def visit_title(self, node): + # type: (nodes.Node) -> None parent = node.parent if isinstance(parent, addnodes.seealso): # the environment already handles this @@ -824,8 +886,8 @@ class LaTeXTranslator(nodes.NodeVisitor): if self.this_is_the_title: if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): - self.builder.warn('document title is not a single Text node', - (self.curfilestack[-1], node.line)) + logger.warning('document title is not a single Text node', + location=(self.curfilestack[-1], node.line)) if not self.elements['title']: # text needs to be escaped since it is inserted into # the output literally @@ -863,15 +925,15 @@ class LaTeXTranslator(nodes.NodeVisitor): # Redirect body output until title is finished. self.pushbody([]) else: - self.builder.warn( - 'encountered title node not in section, topic, table, ' - 'admonition or sidebar', - (self.curfilestack[-1], node.line or '')) + logger.warning('encountered title node not in section, topic, table, ' + 'admonition or sidebar', + location=(self.curfilestack[-1], node.line or '')) self.body.append('\\sphinxstyleothertitle{') self.context.append('}\n') self.in_title = 1 def depart_title(self, node): + # type: (nodes.Node) -> None self.in_title = 0 if isinstance(node.parent, nodes.table): self.table.caption = self.popbody() @@ -880,6 +942,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.unrestrict_footnote(node) def visit_subtitle(self, node): + # type: (nodes.Node) -> None if isinstance(node.parent, nodes.sidebar): self.body.append('\\sphinxstylesidebarsubtitle{') self.context.append('}\n') @@ -887,17 +950,21 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append('') def depart_subtitle(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) def visit_desc(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n\\begin{fulllineitems}\n') if self.table: self.table.has_problematic = True def depart_desc(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\end{fulllineitems}\n\n') def _visit_signature_line(self, node): + # type: (nodes.Node) -> None for child in node: if isinstance(child, addnodes.desc_parameterlist): self.body.append(r'\pysiglinewithargsret{') @@ -906,9 +973,11 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append(r'\pysigline{') def _depart_signature_line(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_desc_signature(self, node): + # type: (nodes.Node) -> None if node.parent['objtype'] != 'describe' and node['ids']: hyper = self.hypertarget(node['ids'][0]) else: @@ -920,57 +989,71 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('%\n\\pysigstartmultiline\n') def depart_desc_signature(self, node): + # type: (nodes.Node) -> None if not node.get('is_multiline'): self._depart_signature_line(node) else: self.body.append('%\n\\pysigstopmultiline') def visit_desc_signature_line(self, node): + # type: (nodes.Node) -> None self._visit_signature_line(node) def depart_desc_signature_line(self, node): + # type: (nodes.Node) -> None self._depart_signature_line(node) def visit_desc_addname(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxcode{') self.literal_whitespace += 1 def depart_desc_addname(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.literal_whitespace -= 1 def visit_desc_type(self, node): + # type: (nodes.Node) -> None pass def depart_desc_type(self, node): + # type: (nodes.Node) -> None pass def visit_desc_returns(self, node): + # type: (nodes.Node) -> None self.body.append(r'{ $\rightarrow$ ') def depart_desc_returns(self, node): + # type: (nodes.Node) -> None self.body.append(r'}') def visit_desc_name(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxbfcode{') self.no_contractions += 1 self.literal_whitespace += 1 def depart_desc_name(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.literal_whitespace -= 1 self.no_contractions -= 1 def visit_desc_parameterlist(self, node): + # type: (nodes.Node) -> None # close name, open parameterlist self.body.append('}{') self.first_param = 1 def depart_desc_parameterlist(self, node): + # type: (nodes.Node) -> None # close parameterlist, open return annotation self.body.append('}{') def visit_desc_parameter(self, node): + # type: (nodes.Node) -> None if not self.first_param: self.body.append(', ') else: @@ -979,36 +1062,46 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append(r'\emph{') def depart_desc_parameter(self, node): + # type: (nodes.Node) -> None if not node.hasattr('noemph'): self.body.append('}') def visit_desc_optional(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxoptional{') def depart_desc_optional(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_desc_annotation(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxstrong{') def depart_desc_annotation(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_desc_content(self, node): + # type: (nodes.Node) -> None if node.children and not isinstance(node.children[0], nodes.paragraph): # avoid empty desc environment which causes a formatting bug self.body.append('~') def depart_desc_content(self, node): + # type: (nodes.Node) -> None pass def visit_seealso(self, node): + # type: (nodes.Node) -> None self.body.append(u'\n\n\\sphinxstrong{%s:}\n\n' % admonitionlabels['seealso']) def depart_seealso(self, node): + # type: (nodes.Node) -> None self.body.append("\n\n") def visit_rubric(self, node): + # type: (nodes.Node) -> None if len(node.children) == 1 and node.children[0].astext() in \ ('Footnotes', _('Footnotes')): raise nodes.SkipNode @@ -1017,13 +1110,16 @@ class LaTeXTranslator(nodes.NodeVisitor): self.in_title = 1 def depart_rubric(self, node): + # type: (nodes.Node) -> None self.in_title = 0 self.body.append(self.context.pop()) def visit_footnote(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_collected_footnote(self, node): + # type: (nodes.Node) -> None self.in_footnote += 1 if 'footnotetext' in node: self.body.append('%%\n\\begin{footnotetext}[%s]' @@ -1033,6 +1129,7 @@ class LaTeXTranslator(nodes.NodeVisitor): '\\sphinxAtStartFootnote\n' % node['number']) def depart_collected_footnote(self, node): + # type: (nodes.Node) -> None if 'footnotetext' in node: self.body.append('%\n\\end{footnotetext}') else: @@ -1040,6 +1137,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.in_footnote -= 1 def visit_label(self, node): + # type: (nodes.Node) -> None if isinstance(node.parent, nodes.citation): self.bibitems[-1][0] = node.astext() self.bibitems[-1][2] = self.curfilestack[-1] @@ -1047,23 +1145,26 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_tabular_col_spec(self, node): + # type: (nodes.Node) -> None self.next_table_colspec = node['spec'] raise nodes.SkipNode def visit_table(self, node): + # type: (nodes.Node) -> None if self.table: raise UnsupportedError( '%s:%s: nested tables are not yet implemented.' % (self.curfilestack[-1], node.line or '')) self.table = Table() self.table.longtable = 'longtable' in node['classes'] - self.tablebody = [] - self.tableheaders = [] + self.tablebody = [] # type: List[unicode] + self.tableheaders = [] # type: List[unicode] # Redirect body output until table is finished. self.pushbody(self.tablebody) self.restrict_footnote(node) def depart_table(self, node): + # type: (nodes.Node) -> None if self.table.rowcount > 30: self.table.longtable = True self.popbody() @@ -1140,18 +1241,23 @@ class LaTeXTranslator(nodes.NodeVisitor): self.tablebody = None def visit_colspec(self, node): + # type: (nodes.Node) -> None self.table.colcount += 1 def depart_colspec(self, node): + # type: (nodes.Node) -> None pass def visit_tgroup(self, node): + # type: (nodes.Node) -> None pass def depart_tgroup(self, node): + # type: (nodes.Node) -> None pass def visit_thead(self, node): + # type: (nodes.Node) -> None self.table.had_head = True if self.next_table_colspec: self.table.colspec = '{%s}\n' % self.next_table_colspec @@ -1160,24 +1266,29 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body = self.tableheaders def depart_thead(self, node): + # type: (nodes.Node) -> None pass def visit_tbody(self, node): + # type: (nodes.Node) -> None if not self.table.had_head: self.visit_thead(node) self.body = self.tablebody def depart_tbody(self, node): + # type: (nodes.Node) -> None self.remember_multirow = {} self.remember_multirowcol = {} def visit_row(self, node): + # type: (nodes.Node) -> None self.table.col = 0 for key, value in self.remember_multirow.items(): if not value and key in self.remember_multirowcol: del self.remember_multirowcol[key] def depart_row(self, node): + # type: (nodes.Node) -> None self.body.append('\\\\\n') if any(self.remember_multirow.values()): linestart = 1 @@ -1198,6 +1309,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.rowcount += 1 def visit_entry(self, node): + # type: (nodes.Node) -> None if self.table.col == 0: while self.remember_multirow.get(self.table.col + 1, 0): self.table.col += 1 @@ -1259,6 +1371,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append(context) def depart_entry(self, node): + # type: (nodes.Node) -> None if self.in_merged_cell: self.in_merged_cell = 0 self.literal_whitespace -= 1 @@ -1272,6 +1385,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append(self.context.pop()) # header def visit_acks(self, node): + # type: (nodes.Node) -> None # this is a list in the source, but should be rendered as a # comma-separated list here self.body.append('\n\n') @@ -1281,16 +1395,19 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_bullet_list(self, node): + # type: (nodes.Node) -> None if not self.compact_list: self.body.append('\\begin{itemize}\n') if self.table: self.table.has_problematic = True def depart_bullet_list(self, node): + # type: (nodes.Node) -> None if not self.compact_list: self.body.append('\\end{itemize}\n') def visit_enumerated_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\begin{enumerate}\n') if 'start' in node: self.body.append('\\setcounter{enumi}{%d}\n' % (node['start'] - 1)) @@ -1298,33 +1415,41 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.has_problematic = True def depart_enumerated_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{enumerate}\n') def visit_list_item(self, node): + # type: (nodes.Node) -> None # Append "{}" in case the next character is "[", which would break # LaTeX's list environment (no numbering and the "[" is not printed). self.body.append(r'\item {} ') def depart_list_item(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_definition_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\begin{description}\n') if self.table: self.table.has_problematic = True def depart_definition_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{description}\n') def visit_definition_list_item(self, node): + # type: (nodes.Node) -> None pass def depart_definition_list_item(self, node): + # type: (nodes.Node) -> None pass def visit_term(self, node): + # type: (nodes.Node) -> None self.in_term += 1 - ctx = '}] \\leavevmode' + ctx = '}] \\leavevmode' # type: unicode if node.get('ids'): ctx += self.hypertarget(node['ids'][0]) self.body.append('\\item[{') @@ -1332,42 +1457,43 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append(ctx) def depart_term(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) self.unrestrict_footnote(node) self.in_term -= 1 - def visit_termsep(self, node): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6. ' - 'This warning is displayed because some Sphinx extension ' - 'uses sphinx.addnodes.termsep. Please report it to ' - 'author of the extension.', RemovedInSphinx16Warning) - self.body.append(', ') - raise nodes.SkipNode - def visit_classifier(self, node): + # type: (nodes.Node) -> None self.body.append('{[}') def depart_classifier(self, node): + # type: (nodes.Node) -> None self.body.append('{]}') def visit_definition(self, node): + # type: (nodes.Node) -> None pass def depart_definition(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_field_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\begin{quote}\\begin{description}\n') if self.table: self.table.has_problematic = True def depart_field_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{description}\\end{quote}\n') def visit_field(self, node): + # type: (nodes.Node) -> None pass def depart_field(self, node): + # type: (nodes.Node) -> None pass visit_field_name = visit_term @@ -1377,6 +1503,7 @@ class LaTeXTranslator(nodes.NodeVisitor): depart_field_body = depart_definition def visit_paragraph(self, node): + # type: (nodes.Node) -> None index = node.parent.index(node) if (index > 0 and isinstance(node.parent, nodes.compound) and not isinstance(node.parent[index - 1], nodes.paragraph) and @@ -1390,17 +1517,21 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\n') def depart_paragraph(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_centered(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\begin{center}') if self.table: self.table.has_problematic = True def depart_centered(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\end{center}') def visit_hlist(self, node): + # type: (nodes.Node) -> None # for now, we don't support a more compact list format # don't add individual itemize environments, but one for all columns self.compact_list += 1 @@ -1410,26 +1541,32 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.has_problematic = True def depart_hlist(self, node): + # type: (nodes.Node) -> None self.compact_list -= 1 self.body.append('\\end{itemize}\n') def visit_hlistcol(self, node): + # type: (nodes.Node) -> None pass def depart_hlistcol(self, node): + # type: (nodes.Node) -> None pass def latex_image_length(self, width_str): + # type: (nodes.Node) -> unicode try: return rstdim_to_latexdim(width_str) except ValueError: - self.builder.warn('dimension unit %s is invalid. Ignored.' % width_str) + logger.warning('dimension unit %s is invalid. Ignored.', width_str) def is_inline(self, node): + # type: (nodes.Node) -> bool """Check whether a node represents an inline element.""" return isinstance(node.parent, nodes.TextElement) def visit_image(self, node): + # type: (nodes.Node) -> None attrs = node.attributes pre = [] # in reverse order post = [] @@ -1502,10 +1639,12 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.extend(post) def depart_image(self, node): + # type: (nodes.Node) -> None pass def visit_figure(self, node): - ids = '' + # type: (nodes.Node) -> None + ids = '' # type: unicode for id in self.pop_hyperlink_ids('figure'): ids += self.hypertarget(id, anchor=False) if node['ids']: @@ -1561,10 +1700,12 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append(ids + align_end + '\\end{figure}\n') def depart_figure(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) self.unrestrict_footnote(node) def visit_caption(self, node): + # type: (nodes.Node) -> None self.in_caption += 1 self.restrict_footnote(node) if self.in_container_literal_block: @@ -1577,29 +1718,36 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\\caption{') def depart_caption(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.in_caption -= 1 self.unrestrict_footnote(node) def visit_legend(self, node): + # type: (nodes.Node) -> None self.body.append('{\\small ') def depart_legend(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_admonition(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\begin{sphinxadmonition}{note}') def depart_admonition(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{sphinxadmonition}\n') def _make_visit_admonition(name): def visit_admonition(self, node): + # type: (nodes.Node) -> None self.body.append(u'\n\\begin{sphinxadmonition}{%s}{%s:}' % (name, admonitionlabels[name])) return visit_admonition def _depart_named_admonition(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{sphinxadmonition}\n') visit_attention = _make_visit_admonition('attention') @@ -1622,13 +1770,17 @@ class LaTeXTranslator(nodes.NodeVisitor): depart_warning = _depart_named_admonition def visit_versionmodified(self, node): + # type: (nodes.Node) -> None pass def depart_versionmodified(self, node): + # type: (nodes.Node) -> None pass def visit_target(self, node): + # type: (nodes.Node) -> None def add_target(id): + # type: (unicode) -> None # indexing uses standard LaTeX index markup, so the targets # will be generated differently if id.startswith('index-'): @@ -1656,7 +1808,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.next_section_ids.update(node['ids']) return else: - domain = self.builder.env.domains['std'] + domain = self.builder.env.get_domain('std') figtype = domain.get_figtype(next) if figtype and domain.get_numfig_title(next): ids = set() @@ -1676,16 +1828,20 @@ class LaTeXTranslator(nodes.NodeVisitor): add_target(id) def depart_target(self, node): + # type: (nodes.Node) -> None pass def visit_attribution(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\begin{flushright}\n') self.body.append('---') def depart_attribution(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\end{flushright}\n') def visit_index(self, node, scre=re.compile(r';\s*')): + # type: (nodes.Node, Pattern) -> None if not node.get('inline', True): self.body.append('\n') entries = node['entries'] @@ -1715,18 +1871,19 @@ class LaTeXTranslator(nodes.NodeVisitor): p1, p2 = [self.encode(x) for x in split_into(2, 'seealso', string)] self.body.append(r'\index{%s|see{%s}}' % (p1, p2)) else: - self.builder.warn( - 'unknown index entry type %s found' % type) + logger.warning('unknown index entry type %s found', type) except ValueError as err: - self.builder.warn(str(err)) + logger.warning(str(err)) raise nodes.SkipNode def visit_raw(self, node): + # type: (nodes.Node) -> None if 'latex' in node.get('format', '').split(): self.body.append(node.astext()) raise nodes.SkipNode def visit_reference(self, node): + # type: (nodes.Node) -> None if not self.in_title: for id in node.get('ids'): anchor = not self.in_caption @@ -1780,14 +1937,16 @@ class LaTeXTranslator(nodes.NodeVisitor): else: self.context.append('}}}') else: - self.builder.warn('unusable reference target found: %s' % uri, - (self.curfilestack[-1], node.line)) + logger.warning('unusable reference target found: %s', uri, + location=(self.curfilestack[-1], node.line)) self.context.append('') def depart_reference(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) def visit_number_reference(self, node): + # type: (nodes.Node) -> None if node.get('refid'): id = self.curfilestack[-1] + ':' + node['refid'] else: @@ -1809,46 +1968,59 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_download_reference(self, node): + # type: (nodes.Node) -> None pass def depart_download_reference(self, node): + # type: (nodes.Node) -> None pass def visit_pending_xref(self, node): + # type: (nodes.Node) -> None pass def depart_pending_xref(self, node): + # type: (nodes.Node) -> None pass def visit_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxstyleemphasis{') def depart_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxstyleliteralemphasis{') self.no_contractions += 1 def depart_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.no_contractions -= 1 def visit_strong(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxstylestrong{') def depart_strong(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_literal_strong(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxstyleliteralstrong{') self.no_contractions += 1 def depart_literal_strong(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.no_contractions -= 1 def visit_abbreviation(self, node): + # type: (nodes.Node) -> None abbr = node.astext() self.body.append(r'\sphinxstyleabbreviation{') # spell out the explanation once @@ -1859,39 +2031,48 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append('}') def depart_abbreviation(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) def visit_manpage(self, node): + # type: (nodes.Node) -> Any return self.visit_literal_emphasis(node) def depart_manpage(self, node): + # type: (nodes.Node) -> Any return self.depart_literal_emphasis(node) def visit_title_reference(self, node): + # type: (nodes.Node) -> None self.body.append(r'\sphinxtitleref{') def depart_title_reference(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_citation(self, node): + # type: (nodes.Node) -> None # TODO maybe use cite bibitems # bibitem: [citelabel, citetext, docname, citeid] self.bibitems.append(['', '', '', '']) self.context.append(len(self.body)) def depart_citation(self, node): + # type: (nodes.Node) -> None size = self.context.pop() text = ''.join(self.body[size:]) del self.body[size:] self.bibitems[-1][1] = text def visit_citation_reference(self, node): + # type: (nodes.Node) -> None # This is currently never encountered, since citation_reference nodes # are already replaced by pending_xref nodes in the environment. self.body.append('\\cite{%s}' % self.idescape(node.astext())) raise nodes.SkipNode def visit_literal(self, node): + # type: (nodes.Node) -> None self.no_contractions += 1 if self.in_title: self.body.append(r'\sphinxstyleliteralintitle{') @@ -1899,10 +2080,12 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append(r'\sphinxcode{') def depart_literal(self, node): + # type: (nodes.Node) -> None self.no_contractions -= 1 self.body.append('}') def visit_footnote_reference(self, node): + # type: (nodes.Node) -> None num = node.astext().strip() try: footnode, used = self.footnotestack[-1][num] @@ -1918,18 +2101,20 @@ class LaTeXTranslator(nodes.NodeVisitor): self.pending_footnotes.append(footnode) else: self.footnotestack[-1][num][1] = True - footnode.walkabout(self) + footnode.walkabout(self) # type: ignore raise nodes.SkipChildren def depart_footnote_reference(self, node): + # type: (nodes.Node) -> None pass def visit_literal_block(self, node): + # type: (nodes.Node) -> None if node.rawsource != node.astext(): # most probably a parsed-literal block -- don't highlight self.body.append('\\begin{alltt}\n') else: - ids = '' + ids = '' # type: unicode for id in self.pop_hyperlink_ids('code-block'): ids += self.hypertarget(id, anchor=False) if node['ids']: @@ -1954,11 +2139,10 @@ class LaTeXTranslator(nodes.NodeVisitor): else: opts = {} - def warner(msg, **kwargs): - self.builder.warn(msg, (self.curfilestack[-1], node.line), **kwargs) - hlcode = self.highlighter.highlight_block(code, lang, opts=opts, - warn=warner, linenos=linenos, - **highlight_args) + hlcode = self.highlighter.highlight_block( + code, lang, opts=opts, linenos=linenos, + location=(self.curfilestack[-1], node.line), **highlight_args + ) # workaround for Unicode issue hlcode = hlcode.replace(u'€', u'@texteuro[]') if self.in_footnote: @@ -1987,17 +2171,21 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def depart_literal_block(self, node): + # type: (nodes.Node) -> None self.body.append('\n\\end{alltt}\n') visit_doctest_block = visit_literal_block depart_doctest_block = depart_literal_block def visit_line(self, node): + # type: (nodes.Node) -> None self.body.append('\item[] ') def depart_line(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_line_block(self, node): + # type: (nodes.Node) -> None if isinstance(node.parent, nodes.line_block): self.body.append('\\item[]\n' '\\begin{DUlineblock}{\\DUlineblockindent}\n') @@ -2007,9 +2195,11 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.has_problematic = True def depart_line_block(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{DUlineblock}\n') def visit_block_quote(self, node): + # type: (nodes.Node) -> None # If the block quote contains a single object and that object # is a list, then generate a list not a block quote. # This lets us indent lists. @@ -2025,6 +2215,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.has_problematic = True def depart_block_quote(self, node): + # type: (nodes.Node) -> None done = 0 if len(node.children) == 1: child = node.children[0] @@ -2037,45 +2228,56 @@ class LaTeXTranslator(nodes.NodeVisitor): # option node handling copied from docutils' latex writer def visit_option(self, node): + # type: (nodes.Node) -> None if self.context[-1]: # this is not the first option self.body.append(', ') def depart_option(self, node): + # type: (nodes.Node) -> None # flag that the first option is done. self.context[-1] += 1 def visit_option_argument(self, node): + # type: (nodes.Node) -> None """The delimiter betweeen an option and its argument.""" self.body.append(node.get('delimiter', ' ')) def depart_option_argument(self, node): + # type: (nodes.Node) -> None pass def visit_option_group(self, node): + # type: (nodes.Node) -> None self.body.append('\\item [') # flag for first option self.context.append(0) def depart_option_group(self, node): + # type: (nodes.Node) -> None self.context.pop() # the flag self.body.append('] ') def visit_option_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\begin{optionlist}{3cm}\n') if self.table: self.table.has_problematic = True def depart_option_list(self, node): + # type: (nodes.Node) -> None self.body.append('\\end{optionlist}\n') def visit_option_list_item(self, node): + # type: (nodes.Node) -> None pass def depart_option_list_item(self, node): + # type: (nodes.Node) -> None pass def visit_option_string(self, node): + # type: (nodes.Node) -> None ostring = node.astext() self.no_contractions += 1 self.body.append(self.encode(ostring)) @@ -2083,30 +2285,39 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_description(self, node): + # type: (nodes.Node) -> None self.body.append(' ') def depart_description(self, node): + # type: (nodes.Node) -> None pass def visit_superscript(self, node): + # type: (nodes.Node) -> None self.body.append('$^{\\text{') def depart_superscript(self, node): + # type: (nodes.Node) -> None self.body.append('}}$') def visit_subscript(self, node): + # type: (nodes.Node) -> None self.body.append('$_{\\text{') def depart_subscript(self, node): + # type: (nodes.Node) -> None self.body.append('}}$') def visit_substitution_definition(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_substitution_reference(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_inline(self, node): + # type: (nodes.Node) -> None classes = node.get('classes', []) if classes in [['menuselection'], ['guilabel']]: self.body.append(r'\sphinxmenuselection{') @@ -2121,24 +2332,30 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append('') def depart_inline(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) def visit_generated(self, node): + # type: (nodes.Node) -> None pass def depart_generated(self, node): + # type: (nodes.Node) -> None pass def visit_compound(self, node): + # type: (nodes.Node) -> None pass def depart_compound(self, node): + # type: (nodes.Node) -> None pass def visit_container(self, node): + # type: (nodes.Node) -> None if node.get('literal_block'): self.in_container_literal_block += 1 - ids = '' + ids = '' # type: unicode for id in self.pop_hyperlink_ids('code-block'): ids += self.hypertarget(id, anchor=False) if node['ids']: @@ -2149,31 +2366,38 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\n\\def\\sphinxLiteralBlockLabel{' + ids + '}\n') def depart_container(self, node): + # type: (nodes.Node) -> None if node.get('literal_block'): self.in_container_literal_block -= 1 self.body.append('\\let\\sphinxVerbatimTitle\\empty\n') self.body.append('\\let\\sphinxLiteralBlockLabel\\empty\n') def visit_decoration(self, node): + # type: (nodes.Node) -> None pass def depart_decoration(self, node): + # type: (nodes.Node) -> None pass # docutils-generated elements that we don't support def visit_header(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_footer(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_docinfo(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode # text handling def encode(self, text): + # type: (unicode) -> unicode text = text_type(text).translate(tex_escape_map) if self.literal_whitespace: # Insert a blank before the newline, to avoid @@ -2185,39 +2409,48 @@ class LaTeXTranslator(nodes.NodeVisitor): return text def encode_uri(self, text): + # type: (unicode) -> unicode # in \href, the tilde is allowed and must be represented literally return self.encode(text).replace('\\textasciitilde{}', '~') def visit_Text(self, node): + # type: (nodes.Node) -> None text = self.encode(node.astext()) if not self.no_contractions: text = educate_quotes_latex(text) self.body.append(text) def depart_Text(self, node): + # type: (nodes.Node) -> None pass def visit_comment(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_meta(self, node): + # type: (nodes.Node) -> None # only valid for HTML raise nodes.SkipNode def visit_system_message(self, node): + # type: (nodes.Node) -> None pass def depart_system_message(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_math(self, node): - self.builder.warn('using "math" markup without a Sphinx math extension ' - 'active, please use one of the math extensions ' - 'described at http://sphinx-doc.org/ext/math.html', - (self.curfilestack[-1], node.line)) + # type: (nodes.Node) -> None + logger.warning('using "math" markup without a Sphinx math extension ' + 'active, please use one of the math extensions ' + 'described at http://sphinx-doc.org/ext/math.html', + location=(self.curfilestack[-1], node.line)) raise nodes.SkipNode visit_math_block = visit_math def unknown_visit(self, node): + # type: (nodes.Node) -> None raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 53cf29767..76b402462 100644 --- a/sphinx/writers/manpage.py +++ b/sphinx/writers/manpage.py @@ -9,8 +9,6 @@ :license: BSD, see LICENSE for details. """ -import warnings - from docutils import nodes from docutils.writers.manpage import ( MACRO_DEF, @@ -19,11 +17,13 @@ from docutils.writers.manpage import ( ) from sphinx import addnodes -from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.locale import admonitionlabels, _ -from sphinx.util.compat import docutils_version +from sphinx.util import logging +import sphinx.util.docutils from sphinx.util.i18n import format_date +logger = logging.getLogger(__name__) + class ManualPageWriter(Writer): def __init__(self, builder): @@ -105,7 +105,7 @@ class ManualPageTranslator(BaseTranslator): self._docinfo['manual_group'] = builder.config.project # In docutils < 0.11 self.append_header() was never called - if docutils_version < (0, 11): + if sphinx.util.docutils.__version_info__ < (0, 11): self.body.append(MACRO_DEF) # Overwrite admonition label translations with our own @@ -216,14 +216,6 @@ class ManualPageTranslator(BaseTranslator): else: BaseTranslator.visit_term(self, node) - def visit_termsep(self, node): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6. ' - 'This warning is displayed because some Sphinx extension ' - 'uses sphinx.addnodes.termsep. Please report it to ' - 'author of the extension.', RemovedInSphinx16Warning) - self.body.append(', ') - raise nodes.SkipNode - # overwritten -- we don't want source comments to show up def visit_comment(self, node): raise nodes.SkipNode @@ -437,9 +429,9 @@ class ManualPageTranslator(BaseTranslator): pass def visit_math(self, node): - self.builder.warn('using "math" markup without a Sphinx math extension ' - 'active, please use one of the math extensions ' - 'described at http://sphinx-doc.org/ext/math.html') + logger.warning('using "math" markup without a Sphinx math extension ' + 'active, please use one of the math extensions ' + 'described at http://sphinx-doc.org/ext/math.html') raise nodes.SkipNode visit_math_block = visit_math diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index 18dcd9177..a992869e3 100644 --- a/sphinx/writers/texinfo.py +++ b/sphinx/writers/texinfo.py @@ -12,18 +12,26 @@ import re import textwrap from os import path -import warnings from six import itervalues from six.moves import range + from docutils import nodes, writers from sphinx import addnodes, __display_version__ -from sphinx.deprecation import RemovedInSphinx16Warning +from sphinx.errors import ExtensionError from sphinx.locale import admonitionlabels, _ +from sphinx.util import logging from sphinx.util.i18n import format_date from sphinx.writers.latex import collected_footnote +if False: + # For type annotation + from typing import Any, Callable, Iterator, Pattern, Tuple, Union # NOQA + from sphinx.builders.texinfo import TexinfoBuilder # NOQA + +logger = logging.getLogger(__name__) + COPYING = """\ @quotation @@ -81,6 +89,7 @@ TEMPLATE = """\ def find_subsections(section): + # type: (nodes.Node) -> List[nodes.Node] """Return a list of subsections for the given ``section``.""" result = [] for child in section.children: @@ -92,6 +101,7 @@ def find_subsections(section): def smart_capwords(s, sep=None): + # type: (unicode, unicode) -> unicode """Like string.capwords() but does not capitalize words that already contain a capital letter.""" words = s.split(sep) @@ -111,21 +121,23 @@ class TexinfoWriter(writers.Writer): ('Dir entry', ['--texinfo-dir-entry'], {'default': ''}), ('Description', ['--texinfo-dir-description'], {'default': ''}), ('Category', ['--texinfo-dir-category'], {'default': - 'Miscellaneous'}))) + 'Miscellaneous'}))) # type: Tuple[unicode, Any, Tuple[Tuple[unicode, List[unicode], Dict[unicode, unicode]], ...]] # NOQA - settings_defaults = {} + settings_defaults = {} # type: Dict - output = None + output = None # type: unicode visitor_attributes = ('output', 'fragment') def __init__(self, builder): + # type: (TexinfoBuilder) -> None writers.Writer.__init__(self) self.builder = builder self.translator_class = ( self.builder.translator_class or TexinfoTranslator) def translate(self): + # type: () -> None self.visitor = visitor = self.translator_class( self.document, self.builder) self.document.walkabout(visitor) @@ -154,44 +166,53 @@ class TexinfoTranslator(nodes.NodeVisitor): } def __init__(self, document, builder): + # type: (nodes.Node, TexinfoBuilder) -> None nodes.NodeVisitor.__init__(self, document) self.builder = builder self.init_settings() - self.written_ids = set() # node names and anchors in output + self.written_ids = set() # type: Set[unicode] + # node names and anchors in output # node names and anchors that should be in output - self.referenced_ids = set() - self.indices = [] # (node name, content) - self.short_ids = {} # anchors --> short ids - self.node_names = {} # node name --> node's name to display - self.node_menus = {} # node name --> node's menu entries - self.rellinks = {} # node name --> (next, previous, up) + self.referenced_ids = set() # type: Set[unicode] + self.indices = [] # type: List[Tuple[unicode, unicode]] + # (node name, content) + self.short_ids = {} # type: Dict[unicode, unicode] + # anchors --> short ids + self.node_names = {} # type: Dict[unicode, unicode] + # node name --> node's name to display + self.node_menus = {} # type: Dict[unicode, List[unicode]] + # node name --> node's menu entries + self.rellinks = {} # type: Dict[unicode, List[unicode]] + # node name --> (next, previous, up) self.collect_indices() self.collect_node_names() self.collect_node_menus() self.collect_rellinks() - self.body = [] - self.context = [] - self.previous_section = None + self.body = [] # type: List[unicode] + self.context = [] # type: List[unicode] + self.previous_section = None # type: nodes.section self.section_level = 0 self.seen_title = False - self.next_section_ids = set() + self.next_section_ids = set() # type: Set[unicode] self.escape_newlines = 0 self.escape_hyphens = 0 - self.curfilestack = [] - self.footnotestack = [] + self.curfilestack = [] # type: List[unicode] + self.footnotestack = [] # type: List[Dict[unicode, List[Union[collected_footnote, bool]]]] # NOQA self.in_footnote = 0 - self.handled_abbrs = set() + self.handled_abbrs = set() # type: Set[unicode] + self.colwidths = None # type: List[int] def finish(self): + # type: () -> None if self.previous_section is None: self.add_menu('Top') for index in self.indices: name, content = index pointers = tuple([name] + self.rellinks[name]) - self.body.append('\n@node %s,%s,%s,%s\n' % pointers) + self.body.append('\n@node %s,%s,%s,%s\n' % pointers) # type: ignore self.body.append('@unnumbered %s\n\n%s\n' % (name, content)) while self.referenced_ids: @@ -207,6 +228,7 @@ class TexinfoTranslator(nodes.NodeVisitor): # -- Helper routines def init_settings(self): + # type: () -> None settings = self.settings = self.document.settings elements = self.elements = self.default_elements.copy() elements.update({ @@ -223,17 +245,18 @@ class TexinfoTranslator(nodes.NodeVisitor): language=self.builder.config.language)) }) # title - title = elements['title'] + title = None # type: unicode + title = elements['title'] # type: ignore if not title: - title = self.document.next_node(nodes.title) - title = (title and title.astext()) or '<untitled>' + title = self.document.next_node(nodes.title) # type: ignore + title = (title and title.astext()) or '<untitled>' # type: ignore elements['title'] = self.escape_id(title) or '<untitled>' # filename if not elements['filename']: elements['filename'] = self.document.get('source') or 'untitled' - if elements['filename'][-4:] in ('.txt', '.rst'): - elements['filename'] = elements['filename'][:-4] - elements['filename'] += '.info' + if elements['filename'][-4:] in ('.txt', '.rst'): # type: ignore + elements['filename'] = elements['filename'][:-4] # type: ignore + elements['filename'] += '.info' # type: ignore # direntry if settings.texinfo_dir_entry: entry = self.format_menu_entry( @@ -250,11 +273,13 @@ class TexinfoTranslator(nodes.NodeVisitor): elements.update(settings.texinfo_elements) def collect_node_names(self): + # type: () -> None """Generates a unique id for each section. Assigns the attribute ``node_name`` to each section.""" def add_node_name(name): + # type: (unicode) -> unicode node_id = self.escape_id(name) nth, suffix = 1, '' while node_id + suffix in self.written_ids or \ @@ -280,6 +305,7 @@ class TexinfoTranslator(nodes.NodeVisitor): section['node_name'] = add_node_name(name) def collect_node_menus(self): + # type: () -> None """Collect the menu entries for each "node" section.""" node_menus = self.node_menus for node in ([self.document] + @@ -300,10 +326,11 @@ class TexinfoTranslator(nodes.NodeVisitor): top['node_name'] = 'Top' # handle the indices for name, content in self.indices: - node_menus[name] = () + node_menus[name] = [] node_menus['Top'].append(name) def collect_rellinks(self): + # type: () -> None """Collect the relative links (next, previous, up) for each "node".""" rellinks = self.rellinks node_menus = self.node_menus @@ -337,6 +364,7 @@ class TexinfoTranslator(nodes.NodeVisitor): # characters. def escape(self, s): + # type: (unicode) -> unicode """Return a string with Texinfo command characters escaped.""" s = s.replace('@', '@@') s = s.replace('{', '@{') @@ -347,6 +375,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return s def escape_arg(self, s): + # type: (unicode) -> unicode """Return an escaped string suitable for use as an argument to a Texinfo command.""" s = self.escape(s) @@ -357,6 +386,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return s def escape_id(self, s): + # type: (unicode) -> unicode """Return an escaped string suitable for node names and anchors.""" bad_chars = ',:.()' for bc in bad_chars: @@ -365,6 +395,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return self.escape(s) def escape_menu(self, s): + # type: (unicode) -> unicode """Return an escaped string suitable for menu entries.""" s = self.escape_arg(s) s = s.replace(':', ';') @@ -372,11 +403,13 @@ class TexinfoTranslator(nodes.NodeVisitor): return s def ensure_eol(self): + # type: () -> None """Ensure the last line in body is terminated by new line.""" if self.body and self.body[-1][-1:] != '\n': self.body.append('\n') def format_menu_entry(self, name, node_name, desc): + # type: (unicode, unicode, unicode) -> unicode if name == node_name: s = '* %s:: ' % (name,) else: @@ -387,6 +420,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return s + wdesc.strip() + '\n' def add_menu_entries(self, entries, reg=re.compile(r'\s+---?\s+')): + # type: (List[unicode], Pattern) -> None for entry in entries: name = self.node_names[entry] # special formatting for entries that are divided by an em-dash @@ -404,6 +438,7 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append(self.format_menu_entry(name, entry, desc)) def add_menu(self, node_name): + # type: (unicode) -> None entries = self.node_menus[node_name] if not entries: return @@ -416,6 +451,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return def _add_detailed_menu(name): + # type: (unicode) -> None entries = self.node_menus[name] if not entries: return @@ -432,6 +468,7 @@ class TexinfoTranslator(nodes.NodeVisitor): '@end menu\n') def tex_image_length(self, width_str): + # type: (unicode) -> unicode match = re.match('(\d*\.?\d*)\s*(\S*)', width_str) if not match: # fallback @@ -447,15 +484,17 @@ class TexinfoTranslator(nodes.NodeVisitor): return res def collect_indices(self): + # type: () -> None def generate(content, collapsed): - ret = ['\n@menu\n'] + # type: (List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool) -> unicode + ret = ['\n@menu\n'] # type: List[unicode] for letter, entries in content: for entry in entries: if not entry[3]: continue - name = self.escape_menu(entry[0]) + name = self.escape_menu(entry[0]) # type: ignore sid = self.get_short_id('%s:%s' % (entry[2], entry[3])) - desc = self.escape_arg(entry[6]) + desc = self.escape_arg(entry[6]) # type: ignore me = self.format_menu_entry(name, sid, desc) ret.append(me) ret.append('@end menu\n') @@ -485,7 +524,9 @@ class TexinfoTranslator(nodes.NodeVisitor): # TODO: move this to sphinx.util def collect_footnotes(self, node): + # type: (nodes.Node) -> Dict[unicode, List[Union[collected_footnote, bool]]] def footnotes_under(n): + # type: (nodes.Node) -> Iterator[nodes.footnote] if isinstance(n, nodes.footnote): yield n else: @@ -494,7 +535,7 @@ class TexinfoTranslator(nodes.NodeVisitor): continue for k in footnotes_under(c): yield k - fnotes = {} + fnotes = {} # type: Dict[unicode, List[Union[collected_footnote, bool]]] for fn in footnotes_under(node): num = fn.children[0].astext().strip() fnotes[num] = [collected_footnote(*fn.children), False] @@ -503,6 +544,7 @@ class TexinfoTranslator(nodes.NodeVisitor): # -- xref handling def get_short_id(self, id): + # type: (unicode) -> unicode """Return a shorter 'id' associated with ``id``.""" # Shorter ids improve paragraph filling in places # that the id is hidden by Emacs. @@ -514,6 +556,7 @@ class TexinfoTranslator(nodes.NodeVisitor): return sid def add_anchor(self, id, node): + # type: (unicode, nodes.Node) -> None if id.startswith('index-'): return id = self.curfilestack[-1] + ':' + id @@ -525,6 +568,7 @@ class TexinfoTranslator(nodes.NodeVisitor): self.written_ids.add(id) def add_xref(self, id, name, node): + # type: (unicode, unicode, nodes.Node) -> None name = self.escape_menu(name) sid = self.get_short_id(id) self.body.append('@ref{%s,,%s}' % (sid, name)) @@ -534,16 +578,19 @@ class TexinfoTranslator(nodes.NodeVisitor): # -- Visiting def visit_document(self, node): + # type: (nodes.Node) -> None self.footnotestack.append(self.collect_footnotes(node)) self.curfilestack.append(node.get('docname', '')) if 'docname' in node: self.add_anchor(':doc', node) def depart_document(self, node): + # type: (nodes.Node) -> None self.footnotestack.pop() self.curfilestack.pop() def visit_Text(self, node): + # type: (nodes.Node) -> None s = self.escape(node.astext()) if self.escape_newlines: s = s.replace('\n', ' ') @@ -553,9 +600,11 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append(s) def depart_Text(self, node): + # type: (nodes.Node) -> None pass def visit_section(self, node): + # type: (nodes.section) -> None self.next_section_ids.update(node.get('ids', [])) if not self.seen_title: return @@ -566,7 +615,7 @@ class TexinfoTranslator(nodes.NodeVisitor): node_name = node['node_name'] pointers = tuple([node_name] + self.rellinks[node_name]) - self.body.append('\n@node %s,%s,%s,%s\n' % pointers) + self.body.append('\n@node %s,%s,%s,%s\n' % pointers) # type: ignore for id in self.next_section_ids: self.add_anchor(id, node) @@ -575,6 +624,7 @@ class TexinfoTranslator(nodes.NodeVisitor): self.section_level += 1 def depart_section(self, node): + # type: (nodes.Node) -> None self.section_level -= 1 headings = ( @@ -583,17 +633,18 @@ class TexinfoTranslator(nodes.NodeVisitor): '@section', '@subsection', '@subsubsection', - ) + ) # type: Tuple[unicode, ...] rubrics = ( '@heading', '@subheading', '@subsubheading', - ) + ) # type: Tuple[unicode, ...] def visit_title(self, node): + # type: (nodes.Node) -> None if not self.seen_title: - self.seen_title = 1 + self.seen_title = True raise nodes.SkipNode parent = node.parent if isinstance(parent, nodes.table): @@ -601,9 +652,9 @@ class TexinfoTranslator(nodes.NodeVisitor): if isinstance(parent, (nodes.Admonition, nodes.sidebar, nodes.topic)): raise nodes.SkipNode elif not isinstance(parent, nodes.section): - self.builder.warn( - 'encountered title node not in section, topic, table, ' - 'admonition or sidebar', (self.curfilestack[-1], node.line)) + logger.warning('encountered title node not in section, topic, table, ' + 'admonition or sidebar', + location=(self.curfilestack[-1], node.line)) self.visit_rubric(node) else: try: @@ -613,9 +664,11 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('\n%s ' % heading) def depart_title(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n') def visit_rubric(self, node): + # type: (nodes.Node) -> None if len(node.children) == 1 and node.children[0].astext() in \ ('Footnotes', _('Footnotes')): raise nodes.SkipNode @@ -626,17 +679,21 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('\n%s ' % rubric) def depart_rubric(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n') def visit_subtitle(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n@noindent\n') def depart_subtitle(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n') # -- References def visit_target(self, node): + # type: (nodes.Node) -> None # postpone the labels until after the sectioning command parindex = node.parent.index(node) try: @@ -661,9 +718,11 @@ class TexinfoTranslator(nodes.NodeVisitor): self.add_anchor(id, node) def depart_target(self, node): + # type: (nodes.Node) -> None pass def visit_reference(self, node): + # type: (nodes.Node) -> None # an xref's target is displayed in Info so we ignore a few # cases for the sake of appearance if isinstance(node.parent, (nodes.title, addnodes.desc_type)): @@ -727,14 +786,17 @@ class TexinfoTranslator(nodes.NodeVisitor): raise nodes.SkipNode def depart_reference(self, node): + # type: (nodes.Node) -> None pass def visit_number_reference(self, node): + # type: (nodes.Node) -> None text = nodes.Text(node.get('title', '#')) self.visit_Text(text) raise nodes.SkipNode def visit_title_reference(self, node): + # type: (nodes.Node) -> None text = node.astext() self.body.append('@cite{%s}' % self.escape_arg(text)) raise nodes.SkipNode @@ -742,22 +804,28 @@ class TexinfoTranslator(nodes.NodeVisitor): # -- Blocks def visit_paragraph(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def depart_paragraph(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_block_quote(self, node): + # type: (nodes.Node) -> None self.body.append('\n@quotation\n') def depart_block_quote(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end quotation\n') def visit_literal_block(self, node): + # type: (nodes.Node) -> None self.body.append('\n@example\n') def depart_literal_block(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end example\n') @@ -765,101 +833,126 @@ class TexinfoTranslator(nodes.NodeVisitor): depart_doctest_block = depart_literal_block def visit_line_block(self, node): + # type: (nodes.Node) -> None if not isinstance(node.parent, nodes.line_block): self.body.append('\n\n') self.body.append('@display\n') def depart_line_block(self, node): + # type: (nodes.Node) -> None self.body.append('@end display\n') if not isinstance(node.parent, nodes.line_block): self.body.append('\n\n') def visit_line(self, node): + # type: (nodes.Node) -> None self.escape_newlines += 1 def depart_line(self, node): + # type: (nodes.Node) -> None self.body.append('@w{ }\n') self.escape_newlines -= 1 # -- Inline def visit_strong(self, node): + # type: (nodes.Node) -> None self.body.append('@strong{') def depart_strong(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('@emph{') def depart_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_literal(self, node): + # type: (nodes.Node) -> None self.body.append('@code{') def depart_literal(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_superscript(self, node): + # type: (nodes.Node) -> None self.body.append('@w{^') def depart_superscript(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_subscript(self, node): + # type: (nodes.Node) -> None self.body.append('@w{[') def depart_subscript(self, node): + # type: (nodes.Node) -> None self.body.append(']}') # -- Footnotes def visit_footnote(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_collected_footnote(self, node): + # type: (nodes.Node) -> None self.in_footnote += 1 self.body.append('@footnote{') def depart_collected_footnote(self, node): + # type: (nodes.Node) -> None self.body.append('}') self.in_footnote -= 1 def visit_footnote_reference(self, node): + # type: (nodes.Node) -> None num = node.astext().strip() try: footnode, used = self.footnotestack[-1][num] except (KeyError, IndexError): raise nodes.SkipNode # footnotes are repeated for each reference - footnode.walkabout(self) + footnode.walkabout(self) # type: ignore raise nodes.SkipChildren def visit_citation(self, node): + # type: (nodes.Node) -> None for id in node.get('ids'): self.add_anchor(id, node) def depart_citation(self, node): + # type: (nodes.Node) -> None pass def visit_citation_reference(self, node): + # type: (nodes.Node) -> None self.body.append('@w{[') def depart_citation_reference(self, node): + # type: (nodes.Node) -> None self.body.append(']}') # -- Lists def visit_bullet_list(self, node): + # type: (nodes.Node) -> None bullet = node.get('bullet', '*') self.body.append('\n\n@itemize %s\n' % bullet) def depart_bullet_list(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end itemize\n') def visit_enumerated_list(self, node): + # type: (nodes.Node) -> None # doesn't support Roman numerals enum = node.get('enumtype', 'arabic') starters = {'arabic': '', @@ -869,75 +962,96 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('\n\n@enumerate %s\n' % start) def depart_enumerated_list(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end enumerate\n') def visit_list_item(self, node): + # type: (nodes.Node) -> None self.body.append('\n@item ') def depart_list_item(self, node): + # type: (nodes.Node) -> None pass # -- Option List def visit_option_list(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n@table @option\n') def depart_option_list(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end table\n') def visit_option_list_item(self, node): + # type: (nodes.Node) -> None pass def depart_option_list_item(self, node): + # type: (nodes.Node) -> None pass def visit_option_group(self, node): + # type: (nodes.Node) -> None self.at_item_x = '@item' def depart_option_group(self, node): + # type: (nodes.Node) -> None pass def visit_option(self, node): + # type: (nodes.Node) -> None self.escape_hyphens += 1 self.body.append('\n%s ' % self.at_item_x) self.at_item_x = '@itemx' def depart_option(self, node): + # type: (nodes.Node) -> None self.escape_hyphens -= 1 def visit_option_string(self, node): + # type: (nodes.Node) -> None pass def depart_option_string(self, node): + # type: (nodes.Node) -> None pass def visit_option_argument(self, node): + # type: (nodes.Node) -> None self.body.append(node.get('delimiter', ' ')) def depart_option_argument(self, node): + # type: (nodes.Node) -> None pass def visit_description(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def depart_description(self, node): + # type: (nodes.Node) -> None pass # -- Definitions def visit_definition_list(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n@table @asis\n') def depart_definition_list(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end table\n') def visit_definition_list_item(self, node): + # type: (nodes.Node) -> None self.at_item_x = '@item' def depart_definition_list_item(self, node): + # type: (nodes.Node) -> None pass def visit_term(self, node): @@ -952,45 +1066,45 @@ class TexinfoTranslator(nodes.NodeVisitor): self.at_item_x = '@itemx' def depart_term(self, node): - pass - - def visit_termsep(self, node): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6. ' - 'This warning is displayed because some Sphinx extension ' - 'uses sphinx.addnodes.termsep. Please report it to ' - 'author of the extension.', RemovedInSphinx16Warning) - self.body.append('\n%s ' % self.at_item_x) - - def depart_termsep(self, node): + # type: (nodes.Node) -> None pass def visit_classifier(self, node): + # type: (nodes.Node) -> None self.body.append(' : ') def depart_classifier(self, node): + # type: (nodes.Node) -> None pass def visit_definition(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def depart_definition(self, node): + # type: (nodes.Node) -> None pass # -- Tables def visit_table(self, node): + # type: (nodes.Node) -> None self.entry_sep = '@item' def depart_table(self, node): + # type: (nodes.Node) -> None self.body.append('\n@end multitable\n\n') def visit_tabular_col_spec(self, node): + # type: (nodes.Node) -> None pass def depart_tabular_col_spec(self, node): + # type: (nodes.Node) -> None pass def visit_colspec(self, node): + # type: (nodes.Node) -> None self.colwidths.append(node['colwidth']) if len(self.colwidths) != self.n_cols: return @@ -999,82 +1113,104 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('{%s} ' % ('x' * (n+2))) def depart_colspec(self, node): + # type: (nodes.Node) -> None pass def visit_tgroup(self, node): + # type: (nodes.Node) -> None self.colwidths = [] self.n_cols = node['cols'] def depart_tgroup(self, node): + # type: (nodes.Node) -> None pass def visit_thead(self, node): + # type: (nodes.Node) -> None self.entry_sep = '@headitem' def depart_thead(self, node): + # type: (nodes.Node) -> None pass def visit_tbody(self, node): + # type: (nodes.Node) -> None pass def depart_tbody(self, node): + # type: (nodes.Node) -> None pass def visit_row(self, node): + # type: (nodes.Node) -> None pass def depart_row(self, node): + # type: (nodes.Node) -> None self.entry_sep = '@item' def visit_entry(self, node): + # type: (nodes.Node) -> None self.body.append('\n%s\n' % self.entry_sep) self.entry_sep = '@tab' def depart_entry(self, node): + # type: (nodes.Node) -> None for i in range(node.get('morecols', 0)): self.body.append('\n@tab\n') # -- Field Lists def visit_field_list(self, node): + # type: (nodes.Node) -> None pass def depart_field_list(self, node): + # type: (nodes.Node) -> None pass def visit_field(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def depart_field(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_field_name(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@*') def depart_field_name(self, node): + # type: (nodes.Node) -> None self.body.append(': ') def visit_field_body(self, node): + # type: (nodes.Node) -> None pass def depart_field_body(self, node): + # type: (nodes.Node) -> None pass # -- Admonitions def visit_admonition(self, node, name=''): + # type: (nodes.Node, unicode) -> None if not name: name = self.escape(node[0].astext()) self.body.append(u'\n@cartouche\n@quotation %s ' % name) def depart_admonition(self, node): + # type: (nodes.Node) -> None self.ensure_eol() self.body.append('@end quotation\n' '@end cartouche\n') def _make_visit_admonition(name): def visit(self, node): + # type: (nodes.Node) -> None self.visit_admonition(node, admonitionlabels[name]) return visit @@ -1100,32 +1236,41 @@ class TexinfoTranslator(nodes.NodeVisitor): # -- Misc def visit_docinfo(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_generated(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_header(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_footer(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_container(self, node): + # type: (nodes.Node) -> None if node.get('literal_block'): self.body.append('\n\n@float LiteralBlock\n') def depart_container(self, node): + # type: (nodes.Node) -> None if node.get('literal_block'): self.body.append('\n@end float\n\n') def visit_decoration(self, node): + # type: (nodes.Node) -> None pass def depart_decoration(self, node): + # type: (nodes.Node) -> None pass def visit_topic(self, node): + # type: (nodes.Node) -> None # ignore TOC's since we have to have a "menu" anyway if 'contents' in node.get('classes', []): raise nodes.SkipNode @@ -1134,48 +1279,59 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('%s\n' % self.escape(title.astext())) def depart_topic(self, node): + # type: (nodes.Node) -> None pass def visit_transition(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n%s\n\n' % ('_' * 66)) def depart_transition(self, node): + # type: (nodes.Node) -> None pass def visit_attribution(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n@center --- ') def depart_attribution(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n') def visit_raw(self, node): + # type: (nodes.Node) -> None format = node.get('format', '').split() if 'texinfo' in format or 'texi' in format: self.body.append(node.astext()) raise nodes.SkipNode def visit_figure(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n@float Figure\n') def depart_figure(self, node): + # type: (nodes.Node) -> None self.body.append('\n@end float\n\n') def visit_caption(self, node): + # type: (nodes.Node) -> None if (isinstance(node.parent, nodes.figure) or (isinstance(node.parent, nodes.container) and node.parent.get('literal_block'))): self.body.append('\n@caption{') else: - self.builder.warn('caption not inside a figure.', - (self.curfilestack[-1], node.line)) + logger.warning('caption not inside a figure.', + location=(self.curfilestack[-1], node.line)) def depart_caption(self, node): + # type: (nodes.Node) -> None if (isinstance(node.parent, nodes.figure) or (isinstance(node.parent, nodes.container) and node.parent.get('literal_block'))): self.body.append('}\n') def visit_image(self, node): + # type: (nodes.Node) -> None if node['uri'] in self.builder.images: uri = self.builder.images[node['uri']] else: @@ -1196,73 +1352,93 @@ class TexinfoTranslator(nodes.NodeVisitor): (name, width, height, alt, ext[1:])) def depart_image(self, node): + # type: (nodes.Node) -> None pass def visit_compound(self, node): + # type: (nodes.Node) -> None pass def depart_compound(self, node): + # type: (nodes.Node) -> None pass def visit_sidebar(self, node): + # type: (nodes.Node) -> None self.visit_topic(node) def depart_sidebar(self, node): + # type: (nodes.Node) -> None self.depart_topic(node) def visit_label(self, node): + # type: (nodes.Node) -> None self.body.append('@w{(') def depart_label(self, node): + # type: (nodes.Node) -> None self.body.append(')} ') def visit_legend(self, node): + # type: (nodes.Node) -> None pass def depart_legend(self, node): + # type: (nodes.Node) -> None pass def visit_substitution_reference(self, node): + # type: (nodes.Node) -> None pass def depart_substitution_reference(self, node): + # type: (nodes.Node) -> None pass def visit_substitution_definition(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_system_message(self, node): + # type: (nodes.Node) -> None self.body.append('\n@verbatim\n' '<SYSTEM MESSAGE: %s>\n' '@end verbatim\n' % node.astext()) raise nodes.SkipNode def visit_comment(self, node): + # type: (nodes.Node) -> None self.body.append('\n') for line in node.astext().splitlines(): self.body.append('@c %s\n' % line) raise nodes.SkipNode def visit_problematic(self, node): + # type: (nodes.Node) -> None self.body.append('>>') def depart_problematic(self, node): + # type: (nodes.Node) -> None self.body.append('<<') def unimplemented_visit(self, node): - self.builder.warn("unimplemented node type: %r" % node, - (self.curfilestack[-1], node.line)) + # type: (nodes.Node) -> None + logger.warning("unimplemented node type: %r", node, + location=(self.curfilestack[-1], node.line)) def unknown_visit(self, node): - self.builder.warn("unknown node type: %r" % node, - (self.curfilestack[-1], node.line)) + # type: (nodes.Node) -> None + logger.warning("unknown node type: %r", node, + location=(self.curfilestack[-1], node.line)) def unknown_departure(self, node): + # type: (nodes.Node) -> None pass # -- Sphinx specific def visit_productionlist(self, node): + # type: (nodes.Node) -> None self.visit_literal_block(None) names = [] for production in node: @@ -1281,24 +1457,31 @@ class TexinfoTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_production(self, node): + # type: (nodes.Node) -> None pass def depart_production(self, node): + # type: (nodes.Node) -> None pass def visit_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('@code{') def depart_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_literal_strong(self, node): + # type: (nodes.Node) -> None self.body.append('@code{') def depart_literal_strong(self, node): + # type: (nodes.Node) -> None self.body.append('}') def visit_index(self, node): + # type: (nodes.Node) -> None # terminate the line but don't prevent paragraph breaks if isinstance(node.parent, nodes.paragraph): self.ensure_eol() @@ -1310,43 +1493,54 @@ class TexinfoTranslator(nodes.NodeVisitor): self.body.append('@geindex %s\n' % text) def visit_versionmodified(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def depart_versionmodified(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_start_of_file(self, node): + # type: (nodes.Node) -> None # add a document target self.next_section_ids.add(':doc') self.curfilestack.append(node['docname']) self.footnotestack.append(self.collect_footnotes(node)) def depart_start_of_file(self, node): + # type: (nodes.Node) -> None self.curfilestack.pop() self.footnotestack.pop() def visit_centered(self, node): + # type: (nodes.Node) -> None txt = self.escape_arg(node.astext()) self.body.append('\n\n@center %s\n\n' % txt) raise nodes.SkipNode def visit_seealso(self, node): + # type: (nodes.Node) -> None self.body.append(u'\n\n@subsubheading %s\n\n' % admonitionlabels['seealso']) def depart_seealso(self, node): + # type: (nodes.Node) -> None self.body.append('\n') def visit_meta(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_glossary(self, node): + # type: (nodes.Node) -> None pass def depart_glossary(self, node): + # type: (nodes.Node) -> None pass def visit_acks(self, node): + # type: (nodes.Node) -> None self.body.append('\n\n') self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') @@ -1354,23 +1548,28 @@ class TexinfoTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_highlightlang(self, node): + # type: (nodes.Node) -> None pass def depart_highlightlang(self, node): + # type: (nodes.Node) -> None pass # -- Desc def visit_desc(self, node): + # type: (nodes.Node) -> None self.desc = node self.at_deffnx = '@deffn' def depart_desc(self, node): + # type: (nodes.Node) -> None self.desc = None self.ensure_eol() self.body.append('@end deffn\n') def visit_desc_signature(self, node): + # type: (nodes.Node) -> None self.escape_hyphens += 1 objtype = node.parent['objtype'] if objtype != 'describe': @@ -1378,11 +1577,11 @@ class TexinfoTranslator(nodes.NodeVisitor): self.add_anchor(id, node) # use the full name of the objtype for the category try: - domain = self.builder.env.domains[node.parent['domain']] + domain = self.builder.env.get_domain(node.parent['domain']) primary = self.builder.config.primary_domain name = domain.get_type_name(domain.object_types[objtype], primary == domain.name) - except KeyError: + except (KeyError, ExtensionError): name = objtype # by convention, the deffn category should be capitalized like a title category = self.escape_arg(smart_capwords(name)) @@ -1391,42 +1590,54 @@ class TexinfoTranslator(nodes.NodeVisitor): self.desc_type_name = name def depart_desc_signature(self, node): + # type: (nodes.Node) -> None self.body.append("\n") self.escape_hyphens -= 1 self.desc_type_name = None def visit_desc_name(self, node): + # type: (nodes.Node) -> None pass def depart_desc_name(self, node): + # type: (nodes.Node) -> None pass def visit_desc_addname(self, node): + # type: (nodes.Node) -> None pass def depart_desc_addname(self, node): + # type: (nodes.Node) -> None pass def visit_desc_type(self, node): + # type: (nodes.Node) -> None pass def depart_desc_type(self, node): + # type: (nodes.Node) -> None pass def visit_desc_returns(self, node): + # type: (nodes.Node) -> None self.body.append(' -> ') def depart_desc_returns(self, node): + # type: (nodes.Node) -> None pass def visit_desc_parameterlist(self, node): + # type: (nodes.Node) -> None self.body.append(' (') self.first_param = 1 def depart_desc_parameterlist(self, node): + # type: (nodes.Node) -> None self.body.append(')') def visit_desc_parameter(self, node): + # type: (nodes.Node) -> None if not self.first_param: self.body.append(', ') else: @@ -1438,12 +1649,15 @@ class TexinfoTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_desc_optional(self, node): + # type: (nodes.Node) -> None self.body.append('[') def depart_desc_optional(self, node): + # type: (nodes.Node) -> None self.body.append(']') def visit_desc_annotation(self, node): + # type: (nodes.Node) -> None # Try to avoid duplicating info already displayed by the deffn category. # e.g. # @deffn {Class} Foo @@ -1456,21 +1670,27 @@ class TexinfoTranslator(nodes.NodeVisitor): raise nodes.SkipNode def depart_desc_annotation(self, node): + # type: (nodes.Node) -> None pass def visit_desc_content(self, node): + # type: (nodes.Node) -> None pass def depart_desc_content(self, node): + # type: (nodes.Node) -> None pass def visit_inline(self, node): + # type: (nodes.Node) -> None pass def depart_inline(self, node): + # type: (nodes.Node) -> None pass def visit_abbreviation(self, node): + # type: (nodes.Node) -> None abbr = node.astext() self.body.append('@abbr{') if node.hasattr('explanation') and abbr not in self.handled_abbrs: @@ -1480,42 +1700,54 @@ class TexinfoTranslator(nodes.NodeVisitor): self.context.append('}') def depart_abbreviation(self, node): + # type: (nodes.Node) -> None self.body.append(self.context.pop()) def visit_manpage(self, node): + # type: (nodes.Node) -> Any return self.visit_literal_emphasis(node) def depart_manpage(self, node): + # type: (nodes.Node) -> Any return self.depart_literal_emphasis(node) def visit_download_reference(self, node): + # type: (nodes.Node) -> None pass def depart_download_reference(self, node): + # type: (nodes.Node) -> None pass def visit_hlist(self, node): + # type: (nodes.Node) -> None self.visit_bullet_list(node) def depart_hlist(self, node): + # type: (nodes.Node) -> None self.depart_bullet_list(node) def visit_hlistcol(self, node): + # type: (nodes.Node) -> None pass def depart_hlistcol(self, node): + # type: (nodes.Node) -> None pass def visit_pending_xref(self, node): + # type: (nodes.Node) -> None pass def depart_pending_xref(self, node): + # type: (nodes.Node) -> None pass def visit_math(self, node): - self.builder.warn('using "math" markup without a Sphinx math extension ' - 'active, please use one of the math extensions ' - 'described at http://sphinx-doc.org/ext/math.html') + # type: (nodes.Node) -> None + logger.warning('using "math" markup without a Sphinx math extension ' + 'active, please use one of the math extensions ' + 'described at http://sphinx-doc.org/ext/math.html') raise nodes.SkipNode visit_math_block = visit_math diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index fc9e3378c..9bd427468 100644 --- a/sphinx/writers/text.py +++ b/sphinx/writers/text.py @@ -12,7 +12,6 @@ import os import re import textwrap from itertools import groupby -import warnings from six.moves import zip_longest @@ -20,8 +19,15 @@ from docutils import nodes, writers from docutils.utils import column_width from sphinx import addnodes -from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.locale import admonitionlabels, _ +from sphinx.util import logging + +if False: + # For type annotation + from typing import Any, Callable, Tuple, Union # NOQA + from sphinx.builders.text import TextBuilder # NOQA + +logger = logging.getLogger(__name__) class TextWrapper(textwrap.TextWrapper): @@ -34,13 +40,14 @@ class TextWrapper(textwrap.TextWrapper): r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash def _wrap_chunks(self, chunks): + # type: (List[unicode]) -> List[unicode] """_wrap_chunks(chunks : [string]) -> [string] The original _wrap_chunks uses len() to calculate width. This method respects wide/fullwidth characters for width adjustment. """ drop_whitespace = getattr(self, 'drop_whitespace', True) # py25 compat - lines = [] + lines = [] # type: List[unicode] if self.width <= 0: raise ValueError("invalid width %r (must be > 0)" % self.width) @@ -82,6 +89,7 @@ class TextWrapper(textwrap.TextWrapper): return lines def _break_word(self, word, space_left): + # type: (unicode, int) -> Tuple[unicode, unicode] """_break_word(word : string, space_left : int) -> (string, string) Break line by unicode width instead of len(word). @@ -94,14 +102,16 @@ class TextWrapper(textwrap.TextWrapper): return word, '' def _split(self, text): + # type: (unicode) -> List[unicode] """_split(text : string) -> [string] Override original method that only split by 'wordsep_re'. This '_split' split wide-characters into chunk by one character. """ def split(t): - return textwrap.TextWrapper._split(self, t) - chunks = [] + # type: (unicode) -> List[unicode] + return textwrap.TextWrapper._split(self, t) # type: ignore + chunks = [] # type: List[unicode] for chunk in split(text): for w, g in groupby(chunk, column_width): if w == 1: @@ -111,6 +121,7 @@ class TextWrapper(textwrap.TextWrapper): return chunks def _handle_long_word(self, reversed_chunks, cur_line, cur_len, width): + # type: (List[unicode], List[unicode], int, int) -> None """_handle_long_word(chunks : [string], cur_line : [string], cur_len : int, width : int) @@ -132,6 +143,7 @@ STDINDENT = 3 def my_wrap(text, width=MAXWIDTH, **kwargs): + # type: (unicode, int, Any) -> List[unicode] w = TextWrapper(width=width, **kwargs) return w.wrap(text) @@ -139,16 +151,18 @@ def my_wrap(text, width=MAXWIDTH, **kwargs): class TextWriter(writers.Writer): supported = ('text',) settings_spec = ('No options here.', '', ()) - settings_defaults = {} + settings_defaults = {} # type: Dict output = None def __init__(self, builder): + # type: (TextBuilder) -> None writers.Writer.__init__(self) self.builder = builder self.translator_class = self.builder.translator_class or TextTranslator def translate(self): + # type: () -> None visitor = self.translator_class(self.document, self.builder) self.document.walkabout(visitor) self.output = visitor.body @@ -158,6 +172,7 @@ class TextTranslator(nodes.NodeVisitor): sectionchars = '*=-~"+`' def __init__(self, document, builder): + # type: (nodes.Node, TextBuilder) -> None nodes.NodeVisitor.__init__(self, document) self.builder = builder @@ -169,28 +184,32 @@ class TextTranslator(nodes.NodeVisitor): else: self.nl = '\n' self.sectionchars = builder.config.text_sectionchars - self.states = [[]] + self.states = [[]] # type: List[List[Tuple[int, Union[unicode, List[unicode]]]]] self.stateindent = [0] - self.list_counter = [] + self.list_counter = [] # type: List[int] self.sectionlevel = 0 self.lineblocklevel = 0 - self.table = None + self.table = None # type: List[Union[unicode, List[int]]] def add_text(self, text): + # type: (unicode) -> None self.states[-1].append((-1, text)) def new_state(self, indent=STDINDENT): + # type: (int) -> None self.states.append([]) self.stateindent.append(indent) def end_state(self, wrap=True, end=[''], first=None): + # type: (bool, List[unicode], unicode) -> None content = self.states.pop() maxindent = sum(self.stateindent) indent = self.stateindent.pop() - result = [] - toformat = [] + result = [] # type: List[Tuple[int, List[unicode]]] + toformat = [] # type: List[unicode] def do_format(): + # type: () -> None if not toformat: return if wrap: @@ -202,10 +221,10 @@ class TextTranslator(nodes.NodeVisitor): result.append((indent, res)) for itemindent, item in content: if itemindent == -1: - toformat.append(item) + toformat.append(item) # type: ignore else: do_format() - result.append((indent + itemindent, item)) + result.append((indent + itemindent, item)) # type: ignore toformat = [] do_format() if first is not None and result: @@ -221,9 +240,11 @@ class TextTranslator(nodes.NodeVisitor): self.states[-1].extend(result) def visit_document(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_document(self, node): + # type: (nodes.Node) -> None self.end_state() self.body = self.nl.join(line and (' '*indent + line) for indent, lines in self.states[0] @@ -231,126 +252,161 @@ class TextTranslator(nodes.NodeVisitor): # XXX header/footer? def visit_highlightlang(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_section(self, node): + # type: (nodes.Node) -> None self._title_char = self.sectionchars[self.sectionlevel] self.sectionlevel += 1 def depart_section(self, node): + # type: (nodes.Node) -> None self.sectionlevel -= 1 def visit_topic(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_topic(self, node): + # type: (nodes.Node) -> None self.end_state() visit_sidebar = visit_topic depart_sidebar = depart_topic def visit_rubric(self, node): + # type: (nodes.Node) -> None self.new_state(0) self.add_text('-[ ') def depart_rubric(self, node): + # type: (nodes.Node) -> None self.add_text(' ]-') self.end_state() def visit_compound(self, node): + # type: (nodes.Node) -> None pass def depart_compound(self, node): + # type: (nodes.Node) -> None pass def visit_glossary(self, node): + # type: (nodes.Node) -> None pass def depart_glossary(self, node): + # type: (nodes.Node) -> None pass def visit_title(self, node): + # type: (nodes.Node) -> None if isinstance(node.parent, nodes.Admonition): self.add_text(node.astext()+': ') raise nodes.SkipNode self.new_state(0) def depart_title(self, node): + # type: (nodes.Node) -> None if isinstance(node.parent, nodes.section): char = self._title_char else: char = '^' - text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) + text = None # type: unicode + text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) # type: ignore self.stateindent.pop() - title = ['', text, '%s' % (char * column_width(text)), ''] + title = ['', text, '%s' % (char * column_width(text)), ''] # type: List[unicode] if len(self.states) == 2 and len(self.states[-1]) == 0: # remove an empty line before title if it is first section title in the document title.pop(0) self.states[-1].append((0, title)) def visit_subtitle(self, node): + # type: (nodes.Node) -> None pass def depart_subtitle(self, node): + # type: (nodes.Node) -> None pass def visit_attribution(self, node): + # type: (nodes.Node) -> None self.add_text('-- ') def depart_attribution(self, node): + # type: (nodes.Node) -> None pass def visit_desc(self, node): + # type: (nodes.Node) -> None pass def depart_desc(self, node): + # type: (nodes.Node) -> None pass def visit_desc_signature(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_desc_signature(self, node): + # type: (nodes.Node) -> None # XXX: wrap signatures in a way that makes sense self.end_state(wrap=False, end=None) def visit_desc_signature_line(self, node): + # type: (nodes.Node) -> None pass def depart_desc_signature_line(self, node): + # type: (nodes.Node) -> None self.add_text('\n') def visit_desc_name(self, node): + # type: (nodes.Node) -> None pass def depart_desc_name(self, node): + # type: (nodes.Node) -> None pass def visit_desc_addname(self, node): + # type: (nodes.Node) -> None pass def depart_desc_addname(self, node): + # type: (nodes.Node) -> None pass def visit_desc_type(self, node): + # type: (nodes.Node) -> None pass def depart_desc_type(self, node): + # type: (nodes.Node) -> None pass def visit_desc_returns(self, node): + # type: (nodes.Node) -> None self.add_text(' -> ') def depart_desc_returns(self, node): + # type: (nodes.Node) -> None pass def visit_desc_parameterlist(self, node): + # type: (nodes.Node) -> None self.add_text('(') self.first_param = 1 def depart_desc_parameterlist(self, node): + # type: (nodes.Node) -> None self.add_text(')') def visit_desc_parameter(self, node): + # type: (nodes.Node) -> None if not self.first_param: self.add_text(', ') else: @@ -359,37 +415,48 @@ class TextTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_desc_optional(self, node): + # type: (nodes.Node) -> None self.add_text('[') def depart_desc_optional(self, node): + # type: (nodes.Node) -> None self.add_text(']') def visit_desc_annotation(self, node): + # type: (nodes.Node) -> None pass def depart_desc_annotation(self, node): + # type: (nodes.Node) -> None pass def visit_desc_content(self, node): + # type: (nodes.Node) -> None self.new_state() self.add_text(self.nl) def depart_desc_content(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_figure(self, node): + # type: (nodes.Node) -> None self.new_state() def depart_figure(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_caption(self, node): + # type: (nodes.Node) -> None pass def depart_caption(self, node): + # type: (nodes.Node) -> None pass def visit_productionlist(self, node): + # type: (nodes.Node) -> None self.new_state() names = [] for production in node: @@ -407,13 +474,16 @@ class TextTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_footnote(self, node): + # type: (nodes.Node) -> None self._footnote = node.children[0].astext().strip() self.new_state(len(self._footnote) + 3) def depart_footnote(self, node): + # type: (nodes.Node) -> None self.end_state(first='[%s] ' % self._footnote) def visit_citation(self, node): + # type: (nodes.Node) -> None if len(node) and isinstance(node[0], nodes.label): self._citlabel = node[0].astext() else: @@ -421,116 +491,150 @@ class TextTranslator(nodes.NodeVisitor): self.new_state(len(self._citlabel) + 3) def depart_citation(self, node): + # type: (nodes.Node) -> None self.end_state(first='[%s] ' % self._citlabel) def visit_label(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_legend(self, node): + # type: (nodes.Node) -> None pass def depart_legend(self, node): + # type: (nodes.Node) -> None pass # XXX: option list could use some better styling def visit_option_list(self, node): + # type: (nodes.Node) -> None pass def depart_option_list(self, node): + # type: (nodes.Node) -> None pass def visit_option_list_item(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_option_list_item(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_option_group(self, node): + # type: (nodes.Node) -> None self._firstoption = True def depart_option_group(self, node): + # type: (nodes.Node) -> None self.add_text(' ') def visit_option(self, node): + # type: (nodes.Node) -> None if self._firstoption: self._firstoption = False else: self.add_text(', ') def depart_option(self, node): + # type: (nodes.Node) -> None pass def visit_option_string(self, node): + # type: (nodes.Node) -> None pass def depart_option_string(self, node): + # type: (nodes.Node) -> None pass def visit_option_argument(self, node): + # type: (nodes.Node) -> None self.add_text(node['delimiter']) def depart_option_argument(self, node): + # type: (nodes.Node) -> None pass def visit_description(self, node): + # type: (nodes.Node) -> None pass def depart_description(self, node): + # type: (nodes.Node) -> None pass def visit_tabular_col_spec(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_colspec(self, node): - self.table[0].append(node['colwidth']) + # type: (nodes.Node) -> None + self.table[0].append(node['colwidth']) # type: ignore raise nodes.SkipNode def visit_tgroup(self, node): + # type: (nodes.Node) -> None pass def depart_tgroup(self, node): + # type: (nodes.Node) -> None pass def visit_thead(self, node): + # type: (nodes.Node) -> None pass def depart_thead(self, node): + # type: (nodes.Node) -> None pass def visit_tbody(self, node): + # type: (nodes.Node) -> None self.table.append('sep') def depart_tbody(self, node): + # type: (nodes.Node) -> None pass def visit_row(self, node): + # type: (nodes.Node) -> None self.table.append([]) def depart_row(self, node): + # type: (nodes.Node) -> None pass def visit_entry(self, node): + # type: (nodes.Node) -> None if 'morerows' in node or 'morecols' in node: raise NotImplementedError('Column or row spanning cells are ' 'not implemented.') self.new_state(0) def depart_entry(self, node): + # type: (nodes.Node) -> None text = self.nl.join(self.nl.join(x[1]) for x in self.states.pop()) self.stateindent.pop() - self.table[-1].append(text) + self.table[-1].append(text) # type: ignore def visit_table(self, node): + # type: (nodes.Node) -> None if self.table: raise NotImplementedError('Nested tables are not supported.') self.new_state(0) self.table = [[]] def depart_table(self, node): - lines = self.table[1:] - fmted_rows = [] - colwidths = self.table[0] + # type: (nodes.Node) -> None + lines = None # type: List[unicode] + lines = self.table[1:] # type: ignore + fmted_rows = [] # type: List[List[List[unicode]]] + colwidths = None # type: List[int] + colwidths = self.table[0] # type: ignore realwidths = colwidths[:] separator = 0 # don't allow paragraphs in table cells for now @@ -538,7 +642,7 @@ class TextTranslator(nodes.NodeVisitor): if line == 'sep': separator = len(fmted_rows) else: - cells = [] + cells = [] # type: List[List[unicode]] for i, cell in enumerate(line): par = my_wrap(cell, width=colwidths[i]) if par: @@ -550,13 +654,15 @@ class TextTranslator(nodes.NodeVisitor): fmted_rows.append(cells) def writesep(char='-'): - out = ['+'] + # type: (unicode) -> None + out = ['+'] # type: List[unicode] for width in realwidths: out.append(char * (width+2)) out.append('+') self.add_text(''.join(out) + self.nl) def writerow(row): + # type: (list[List[unicode]]) -> None lines = zip_longest(*row) for line in lines: out = ['|'] @@ -581,6 +687,7 @@ class TextTranslator(nodes.NodeVisitor): self.end_state(wrap=False) def visit_acks(self, node): + # type: (nodes.Node) -> None self.new_state(0) self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') @@ -588,12 +695,14 @@ class TextTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_image(self, node): + # type: (nodes.Node) -> None if 'alt' in node.attributes: self.add_text(_('[image: %s]') % node['alt']) self.add_text(_('[image]')) raise nodes.SkipNode def visit_transition(self, node): + # type: (nodes.Node) -> None indent = sum(self.stateindent) self.new_state(0) self.add_text('=' * (MAXWIDTH - indent)) @@ -601,24 +710,31 @@ class TextTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_bullet_list(self, node): + # type: (nodes.Node) -> None self.list_counter.append(-1) def depart_bullet_list(self, node): + # type: (nodes.Node) -> None self.list_counter.pop() def visit_enumerated_list(self, node): + # type: (nodes.Node) -> None self.list_counter.append(node.get('start', 1) - 1) def depart_enumerated_list(self, node): + # type: (nodes.Node) -> None self.list_counter.pop() def visit_definition_list(self, node): + # type: (nodes.Node) -> None self.list_counter.append(-2) def depart_definition_list(self, node): + # type: (nodes.Node) -> None self.list_counter.pop() def visit_list_item(self, node): + # type: (nodes.Node) -> None if self.list_counter[-1] == -1: # bullet list self.new_state(2) @@ -631,6 +747,7 @@ class TextTranslator(nodes.NodeVisitor): self.new_state(len(str(self.list_counter[-1])) + 2) def depart_list_item(self, node): + # type: (nodes.Node) -> None if self.list_counter[-1] == -1: self.end_state(first='* ') elif self.list_counter[-1] == -2: @@ -639,90 +756,107 @@ class TextTranslator(nodes.NodeVisitor): self.end_state(first='%s. ' % self.list_counter[-1]) def visit_definition_list_item(self, node): + # type: (nodes.Node) -> None self._classifier_count_in_li = len(node.traverse(nodes.classifier)) def depart_definition_list_item(self, node): + # type: (nodes.Node) -> None pass def visit_term(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_term(self, node): + # type: (nodes.Node) -> None if not self._classifier_count_in_li: self.end_state(end=None) - def visit_termsep(self, node): - warnings.warn('sphinx.addnodes.termsep will be removed at Sphinx-1.6. ' - 'This warning is displayed because some Sphinx extension ' - 'uses sphinx.addnodes.termsep. Please report it to ' - 'author of the extension.', RemovedInSphinx16Warning) - self.add_text(', ') - raise nodes.SkipNode - def visit_classifier(self, node): + # type: (nodes.Node) -> None self.add_text(' : ') def depart_classifier(self, node): + # type: (nodes.Node) -> None self._classifier_count_in_li -= 1 if not self._classifier_count_in_li: self.end_state(end=None) def visit_definition(self, node): + # type: (nodes.Node) -> None self.new_state() def depart_definition(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_field_list(self, node): + # type: (nodes.Node) -> None pass def depart_field_list(self, node): + # type: (nodes.Node) -> None pass def visit_field(self, node): + # type: (nodes.Node) -> None pass def depart_field(self, node): + # type: (nodes.Node) -> None pass def visit_field_name(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_field_name(self, node): + # type: (nodes.Node) -> None self.add_text(':') self.end_state(end=None) def visit_field_body(self, node): + # type: (nodes.Node) -> None self.new_state() def depart_field_body(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_centered(self, node): + # type: (nodes.Node) -> None pass def depart_centered(self, node): + # type: (nodes.Node) -> None pass def visit_hlist(self, node): + # type: (nodes.Node) -> None pass def depart_hlist(self, node): + # type: (nodes.Node) -> None pass def visit_hlistcol(self, node): + # type: (nodes.Node) -> None pass def depart_hlistcol(self, node): + # type: (nodes.Node) -> None pass def visit_admonition(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_admonition(self, node): + # type: (nodes.Node) -> None self.end_state() def _visit_admonition(self, node): + # type: (nodes.Node) -> None self.new_state(2) if isinstance(node.children[0], nodes.Sequential): @@ -730,6 +864,7 @@ class TextTranslator(nodes.NodeVisitor): def _make_depart_admonition(name): def depart_admonition(self, node): + # type: (nodes.NodeVisitor, nodes.Node) -> None self.end_state(first=admonitionlabels[name] + ': ') return depart_admonition @@ -755,211 +890,274 @@ class TextTranslator(nodes.NodeVisitor): depart_seealso = _make_depart_admonition('seealso') def visit_versionmodified(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_versionmodified(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_literal_block(self, node): + # type: (nodes.Node) -> None self.new_state() def depart_literal_block(self, node): + # type: (nodes.Node) -> None self.end_state(wrap=False) def visit_doctest_block(self, node): + # type: (nodes.Node) -> None self.new_state(0) def depart_doctest_block(self, node): + # type: (nodes.Node) -> None self.end_state(wrap=False) def visit_line_block(self, node): + # type: (nodes.Node) -> None self.new_state() self.lineblocklevel += 1 def depart_line_block(self, node): + # type: (nodes.Node) -> None self.lineblocklevel -= 1 self.end_state(wrap=False, end=None) if not self.lineblocklevel: self.add_text('\n') def visit_line(self, node): + # type: (nodes.Node) -> None pass def depart_line(self, node): + # type: (nodes.Node) -> None self.add_text('\n') def visit_block_quote(self, node): + # type: (nodes.Node) -> None self.new_state() def depart_block_quote(self, node): + # type: (nodes.Node) -> None self.end_state() def visit_compact_paragraph(self, node): + # type: (nodes.Node) -> None pass def depart_compact_paragraph(self, node): + # type: (nodes.Node) -> None pass def visit_paragraph(self, node): + # type: (nodes.Node) -> None if not isinstance(node.parent, nodes.Admonition) or \ isinstance(node.parent, addnodes.seealso): self.new_state(0) def depart_paragraph(self, node): + # type: (nodes.Node) -> None if not isinstance(node.parent, nodes.Admonition) or \ isinstance(node.parent, addnodes.seealso): self.end_state() def visit_target(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_index(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_toctree(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_substitution_definition(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_pending_xref(self, node): + # type: (nodes.Node) -> None pass def depart_pending_xref(self, node): + # type: (nodes.Node) -> None pass def visit_reference(self, node): + # type: (nodes.Node) -> None pass def depart_reference(self, node): + # type: (nodes.Node) -> None pass def visit_number_reference(self, node): + # type: (nodes.Node) -> None text = nodes.Text(node.get('title', '#')) self.visit_Text(text) raise nodes.SkipNode def visit_download_reference(self, node): + # type: (nodes.Node) -> None pass def depart_download_reference(self, node): + # type: (nodes.Node) -> None pass def visit_emphasis(self, node): + # type: (nodes.Node) -> None self.add_text('*') def depart_emphasis(self, node): + # type: (nodes.Node) -> None self.add_text('*') def visit_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.add_text('*') def depart_literal_emphasis(self, node): + # type: (nodes.Node) -> None self.add_text('*') def visit_strong(self, node): + # type: (nodes.Node) -> None self.add_text('**') def depart_strong(self, node): + # type: (nodes.Node) -> None self.add_text('**') def visit_literal_strong(self, node): + # type: (nodes.Node) -> None self.add_text('**') def depart_literal_strong(self, node): + # type: (nodes.Node) -> None self.add_text('**') def visit_abbreviation(self, node): + # type: (nodes.Node) -> None self.add_text('') def depart_abbreviation(self, node): + # type: (nodes.Node) -> None if node.hasattr('explanation'): self.add_text(' (%s)' % node['explanation']) def visit_manpage(self, node): + # type: (nodes.Node) -> Any return self.visit_literal_emphasis(node) def depart_manpage(self, node): + # type: (nodes.Node) -> Any return self.depart_literal_emphasis(node) def visit_title_reference(self, node): + # type: (nodes.Node) -> None self.add_text('*') def depart_title_reference(self, node): + # type: (nodes.Node) -> None self.add_text('*') def visit_literal(self, node): + # type: (nodes.Node) -> None self.add_text('"') def depart_literal(self, node): + # type: (nodes.Node) -> None self.add_text('"') def visit_subscript(self, node): + # type: (nodes.Node) -> None self.add_text('_') def depart_subscript(self, node): + # type: (nodes.Node) -> None pass def visit_superscript(self, node): + # type: (nodes.Node) -> None self.add_text('^') def depart_superscript(self, node): + # type: (nodes.Node) -> None pass def visit_footnote_reference(self, node): + # type: (nodes.Node) -> None self.add_text('[%s]' % node.astext()) raise nodes.SkipNode def visit_citation_reference(self, node): + # type: (nodes.Node) -> None self.add_text('[%s]' % node.astext()) raise nodes.SkipNode def visit_Text(self, node): + # type: (nodes.Node) -> None self.add_text(node.astext()) def depart_Text(self, node): + # type: (nodes.Node) -> None pass def visit_generated(self, node): + # type: (nodes.Node) -> None pass def depart_generated(self, node): + # type: (nodes.Node) -> None pass def visit_inline(self, node): + # type: (nodes.Node) -> None if 'xref' in node['classes'] or 'term' in node['classes']: self.add_text('*') def depart_inline(self, node): + # type: (nodes.Node) -> None if 'xref' in node['classes'] or 'term' in node['classes']: self.add_text('*') def visit_container(self, node): + # type: (nodes.Node) -> None pass def depart_container(self, node): + # type: (nodes.Node) -> None pass def visit_problematic(self, node): + # type: (nodes.Node) -> None self.add_text('>>') def depart_problematic(self, node): + # type: (nodes.Node) -> None self.add_text('<<') def visit_system_message(self, node): + # type: (nodes.Node) -> None self.new_state(0) self.add_text('<SYSTEM MESSAGE: %s>' % node.astext()) self.end_state() raise nodes.SkipNode def visit_comment(self, node): + # type: (nodes.Node) -> None raise nodes.SkipNode def visit_meta(self, node): + # type: (nodes.Node) -> None # only valid for HTML raise nodes.SkipNode def visit_raw(self, node): + # type: (nodes.Node) -> None if 'text' in node.get('format', '').split(): self.new_state(0) self.add_text(node.astext()) @@ -967,13 +1165,15 @@ class TextTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_math(self, node): - self.builder.warn('using "math" markup without a Sphinx math extension ' - 'active, please use one of the math extensions ' - 'described at http://sphinx-doc.org/ext/math.html', - (self.builder.current_docname, node.line)) + # type: (nodes.Node) -> None + logger.warning('using "math" markup without a Sphinx math extension ' + 'active, please use one of the math extensions ' + 'described at http://sphinx-doc.org/ext/math.html', + location=(self.builder.current_docname, node.line)) raise nodes.SkipNode visit_math_block = visit_math def unknown_visit(self, node): + # type: (nodes.Node) -> None raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/xml.py b/sphinx/writers/xml.py index 5aa0ad96a..879f65dd3 100644 --- a/sphinx/writers/xml.py +++ b/sphinx/writers/xml.py @@ -12,16 +12,23 @@ from docutils import writers from docutils.writers.docutils_xml import Writer as BaseXMLWriter +if False: + # For type annotation + from typing import Any, Tuple # NOQA + from sphinx.builders import Builder # NOQA + class XMLWriter(BaseXMLWriter): def __init__(self, builder): + # type: (Builder) -> None BaseXMLWriter.__init__(self) self.builder = builder if self.builder.translator_class: self.translator_class = self.builder.translator_class def translate(self, *args, **kwargs): + # type: (Any, Any) -> None self.document.settings.newlines = \ self.document.settings.indents = \ self.builder.env.config.xml_pretty @@ -36,18 +43,21 @@ class PseudoXMLWriter(writers.Writer): """Formats this writer supports.""" config_section = 'pseudoxml writer' - config_section_dependencies = ('writers',) + config_section_dependencies = ('writers',) # type: Tuple[unicode] output = None """Final translated form of `document`.""" def __init__(self, builder): + # type: (Builder) -> None writers.Writer.__init__(self) self.builder = builder def translate(self): + # type: () -> None self.output = self.document.pformat() def supports(self, format): + # type: (unicode) -> bool """This writer supports all format-specific elements.""" return True diff --git a/test-reqs.txt b/test-reqs.txt index 1877886c1..e06513a01 100644 --- a/test-reqs.txt +++ b/test-reqs.txt @@ -16,3 +16,4 @@ imagesize requests html5lib enum34 +typing diff --git a/tests/root/Makefile b/tests/root/Makefile index 7d5162fe7..85a93bc54 100644 --- a/tests/root/Makefile +++ b/tests/root/Makefile @@ -4,12 +4,9 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = # Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d _build/doctrees $(SPHINXOPTS) . .PHONY: help clean html web pickle htmlhelp latex changes linkcheck @@ -18,7 +15,7 @@ help: @echo " html to make standalone HTML files" @echo " pickle to make pickle files (usable by e.g. sphinx-web)" @echo " htmlhelp to make HTML files and an HTML help project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latex to make LaTeX files" @echo " changes to make an overview over all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" diff --git a/tests/root/conf.py b/tests/root/conf.py index f2684e33f..a23aec482 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -84,8 +84,8 @@ tags.add('confpytag') # -- extension API from docutils import nodes +from docutils.parsers.rst import Directive from sphinx import addnodes -from sphinx.util.compat import Directive def userdesc_parse(env, sig, signode): diff --git a/tests/test_api_translator.py b/tests/test_api_translator.py index 5f2707cc3..f1c70a671 100644 --- a/tests/test_api_translator.py +++ b/tests/test_api_translator.py @@ -25,22 +25,13 @@ def teardown_module(): @pytest.mark.sphinx('html') def test_html_translator(app, status, warning): - # no set_translator(), no html_translator_class + # no set_translator() translator_class = app.builder.translator_class assert translator_class assert translator_class.__name__ == 'SmartyPantsHTMLTranslator' @pytest.mark.sphinx('html', confoverrides={ - 'html_translator_class': 'translator.ExtHTMLTranslator'}) -def test_html_with_html_translator_class(app, status, warning): - # no set_translator(), but html_translator_class - translator_class = app.builder.translator_class - assert translator_class - assert translator_class.__name__ == 'ExtHTMLTranslator' - - -@pytest.mark.sphinx('html', confoverrides={ 'html_use_smartypants': False}) def test_html_with_smartypants(app, status, warning): # no set_translator(), html_use_smartypants=False @@ -51,18 +42,7 @@ def test_html_with_smartypants(app, status, warning): @pytest.mark.sphinx('html', testroot='api-set-translator') def test_html_with_set_translator_for_html_(app, status, warning): - # use set_translator(), no html_translator_class - translator_class = app.builder.translator_class - assert translator_class - assert translator_class.__name__ == 'ConfHTMLTranslator' - - -@pytest.mark.sphinx('html', testroot='api-set-translator', confoverrides={ - 'html_translator_class': 'translator.ExtHTMLTranslator'}) -def test_html_with_set_translator_for_html_and_html_translator_class( - app, status, warning): - # use set_translator() and html_translator_class. - # set_translator() is given priority over html_translator_clas. + # use set_translator() translator_class = app.builder.translator_class assert translator_class assert translator_class.__name__ == 'ConfHTMLTranslator' diff --git a/tests/test_application.py b/tests/test_application.py index 00223350b..e83e2b4de 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -49,40 +49,6 @@ def test_emit_with_nonascii_name_node(app, status, warning): app.emit('my_event', node) -def test_output(app, status, warning): - # info with newline - status.truncate(0) # __init__ writes to status - status.seek(0) - app.info("Nothing here...") - assert status.getvalue() == "Nothing here...\n" - # info without newline - status.truncate(0) - status.seek(0) - app.info("Nothing here...", True) - assert status.getvalue() == "Nothing here..." - - # warning - old_count = app._warncount - app.warn("Bad news!") - assert strip_escseq(warning.getvalue()) == "WARNING: Bad news!\n" - assert app._warncount == old_count + 1 - - -def test_output_with_unencodable_char(app, status, warning): - - class StreamWriter(codecs.StreamWriter): - def write(self, object): - self.stream.write(object.encode('cp1252').decode('cp1252')) - - app._status = StreamWriter(status) - - # info with UnicodeEncodeError - status.truncate(0) - status.seek(0) - app.info(u"unicode \u206d...") - assert status.getvalue() == "unicode ?...\n" - - def test_extensions(app, status, warning): app.setup_extension('shutil') assert strip_escseq(warning.getvalue()).startswith("WARNING: extension 'shutil'") diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 63c8111e1..98a11d1fc 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -39,10 +39,10 @@ with "\\?": b?'here: >>>(\\\\|/)xbb<<<((\\\\|/)r)?' """ HTML_WARNINGS = ENV_WARNINGS + """\ -%(root)s/index.rst:\\d+: WARNING: no matching candidate for image URI u'foo.\\*' -%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block as "c". Highlighting skipped. %(root)s/index.rst:\\d+: WARNING: unknown option: &option %(root)s/index.rst:\\d+: WARNING: citation not found: missing +%(root)s/index.rst:\\d+: WARNING: no matching candidate for image URI u'foo.\\*' +%(root)s/index.rst:\\d+: WARNING: Could not lex literal_block as "c". Highlighting skipped. """ if PY3: diff --git a/tests/test_config.py b/tests/test_config.py index 4bf4d6c11..75de8d57c 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -90,7 +90,8 @@ def test_extension_values(app, status, warning): assert 'already present' in str(excinfo.value) -def test_errors_warnings(tempdir): +@mock.patch("sphinx.config.logger") +def test_errors_warnings(logger, tempdir): # test the error for syntax errors in the config file (tempdir / 'conf.py').write_text(u'project = \n', encoding='ascii') with pytest.raises(ConfigError) as excinfo: @@ -102,8 +103,9 @@ def test_errors_warnings(tempdir): u'# -*- coding: utf-8\n\nproject = u"Jägermeister"\n', encoding='utf-8') cfg = Config(tempdir, 'conf.py', {}, None) - cfg.init_values(lambda warning: 1/0) + cfg.init_values() assert cfg.project == u'Jägermeister' + assert logger.called is False # test the warning for bytestrings with non-ascii content # bytestrings with non-ascii content are a syntax error in python3 so we @@ -113,13 +115,10 @@ def test_errors_warnings(tempdir): (tempdir / 'conf.py').write_text( u'# -*- coding: latin-1\nproject = "fooä"\n', encoding='latin-1') cfg = Config(tempdir, 'conf.py', {}, None) - warned = [False] - def warn(msg): - warned[0] = True - - cfg.check_unicode(warn) - assert warned[0] + assert logger.warning.called is False + cfg.check_unicode() + assert logger.warning.called is True def test_errors_if_setup_is_not_callable(tempdir, make_app): @@ -157,14 +156,16 @@ def test_needs_sphinx(make_app): make_app(confoverrides={'needs_sphinx': '2'}) # NG: greater -def test_config_eol(tempdir): +@mock.patch("sphinx.config.logger") +def test_config_eol(logger, tempdir): # test config file's eol patterns: LF, CRLF configfile = tempdir / 'conf.py' for eol in (b'\n', b'\r\n'): configfile.write_bytes(b'project = "spam"' + eol) cfg = Config(tempdir, 'conf.py', {}, None) - cfg.init_values(lambda warning: 1/0) + cfg.init_values() assert cfg.project == u'spam' + assert logger.called is False @pytest.mark.sphinx(confoverrides={'master_doc': 123, diff --git a/tests/test_environment.py b/tests/test_environment.py index 476b66923..a0e438494 100644 --- a/tests/test_environment.py +++ b/tests/test_environment.py @@ -15,27 +15,18 @@ from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.builders.latex import LaTeXBuilder app = env = None -warnings = [] def setup_module(): global app, env app = SphinxTestApp(srcdir='root-envtest') env = app.env - env.set_warnfunc(lambda *args, **kwargs: warnings.append(args)) def teardown_module(): app.cleanup() -def warning_emitted(file, text): - for warning in warnings: - if len(warning) == 2 and file in warning[1] and text in warning[0]: - return True - return False - - # Tests are run in the order they appear in the file, therefore we can # afford to not run update() in the setup but in its own test @@ -47,9 +38,10 @@ def test_first_update(): def test_images(): - assert warning_emitted('images', 'image file not readable: foo.png') - assert warning_emitted('images', 'nonlocal image URI found: ' - 'http://www.python.org/logo.png') + assert ('image file not readable: foo.png' + in app._warning.getvalue()) + assert ('nonlocal image URI found: http://www.python.org/logo.png' + in app._warning.getvalue()) tree = env.get_doctree('images') htmlbuilder = StandaloneHTMLBuilder(app) diff --git a/tests/test_ext_napoleon.py b/tests/test_ext_napoleon.py index 21d095a79..5f68ba7c0 100644 --- a/tests/test_ext_napoleon.py +++ b/tests/test_ext_napoleon.py @@ -123,19 +123,19 @@ class SetupTest(TestCase): class SkipMemberTest(TestCase): - def assertSkip(self, what, member, obj, expect_skip, config_name): - skip = 'default skip' + def assertSkip(self, what, member, obj, expect_default_skip, config_name): + skip = True app = mock.Mock() app.config = Config() setattr(app.config, config_name, True) - if expect_skip: - self.assertEqual(skip, _skip_member(app, what, member, obj, skip, + if expect_default_skip: + self.assertEqual(None, _skip_member(app, what, member, obj, skip, mock.Mock())) else: self.assertFalse(_skip_member(app, what, member, obj, skip, mock.Mock())) setattr(app.config, config_name, False) - self.assertEqual(skip, _skip_member(app, what, member, obj, skip, + self.assertEqual(None, _skip_member(app, what, member, obj, skip, mock.Mock())) def test_namedtuple(self): diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py index 44a1cb3c1..e2c5221ff 100644 --- a/tests/test_highlighting.py +++ b/tests/test_highlighting.py @@ -9,9 +9,9 @@ :license: BSD, see LICENSE for details. """ +import mock from pygments.lexer import RegexLexer from pygments.token import Text, Name -from pygments.filters import ErrorToken from pygments.formatters.html import HtmlFormatter from sphinx.highlighting import PygmentsBridge @@ -86,7 +86,8 @@ def test_trim_doctest_flags(): PygmentsBridge.html_formatter = HtmlFormatter -def test_default_highlight(): +@mock.patch('sphinx.highlighting.logger') +def test_default_highlight(logger): bridge = PygmentsBridge('html') # default: highlights as python3 @@ -104,8 +105,8 @@ def test_default_highlight(): '<span class="s2">"Hello sphinx world"</span>\n</pre></div>\n') # python3: raises error if highlighting failed - try: - ret = bridge.highlight_block('reST ``like`` text', 'python3') - assert False, "highlight_block() does not raise any exceptions" - except ErrorToken: - pass # raise parsing error + ret = bridge.highlight_block('reST ``like`` text', 'python3') + logger.warning.assert_called_with('Could not lex literal_block as "%s". ' + 'Highlighting skipped.', 'python3', + type='misc', subtype='highlighting_failure', + location=None) diff --git a/tests/test_intl.py b/tests/test_intl.py index e7bb130ff..5fb3cea24 100644 --- a/tests/test_intl.py +++ b/tests/test_intl.py @@ -1138,4 +1138,4 @@ def test_image_glob_intl_using_figure_language_filename(app): def getwarning(warnings): - return warnings.getvalue().replace(os.sep, '/') + return strip_escseq(warnings.getvalue().replace(os.sep, '/')) diff --git a/tests/test_util_i18n.py b/tests/test_util_i18n.py index d7665e58e..d5a0f8f64 100644 --- a/tests/test_util_i18n.py +++ b/tests/test_util_i18n.py @@ -159,15 +159,6 @@ def test_get_catalogs_with_compact(tempdir): def test_format_date(): date = datetime.date(2016, 2, 7) - # default format - format = None - assert i18n.format_date(format, date=date) == 'Feb 7, 2016' - assert i18n.format_date(format, date=date, language='') == 'Feb 7, 2016' - assert i18n.format_date(format, date=date, language='unknown') == 'Feb 7, 2016' - assert i18n.format_date(format, date=date, language='en') == 'Feb 7, 2016' - assert i18n.format_date(format, date=date, language='ja') == '2016/02/07' - assert i18n.format_date(format, date=date, language='de') == '07.02.2016' - # strftime format format = '%B %d, %Y' assert i18n.format_date(format, date=date) == 'February 07, 2016' @@ -177,15 +168,6 @@ def test_format_date(): assert i18n.format_date(format, date=date, language='ja') == u'2月 07, 2016' assert i18n.format_date(format, date=date, language='de') == 'Februar 07, 2016' - # LDML format - format = 'MMM dd, YYYY' - assert i18n.format_date(format, date=date) == 'Feb 07, 2016' - assert i18n.format_date(format, date=date, language='') == 'Feb 07, 2016' - assert i18n.format_date(format, date=date, language='unknown') == 'Feb 07, 2016' - assert i18n.format_date(format, date=date, language='en') == 'Feb 07, 2016' - assert i18n.format_date(format, date=date, language='ja') == u'2月 07, 2016' - assert i18n.format_date(format, date=date, language='de') == 'Feb. 07, 2016' - # raw string format = 'Mon Mar 28 12:37:08 2016, commit 4367aef' assert i18n.format_date(format, date=date) == format diff --git a/tests/test_util_logging.py b/tests/test_util_logging.py index d88d3cc6d..4083ec5bd 100644 --- a/tests/test_util_logging.py +++ b/tests/test_util_logging.py @@ -10,7 +10,96 @@ """ from __future__ import print_function +import codecs +from docutils import nodes + +from sphinx.errors import SphinxWarning +from sphinx.util import logging +from sphinx.util.console import colorize from sphinx.util.logging import is_suppressed_warning +from sphinx.util.parallel import ParallelTasks + +import pytest +from util import strip_escseq + + +def test_info_and_warning(app, status, warning): + app.verbosity = 2 + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.debug('message1') + logger.info('message2') + logger.warning('message3') + logger.critical('message4') + logger.error('message5') + + assert 'message1' in status.getvalue() + assert 'message2' in status.getvalue() + assert 'message3' not in status.getvalue() + assert 'message4' not in status.getvalue() + assert 'message5' not in status.getvalue() + + assert 'message1' not in warning.getvalue() + assert 'message2' not in warning.getvalue() + assert 'message3' in warning.getvalue() + assert 'message4' in warning.getvalue() + assert 'message5' in warning.getvalue() + + +def test_verbosity_filter(app, status, warning): + # verbosity = 0: INFO + app.verbosity = 0 + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.info('message1') + logger.verbose('message2') + logger.debug('message3') + + assert 'message1' in status.getvalue() + assert 'message2' not in status.getvalue() + assert 'message3' not in status.getvalue() + assert 'message4' not in status.getvalue() + + # verbosity = 1: VERBOSE + app.verbosity = 1 + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.info('message1') + logger.verbose('message2') + logger.debug('message3') + + assert 'message1' in status.getvalue() + assert 'message2' in status.getvalue() + assert 'message3' not in status.getvalue() + assert 'message4' not in status.getvalue() + + # verbosity = 2: DEBUG + app.verbosity = 2 + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.info('message1') + logger.verbose('message2') + logger.debug('message3') + + assert 'message1' in status.getvalue() + assert 'message2' in status.getvalue() + assert 'message3' in status.getvalue() + assert 'message4' not in status.getvalue() + + +def test_nonl_info_log(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.info('message1', nonl=True) + logger.info('message2') + logger.info('message3') + + assert 'message1message2\nmessage3' in status.getvalue() def test_is_suppressed_warning(): @@ -24,3 +113,159 @@ def test_is_suppressed_warning(): assert is_suppressed_warning("files", "stylesheet", suppress_warnings) is True assert is_suppressed_warning("rest", "syntax", suppress_warnings) is False assert is_suppressed_warning("rest", "duplicated_labels", suppress_warnings) is True + + +def test_suppress_warnings(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + app._warncount = 0 # force reset + + app.config.suppress_warnings = [] + warning.truncate(0) + logger.warning('message1', type='test', subtype='logging') + logger.warning('message2', type='test', subtype='crash') + logger.warning('message3', type='actual', subtype='logging') + assert 'message1' in warning.getvalue() + assert 'message2' in warning.getvalue() + assert 'message3' in warning.getvalue() + assert app._warncount == 3 + + app.config.suppress_warnings = ['test'] + warning.truncate(0) + logger.warning('message1', type='test', subtype='logging') + logger.warning('message2', type='test', subtype='crash') + logger.warning('message3', type='actual', subtype='logging') + assert 'message1' not in warning.getvalue() + assert 'message2' not in warning.getvalue() + assert 'message3' in warning.getvalue() + assert app._warncount == 4 + + app.config.suppress_warnings = ['test.logging'] + warning.truncate(0) + logger.warning('message1', type='test', subtype='logging') + logger.warning('message2', type='test', subtype='crash') + logger.warning('message3', type='actual', subtype='logging') + assert 'message1' not in warning.getvalue() + assert 'message2' in warning.getvalue() + assert 'message3' in warning.getvalue() + assert app._warncount == 6 + + +def test_warningiserror(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + # if False, warning is not error + app.warningiserror = False + logger.warning('message') + + # if True, warning raises SphinxWarning exception + app.warningiserror = True + with pytest.raises(SphinxWarning): + logger.warning('message') + + +def test_warning_location(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.warning('message1', location='index') + assert 'index.txt: WARNING: message1' in warning.getvalue() + + logger.warning('message2', location=('index', 10)) + assert 'index.txt:10: WARNING: message2' in warning.getvalue() + + logger.warning('message3', location=None) + assert colorize('darkred', 'WARNING: message3') in warning.getvalue() + + node = nodes.Node() + node.source, node.line = ('index.txt', 10) + logger.warning('message4', location=node) + assert 'index.txt:10: WARNING: message4' in warning.getvalue() + + node.source, node.line = ('index.txt', None) + logger.warning('message5', location=node) + assert 'index.txt:: WARNING: message5' in warning.getvalue() + + node.source, node.line = (None, 10) + logger.warning('message6', location=node) + assert '<unknown>:10: WARNING: message6' in warning.getvalue() + + node.source, node.line = (None, None) + logger.warning('message7', location=node) + assert colorize('darkred', 'WARNING: message7') in warning.getvalue() + + +def test_pending_warnings(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + logger.warning('message1') + with logging.pending_warnings(): + # not logged yet (bufferred) in here + logger.warning('message2') + logger.warning('message3') + assert 'WARNING: message1' in warning.getvalue() + assert 'WARNING: message2' not in warning.getvalue() + assert 'WARNING: message3' not in warning.getvalue() + + # actually logged as ordered + assert 'WARNING: message2\nWARNING: message3' in strip_escseq(warning.getvalue()) + + +def test_colored_logs(app, status, warning): + app.verbosity = 2 + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + # default colors + logger.debug('message1') + logger.verbose('message2') + logger.info('message3') + logger.warning('message4') + logger.critical('message5') + logger.error('message6') + + assert colorize('darkgray', 'message1') in status.getvalue() + assert 'message2\n' in status.getvalue() # not colored + assert 'message3\n' in status.getvalue() # not colored + assert colorize('darkred', 'WARNING: message4') in warning.getvalue() + assert 'WARNING: message5\n' in warning.getvalue() # not colored + assert 'WARNING: message6\n' in warning.getvalue() # not colored + + # color specification + logger.debug('message7', color='white') + logger.info('message8', color='red') + assert colorize('white', 'message7') in status.getvalue() + assert colorize('red', 'message8') in status.getvalue() + + +def test_logging_in_ParallelTasks(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + def child_process(): + logger.info('message1') + logger.warning('message2', location='index') + + tasks = ParallelTasks(1) + tasks.add_task(child_process) + tasks.join() + assert 'message1' in status.getvalue() + assert 'index.txt: WARNING: message2' in warning.getvalue() + + +def test_output_with_unencodable_char(app, status, warning): + class StreamWriter(codecs.StreamWriter): + def write(self, object): + self.stream.write(object.encode('cp1252').decode('cp1252')) + + logging.setup(app, StreamWriter(status), warning) + logger = logging.getLogger(__name__) + + # info with UnicodeEncodeError + status.truncate(0) + status.seek(0) + logger.info(u"unicode \u206d...") + assert status.getvalue() == "unicode ?...\n" @@ -47,6 +47,10 @@ deps= {[testenv]deps} [testenv:py35] +deps= + mypy-lang + typed_ast + {[testenv]deps} commands= {envpython} -Wall tests/run.py {posargs} sphinx-build -q -W -b html -d {envtmpdir}/doctrees doc {envtmpdir}/html diff --git a/utils/check_sources.py b/utils/check_sources.py index 18d444057..d4a5ab491 100755 --- a/utils/check_sources.py +++ b/utils/check_sources.py @@ -46,6 +46,7 @@ copyright_2_re = re.compile(r'^ %s(, %s)*[,.]$' % (name_mail_re, name_mail_re)) not_ix_re = re.compile(r'\bnot\s+\S+?\s+i[sn]\s\S+') is_const_re = re.compile(r'if.*?==\s+(None|False|True)\b') +noqa_re = re.compile(r'#\s+NOQA\s*$', re.I) misspellings = ["developement", "adress", # ALLOW-MISSPELLING "verificate", "informations"] # ALLOW-MISSPELLING @@ -81,6 +82,8 @@ def check_syntax(fn, lines): @checker('.py') def check_style(fn, lines): for lno, line in enumerate(lines): + if noqa_re.search(line): + continue if len(line.rstrip('\n')) > 95: yield lno+1, "line too long" if line.strip().startswith('#'): |