diff options
135 files changed, 1931 insertions, 2331 deletions
@@ -10,6 +10,10 @@ Incompatible changes Deprecated ---------- +* The ``info`` and ``warn`` arguments of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` +* ``sphinx.ext.autosummary.generate._simple_info()`` +* ``sphinx.ext.autosummary.generate._simple_warn()`` * ``sphinx.ext.todo.merge_info()`` * ``sphinx.ext.todo.process_todo_nodes()`` * ``sphinx.ext.todo.process_todos()`` @@ -21,10 +25,15 @@ Features added Bugs fixed ---------- +* py domain: duplicated warning does not point the location of source code +* #1125: html theme: scrollbar is hard to see on classic theme and macOS +* #5502: linkcheck: Consider HTTP 503 response as not an error +* #6439: Make generated download links reproducible + Testing -------- -Release 2.1.1 (in development) +Release 2.1.2 (in development) ============================== Dependencies @@ -45,6 +54,27 @@ Bugs fixed Testing -------- +Release 2.1.1 (released Jun 10, 2019) +===================================== + +Incompatible changes +-------------------- + +* #6447: autodoc: Stop to generate document for undocumented module variables + +Bugs fixed +---------- + +* #6442: LaTeX: admonitions of :rst:dir:`note` type can get separated from + immediately preceding section title by pagebreak +* #6448: autodoc: crashed when autodocumenting classes with ``__slots__ = None`` +* #6451: autodoc: generates docs for "optional import"ed modules as variables +* #6452: autosummary: crashed when generating document of properties +* #6455: napoleon: docstrings for properties are not processed +* #6436: napoleon: "Unknown target name" error if variable name ends with + underscore +* #6440: apidoc: missing blank lines between modules + Release 2.1.0 (released Jun 02, 2019) ===================================== diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1807d3998..8c74b184a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -250,7 +250,7 @@ the source and the compiled catalogs. When a new locale is submitted, add a new directory with the ISO 639-1 language identifier and put ``sphinx.po`` in there. Don't forget to update the possible -values for :confval:`language` in ``doc/config.rst``. +values for :confval:`language` in ``doc/usage/configuration.rst``. The Sphinx core messages can also be translated on `Transifex <https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index f67c94592..f83235b92 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -26,6 +26,22 @@ The following is a list of deprecated interfaces. - (will be) Removed - Alternatives + * - The ``info`` and ``warn`` arguments of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 2.2 + - 4.0 + - ``logging.info()`` and ``logging.warning()`` + + * - ``sphinx.ext.autosummary.generate._simple_info()`` + - 2.2 + - 4.0 + - ``logging.info()`` + + * - ``sphinx.ext.autosummary.generate._simple_warn()`` + - 2.2 + - 4.0 + - ``logging.warning()`` + * - ``sphinx.ext.todo.merge_info()`` - 2.2 - 4.0 @@ -5,9 +5,6 @@ license_file = LICENSE tag_build = .dev tag_date = true -[bdist_wheel] -universal = 1 - [aliases] release = egg_info -Db '' upload = upload --sign --identity=36580288 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 8eaa0e215..546b9b0a8 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -11,22 +11,27 @@ import pickle import time from os import path +from typing import Any, Dict, Iterable, List, Sequence, Set, Tuple, Type, Union from docutils import nodes +from docutils.nodes import Node -from sphinx.environment import CONFIG_OK, CONFIG_CHANGED_REASON +from sphinx.config import Config +from sphinx.environment import BuildEnvironment, CONFIG_OK, CONFIG_CHANGED_REASON from sphinx.environment.adapters.asset import ImageAdapter from sphinx.errors import SphinxError +from sphinx.events import EventManager from sphinx.io import read_doc from sphinx.locale import __ from sphinx.util import import_object, logging, rst, progress_message, status_iterator from sphinx.util.build_phase import BuildPhase from sphinx.util.console import bold # type: ignore from sphinx.util.docutils import sphinx_domains -from sphinx.util.i18n import CatalogRepository, docname_to_domain +from sphinx.util.i18n import CatalogInfo, CatalogRepository, docname_to_domain from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \ parallel_available +from sphinx.util.tags import Tags # side effect: registers roles and directives from sphinx import roles # noqa @@ -39,13 +44,7 @@ except ImportError: if False: # For type annotation - from typing import Any, Dict, Iterable, List, Sequence, Set, Tuple, Type, Union # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - from sphinx.environment import BuildEnvironment # NOQA - from sphinx.events import EventManager # NOQA - from sphinx.util.i18n import CatalogInfo # NOQA - from sphinx.util.tags import Tags # NOQA + from sphinx.application import Sphinx logger = logging.getLogger(__name__) @@ -84,8 +83,7 @@ class Builder: #: The builder supports data URIs or not. supported_data_uri_images = False - def __init__(self, app): - # type: (Sphinx) -> None + def __init__(self, app: "Sphinx") -> None: self.srcdir = app.srcdir self.confdir = app.confdir self.outdir = app.outdir @@ -113,20 +111,17 @@ class Builder: self.parallel_ok = False self.finish_tasks = None # type: Any - def set_environment(self, env): - # type: (BuildEnvironment) -> None + def set_environment(self, env: BuildEnvironment) -> None: """Store BuildEnvironment object.""" self.env = env self.env.set_versioning_method(self.versioning_method, self.versioning_compare) - def get_translator_class(self, *args): - # type: (Any) -> Type[nodes.NodeVisitor] + def get_translator_class(self, *args) -> Type[nodes.NodeVisitor]: """Return a class of translator.""" return self.app.registry.get_translator_class(self) - def create_translator(self, *args): - # type: (Any) -> nodes.NodeVisitor + def create_translator(self, *args) -> nodes.NodeVisitor: """Return an instance of translator. This method returns an instance of ``default_translator_class`` by default. @@ -135,15 +130,13 @@ class Builder: return self.app.registry.create_translator(self, *args) # helper methods - def init(self): - # type: () -> None + def init(self) -> None: """Load necessary templates and perform initialization. The default implementation does nothing. """ pass - def create_template_bridge(self): - # type: () -> None + def create_template_bridge(self) -> None: """Return the template bridge configured.""" if self.config.template_bridge: self.templates = import_object(self.config.template_bridge, @@ -152,8 +145,7 @@ class Builder: from sphinx.jinja2glue import BuiltinTemplateLoader self.templates = BuiltinTemplateLoader() - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: """Return the target URI for a document name. *typ* can be used to qualify the link characteristic for individual @@ -161,8 +153,7 @@ class Builder: """ raise NotImplementedError - def get_relative_uri(self, from_, to, typ=None): - # type: (str, str, str) -> str + def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str: """Return a relative URI between two source filenames. May raise environment.NoUri if there's no way to return a sensible URI. @@ -170,8 +161,7 @@ class Builder: return relative_uri(self.get_target_uri(from_), self.get_target_uri(to, typ)) - def get_outdated_docs(self): - # type: () -> Union[str, Iterable[str]] + def get_outdated_docs(self) -> Union[str, Iterable[str]]: """Return an iterable of output files that are outdated, or a string describing what an update build will build. @@ -181,13 +171,11 @@ class Builder: """ raise NotImplementedError - def get_asset_paths(self): - # type: () -> List[str] + def get_asset_paths(self) -> List[str]: """Return list of paths for assets (ex. templates, CSS, etc.).""" return [] - def post_process_images(self, doctree): - # type: (nodes.Node) -> None + def post_process_images(self, doctree: Node) -> None: """Pick the best candidate for all image URIs.""" images = ImageAdapter(self.env) for node in doctree.traverse(nodes.image): @@ -220,13 +208,11 @@ class Builder: # compile po methods - def compile_catalogs(self, catalogs, message): - # type: (Set[CatalogInfo], str) -> None + def compile_catalogs(self, catalogs: Set[CatalogInfo], message: str) -> None: if not self.config.gettext_auto_build: return - def cat2relpath(cat): - # type: (CatalogInfo) -> str + def cat2relpath(cat: CatalogInfo) -> str: return relpath(cat.mo_path, self.env.srcdir).replace(path.sep, SEP) logger.info(bold(__('building [mo]: ')) + message) @@ -235,17 +221,14 @@ class Builder: stringify_func=cat2relpath): catalog.write_mo(self.config.language) - def compile_all_catalogs(self): - # type: () -> None + def compile_all_catalogs(self) -> None: repo = CatalogRepository(self.srcdir, self.config.locale_dirs, self.config.language, self.config.source_encoding) message = __('all of %d po files') % len(list(repo.catalogs)) self.compile_catalogs(set(repo.catalogs), message) - def compile_specific_catalogs(self, specified_files): - # type: (List[str]) -> None - def to_domain(fpath): - # type: (str) -> str + def compile_specific_catalogs(self, specified_files: List[str]) -> None: + def to_domain(fpath: str) -> str: docname = self.env.path2doc(path.abspath(fpath)) if docname: return docname_to_domain(docname, self.config.gettext_compact) @@ -262,8 +245,7 @@ class Builder: message = __('targets for %d po files that are specified') % len(catalogs) self.compile_catalogs(catalogs, message) - def compile_update_catalogs(self): - # type: () -> None + def compile_update_catalogs(self) -> None: repo = CatalogRepository(self.srcdir, self.config.locale_dirs, self.config.language, self.config.source_encoding) catalogs = {c for c in repo.catalogs if c.is_outdated()} @@ -272,13 +254,11 @@ class Builder: # build methods - def build_all(self): - # type: () -> None + def build_all(self) -> None: """Build all source files.""" self.build(None, summary=__('all source files'), method='all') - def build_specific(self, filenames): - # type: (List[str]) -> None + def build_specific(self, filenames: List[str]) -> 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. @@ -306,8 +286,7 @@ class Builder: self.build(to_write, method='specific', summary=__('%d source files given on command line') % len(to_write)) - def build_update(self): - # type: () -> None + def build_update(self) -> None: """Only rebuild what was changed or added since last build.""" to_build = self.get_outdated_docs() if isinstance(to_build, str): @@ -318,8 +297,7 @@ class Builder: summary=__('targets for %d source files that are out of date') % len(to_build)) - def build(self, docnames, summary=None, method='update'): - # type: (Iterable[str], str, str) -> None + def build(self, docnames: Iterable[str], summary: str = None, method: str = 'update') -> None: # NOQA """Main build method. First updates the environment, and then calls :meth:`write`. @@ -387,8 +365,7 @@ class Builder: # wait for all tasks self.finish_tasks.join() - def read(self): - # type: () -> List[str] + def read(self) -> List[str]: """(Re-)read all files new or changed since last update. Store all environment docnames in the canonical format (ie using SEP as @@ -450,8 +427,7 @@ class Builder: return sorted(docnames) - def _read_serial(self, docnames): - # type: (List[str]) -> None + def _read_serial(self, docnames: List[str]) -> None: for docname in status_iterator(docnames, __('reading sources... '), "purple", len(docnames), self.app.verbosity): # remove all inventory entries for that file @@ -459,23 +435,20 @@ class Builder: self.env.clear_doc(docname) self.read_doc(docname) - def _read_parallel(self, docnames, nproc): - # type: (List[str], int) -> None + def _read_parallel(self, docnames: List[str], nproc: int) -> None: # clear all outdated docs at once for docname in docnames: self.events.emit('env-purge-doc', self.env, docname) self.env.clear_doc(docname) - def read_process(docs): - # type: (List[str]) -> bytes + def read_process(docs: List[str]) -> bytes: self.env.app = self.app for docname in docs: self.read_doc(docname) # allow pickling self to send it back return pickle.dumps(self.env, pickle.HIGHEST_PROTOCOL) - def merge(docs, otherenv): - # type: (List[str], bytes) -> None + def merge(docs: List[str], otherenv: bytes) -> None: env = pickle.loads(otherenv) self.env.merge_info_from(docs, env, self.app) @@ -490,8 +463,7 @@ class Builder: logger.info(bold(__('waiting for workers...'))) tasks.join() - def read_doc(self, docname): - # type: (str) -> None + def read_doc(self, docname: str) -> None: """Parse a file and add/update inventory entries for the doctree.""" self.env.prepare_settings(docname) @@ -516,8 +488,7 @@ class Builder: self.write_doctree(docname, doctree) - def write_doctree(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doctree(self, docname: str, doctree: nodes.document) -> None: """Write the doctree to a file.""" # make it picklable doctree.reporter = None @@ -531,8 +502,7 @@ class Builder: with open(doctree_filename, 'wb') as f: pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) - def write(self, build_docnames, updated_docnames, method='update'): - # type: (Iterable[str], Sequence[str], str) -> None + def write(self, build_docnames: Iterable[str], updated_docnames: Sequence[str], method: str = 'update') -> None: # NOQA if build_docnames is None or build_docnames == ['__all__']: # build_all build_docnames = self.env.found_docs @@ -561,8 +531,7 @@ class Builder: else: self._write_serial(sorted(docnames)) - def _write_serial(self, docnames): - # type: (Sequence[str]) -> None + def _write_serial(self, docnames: Sequence[str]) -> None: with logging.pending_warnings(): for docname in status_iterator(docnames, __('writing output... '), "darkgreen", len(docnames), self.app.verbosity): @@ -572,10 +541,8 @@ class Builder: self.write_doc_serialized(docname, doctree) self.write_doc(docname, doctree) - def _write_parallel(self, docnames, nproc): - # type: (Sequence[str], int) -> None - def write_process(docs): - # type: (List[Tuple[str, nodes.document]]) -> None + def _write_parallel(self, docnames: Sequence[str], nproc: int) -> None: + def write_process(docs: List[Tuple[str, nodes.document]]) -> None: self.app.phase = BuildPhase.WRITING for docname, doctree in docs: self.write_doc(docname, doctree) @@ -605,41 +572,35 @@ class Builder: logger.info(bold(__('waiting for workers...'))) tasks.join() - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: """A place where you can add logic before :meth:`write_doc` is run""" raise NotImplementedError - def write_doc(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc(self, docname: str, doctree: nodes.document) -> None: """Where you actually write something to the filesystem.""" raise NotImplementedError - def write_doc_serialized(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc_serialized(self, docname: str, doctree: nodes.document) -> 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 + def finish(self) -> None: """Finish the building process. The default implementation does nothing. """ pass - def cleanup(self): - # type: () -> None + def cleanup(self) -> None: """Cleanup any resources. The default implementation does nothing. """ pass - def get_builder_config(self, option, default): - # type: (str, str) -> Any + def get_builder_config(self, option: str, default: str) -> Any: """Return a builder specific option. This method allows customization of common builder settings by diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py index 140f2748d..75e79936b 100644 --- a/sphinx/builders/_epub_base.py +++ b/sphinx/builders/_epub_base.py @@ -14,9 +14,11 @@ import re import warnings from collections import namedtuple from os import path +from typing import Any, Dict, List, Set, Tuple from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile from docutils import nodes +from docutils.nodes import Element, Node from docutils.utils import smartquotes from sphinx import addnodes @@ -34,10 +36,6 @@ try: except ImportError: Image = None -if False: - # For type annotation - from typing import Any, Dict, List, Set, Tuple # NOQA - logger = logging.getLogger(__name__) @@ -93,8 +91,7 @@ Guide = namedtuple('Guide', ['type', 'title', 'uri']) NavPoint = namedtuple('NavPoint', ['navpoint', 'playorder', 'text', 'refuri', 'children']) -def sphinx_smarty_pants(t, language='en'): - # type: (str, str) -> str +def sphinx_smarty_pants(t: str, language: str = 'en') -> str: t = t.replace('"', '"') t = smartquotes.educateDashesOldSchool(t) t = smartquotes.educateQuotes(t, language) @@ -145,8 +142,7 @@ class EpubBuilder(StandaloneHTMLBuilder): template_dir = "" doctype = "" - def init(self): - # type: () -> None + def init(self) -> None: super().init() # the output files for epub must be .html only self.out_suffix = '.xhtml' @@ -157,17 +153,14 @@ class EpubBuilder(StandaloneHTMLBuilder): self.use_index = self.get_builder_config('use_index', 'epub') self.refnodes = [] # type: List[Dict[str, Any]] - def create_build_info(self): - # type: () -> BuildInfo + def create_build_info(self) -> BuildInfo: return BuildInfo(self.config, self.tags, ['html', 'epub']) - def get_theme_config(self): - # type: () -> Tuple[str, Dict] + def get_theme_config(self) -> Tuple[str, Dict]: return self.config.epub_theme, self.config.epub_theme_options # generic support functions - def make_id(self, name): - # type: (str) -> str + def make_id(self, name: str) -> str: # id_cache is intentionally mutable """Return a unique id for name.""" id = self.id_cache.get(name) @@ -176,8 +169,7 @@ class EpubBuilder(StandaloneHTMLBuilder): self.id_cache[name] = id return id - def esc(self, name): - # type: (str) -> str + def esc(self, name: str) -> str: """Replace all characters not allowed in text an attribute values.""" warnings.warn( '%s.esc() is deprecated. Use html.escape() instead.' % self.__class__.__name__, @@ -189,8 +181,7 @@ class EpubBuilder(StandaloneHTMLBuilder): name = name.replace('\'', ''') return name - def get_refnodes(self, doctree, result): - # type: (nodes.Node, List[Dict[str, Any]]) -> List[Dict[str, Any]] + def get_refnodes(self, doctree: Node, result: List[Dict[str, Any]]) -> List[Dict[str, Any]]: # NOQA """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? @@ -213,8 +204,7 @@ class EpubBuilder(StandaloneHTMLBuilder): result = self.get_refnodes(elem, result) return result - def check_refnodes(self, nodes): - # type: (List[Dict[str, Any]]) -> None + def check_refnodes(self, nodes: List[Dict[str, Any]]) -> None: appeared = set() # type: Set[str] for node in nodes: if node['refuri'] in appeared: @@ -222,8 +212,7 @@ class EpubBuilder(StandaloneHTMLBuilder): else: appeared.add(node['refuri']) - def get_toc(self): - # type: () -> None + def get_toc(self) -> None: """Get the total table of contents, containing the master_doc and pre and post files not managed by sphinx. """ @@ -238,8 +227,7 @@ class EpubBuilder(StandaloneHTMLBuilder): item['refuri'] = master_dir + item['refuri'] self.toc_add_files(self.refnodes) - def toc_add_files(self, refnodes): - # type: (List[Dict[str, Any]]) -> None + def toc_add_files(self, refnodes: List[Dict[str, Any]]) -> None: """Add the master_doc, pre and post files to a list of refnodes. """ refnodes.insert(0, { @@ -261,13 +249,11 @@ class EpubBuilder(StandaloneHTMLBuilder): 'text': ssp(html.escape(text)) }) - def fix_fragment(self, prefix, fragment): - # type: (str, str) -> str + def fix_fragment(self, prefix: str, fragment: str) -> str: """Return a href/id attribute with colons replaced by hyphens.""" return prefix + fragment.replace(':', '-') - def fix_ids(self, tree): - # type: (nodes.document) -> None + def fix_ids(self, tree: nodes.document) -> None: """Replace colons with hyphens in href and id attributes. Some readers crash because they interpret the part as a @@ -286,7 +272,7 @@ class EpubBuilder(StandaloneHTMLBuilder): if ':' in node_id: target['ids'][i] = self.fix_fragment('', node_id) - next_node = target.next_node(siblings=True) # type: nodes.Node + next_node = target.next_node(siblings=True) # type: Node if isinstance(next_node, nodes.Element): for i, node_id in enumerate(next_node['ids']): if ':' in node_id: @@ -299,20 +285,17 @@ class EpubBuilder(StandaloneHTMLBuilder): newids.append(self.fix_fragment('', id)) desc_signature.attributes['ids'] = newids - def add_visible_links(self, tree, show_urls='inline'): - # type: (nodes.document, str) -> None + def add_visible_links(self, tree: nodes.document, show_urls: str = 'inline') -> None: """Add visible link targets for external links""" - def make_footnote_ref(doc, label): - # type: (nodes.document, str) -> nodes.footnote_reference + def make_footnote_ref(doc: nodes.document, label: str) -> nodes.footnote_reference: """Create a footnote_reference node with children""" footnote_ref = nodes.footnote_reference('[#]_') footnote_ref.append(nodes.Text(label)) doc.note_autofootnote_ref(footnote_ref) return footnote_ref - def make_footnote(doc, label, uri): - # type: (nodes.document, str, str) -> nodes.footnote + def make_footnote(doc: nodes.document, label: str, uri: str) -> nodes.footnote: """Create a footnote node with children""" footnote = nodes.footnote(uri) para = nodes.paragraph() @@ -322,8 +305,7 @@ class EpubBuilder(StandaloneHTMLBuilder): doc.note_autofootnote(footnote) return footnote - def footnote_spot(tree): - # type: (nodes.document) -> Tuple[nodes.Element, int] + def footnote_spot(tree: nodes.document) -> Tuple[Element, int]: """Find or create a spot to place footnotes. The function returns the tuple (parent, index).""" @@ -371,8 +353,7 @@ class EpubBuilder(StandaloneHTMLBuilder): footnote.add_backref(footnote_ref['ids'][0]) fn_idx += 1 - def write_doc(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc(self, docname: str, doctree: nodes.document) -> None: """Write one document file. This method is overwritten in order to fix fragment identifiers @@ -382,8 +363,7 @@ class EpubBuilder(StandaloneHTMLBuilder): self.add_visible_links(doctree, self.config.epub_show_urls) super().write_doc(docname, doctree) - def fix_genindex(self, tree): - # type: (List[Tuple[str, List[Tuple[str, Any]]]]) -> None + def fix_genindex(self, tree: List[Tuple[str, List[Tuple[str, Any]]]]) -> None: """Fix href attributes for genindex pages.""" # XXX: modifies tree inline # Logic modeled from themes/basic/genindex.html @@ -401,14 +381,12 @@ class EpubBuilder(StandaloneHTMLBuilder): subentrylinks[i] = (ismain, self.fix_fragment(m.group(1), m.group(2))) - def is_vector_graphics(self, filename): - # type: (str) -> bool + def is_vector_graphics(self, filename: str) -> 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 + def copy_image_files_pil(self) -> None: """Copy images using Pillow, the Python Imaging Libary. The method tries to read and write the files with Pillow, converting the format and resizing the image if necessary/possible. @@ -447,8 +425,7 @@ class EpubBuilder(StandaloneHTMLBuilder): logger.warning(__('cannot write image file %r: %s'), path.join(self.srcdir, src), err) - def copy_image_files(self): - # type: () -> None + def copy_image_files(self) -> None: """Copy image files to destination directory. This overwritten method can use Pillow to convert image files. """ @@ -462,13 +439,11 @@ class EpubBuilder(StandaloneHTMLBuilder): else: super().copy_image_files() - def copy_download_files(self): - # type: () -> None + def copy_download_files(self) -> None: pass - def handle_page(self, pagename, addctx, templatename='page.html', - outfilename=None, event_arg=None): - # type: (str, Dict, str, str, Any) -> None + def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html', + outfilename: str = None, event_arg: Any = None) -> None: """Create a rendered page. This method is overwritten for genindex pages in order to fix href link @@ -481,8 +456,7 @@ class EpubBuilder(StandaloneHTMLBuilder): addctx['doctype'] = self.doctype super().handle_page(pagename, addctx, templatename, outfilename, event_arg) - def build_mimetype(self, outdir=None, outname='mimetype'): - # type: (str, str) -> None + def build_mimetype(self, outdir: str = None, outname: str = 'mimetype') -> None: """Write the metainfo file mimetype.""" if outdir: warnings.warn('The arguments of EpubBuilder.build_mimetype() is deprecated.', @@ -494,8 +468,7 @@ class EpubBuilder(StandaloneHTMLBuilder): copy_asset_file(path.join(self.template_dir, 'mimetype'), path.join(outdir, outname)) - def build_container(self, outdir=None, outname='META-INF/container.xml'): - # type: (str, str) -> None + def build_container(self, outdir: str = None, outname: str = 'META-INF/container.xml') -> None: # NOQA """Write the metainfo file META-INF/container.xml.""" if outdir: warnings.warn('The arguments of EpubBuilder.build_container() is deprecated.', @@ -508,8 +481,7 @@ class EpubBuilder(StandaloneHTMLBuilder): ensuredir(path.dirname(filename)) copy_asset_file(path.join(self.template_dir, 'container.xml'), filename) - def content_metadata(self): - # type: () -> Dict[str, Any] + def content_metadata(self) -> Dict[str, Any]: """Create a dictionary with all metadata for the content.opf file properly escaped. """ @@ -528,8 +500,7 @@ class EpubBuilder(StandaloneHTMLBuilder): metadata['guides'] = [] return metadata - def build_content(self, outdir=None, outname='content.opf'): - # type: (str, str) -> None + def build_content(self, outdir: str = None, outname: str = 'content.opf') -> None: """Write the metainfo file content.opf It contains bibliographic data, a file list and the spine (the reading order). """ @@ -648,8 +619,7 @@ class EpubBuilder(StandaloneHTMLBuilder): path.join(outdir, outname), metadata) - def new_navpoint(self, node, level, incr=True): - # type: (Dict[str, Any], int, bool) -> NavPoint + def new_navpoint(self, node: Dict[str, Any], level: int, incr: bool = True) -> NavPoint: """Create a new entry in the toc from the node at given level.""" # XXX Modifies the node if incr: @@ -658,8 +628,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return NavPoint('navPoint%d' % self.tocid, self.playorder, node['text'], node['refuri'], []) - def build_navpoints(self, nodes): - # type: (List[Dict[str, Any]]) -> List[NavPoint] + def build_navpoints(self, nodes: List[Dict[str, Any]]) -> List[NavPoint]: """Create the toc navigation structure. Subelements of a node are nested inside the navpoint. For nested nodes @@ -703,8 +672,7 @@ class EpubBuilder(StandaloneHTMLBuilder): return navstack[0].children - def toc_metadata(self, level, navpoints): - # type: (int, List[NavPoint]) -> Dict[str, Any] + def toc_metadata(self, level: int, navpoints: List[NavPoint]) -> Dict[str, Any]: """Create a dictionary with all metadata for the toc.ncx file properly escaped. """ @@ -715,8 +683,7 @@ class EpubBuilder(StandaloneHTMLBuilder): metadata['navpoints'] = navpoints return metadata - def build_toc(self, outdir=None, outname='toc.ncx'): - # type: (str, str) -> None + def build_toc(self, outdir: str = None, outname: str = 'toc.ncx') -> None: """Write the metainfo file toc.ncx.""" if outdir: warnings.warn('The arguments of EpubBuilder.build_toc() is deprecated.', @@ -743,8 +710,7 @@ class EpubBuilder(StandaloneHTMLBuilder): path.join(outdir, outname), self.toc_metadata(level, navpoints)) - def build_epub(self, outdir=None, outname=None): - # type: (str, str) -> None + def build_epub(self, outdir: str = None, outname: str = None) -> None: """Write the epub file. It is a zip file with the mimetype file stored uncompressed as the first diff --git a/sphinx/builders/applehelp.py b/sphinx/builders/applehelp.py index 0ee50ff56..d7dd336ca 100644 --- a/sphinx/builders/applehelp.py +++ b/sphinx/builders/applehelp.py @@ -9,6 +9,7 @@ """ import warnings +from typing import Any, Dict from sphinxcontrib.applehelp import ( AppleHelpCodeSigningFailed, @@ -16,13 +17,9 @@ from sphinxcontrib.applehelp import ( AppleHelpBuilder, ) +from sphinx.application import Sphinx from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias -if False: - # For type annotation - from typing import Any, Dict # NOQA - from sphinx.application import Sphinx # NOQA - deprecated_alias('sphinx.builders.applehelp', { @@ -33,8 +30,7 @@ deprecated_alias('sphinx.builders.applehelp', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: warnings.warn('sphinx.builders.applehelp has been moved to sphinxcontrib-applehelp.', RemovedInSphinx40Warning) app.setup_extension('sphinxcontrib.applehelp') diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index 3b169e493..a42215fad 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -10,9 +10,11 @@ import html from os import path +from typing import Any, Dict, List, Tuple from typing import cast from sphinx import package_dir +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.domains.changeset import ChangeSetDomain from sphinx.locale import _, __ @@ -22,11 +24,6 @@ from sphinx.util.console import bold # type: ignore from sphinx.util.fileutil import copy_asset_file from sphinx.util.osutil import ensuredir, os_path -if False: - # For type annotation - from typing import Any, Dict, List, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - logger = logging.getLogger(__name__) @@ -38,15 +35,13 @@ class ChangesBuilder(Builder): name = 'changes' epilog = __('The overview file is in %(outdir)s.') - def init(self): - # type: () -> None + def init(self) -> None: self.create_template_bridge() theme_factory = HTMLThemeFactory(self.app) self.theme = theme_factory.create('default') self.templates.init(self, self.theme) - def get_outdated_docs(self): - # type: () -> str + def get_outdated_docs(self) -> str: return self.outdir typemap = { @@ -55,8 +50,7 @@ class ChangesBuilder(Builder): 'deprecated': 'deprecated', } - def write(self, *ignored): - # type: (Any) -> None + def write(self, *ignored) -> None: version = self.config.version domain = cast(ChangeSetDomain, self.env.get_domain('changeset')) libchanges = {} # type: Dict[str, List[Tuple[str, str, int]]] @@ -121,8 +115,7 @@ class ChangesBuilder(Builder): '.. versionchanged:: %s' % version, '.. deprecated:: %s' % version] - def hl(no, line): - # type: (int, str) -> str + def hl(no: int, line: str) -> str: line = '<a name="L%s"> </a>' % no + html.escape(line) for x in hltext: if x in line: @@ -155,21 +148,18 @@ class ChangesBuilder(Builder): copy_asset_file(path.join(package_dir, 'themes', 'basic', 'static', 'basic.css'), self.outdir) - def hl(self, text, version): - # type: (str, str) -> str + def hl(self, text: str, version: str) -> str: text = html.escape(text) for directive in ['versionchanged', 'versionadded', 'deprecated']: text = text.replace('.. %s:: %s' % (directive, version), '<b>.. %s:: %s</b>' % (directive, version)) return text - def finish(self): - # type: () -> None + def finish(self) -> None: pass -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(ChangesBuilder) return { diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py index 2306ddee2..17e861777 100644 --- a/sphinx/builders/devhelp.py +++ b/sphinx/builders/devhelp.py @@ -11,18 +11,14 @@ """ import warnings +from typing import Any, Dict from sphinxcontrib.devhelp import DevhelpBuilder +from sphinx.application import Sphinx from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias -if False: - # For type annotation - from typing import Any, Dict # NOQA - from sphinx.application import Sphinx # NOQA - - deprecated_alias('sphinx.builders.devhelp', { 'DevhelpBuilder': DevhelpBuilder, @@ -30,8 +26,7 @@ deprecated_alias('sphinx.builders.devhelp', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: warnings.warn('sphinx.builders.devhelp has been moved to sphinxcontrib-devhelp.', RemovedInSphinx40Warning) app.setup_extension('sphinxcontrib.devhelp') diff --git a/sphinx/builders/dirhtml.py b/sphinx/builders/dirhtml.py index d5d61c273..40ec7b11f 100644 --- a/sphinx/builders/dirhtml.py +++ b/sphinx/builders/dirhtml.py @@ -9,17 +9,14 @@ """ from os import path +from typing import Any, Dict, Set +from sphinx.application import Sphinx from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias from sphinx.util import logging from sphinx.util.osutil import SEP, os_path -if False: - # For type annotation - from typing import Any, Dict, Set # NOQA - from sphinx.application import Sphinx # NOQA - logger = logging.getLogger(__name__) @@ -31,16 +28,14 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder): """ name = 'dirhtml' - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: if docname == 'index': return '' if docname.endswith(SEP + 'index'): return docname[:-5] # up to sep return docname + SEP - def get_outfilename(self, pagename): - # type: (str) -> str + def get_outfilename(self, pagename: str) -> str: if pagename == 'index' or pagename.endswith(SEP + 'index'): outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) @@ -50,8 +45,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder): return outfilename - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: super().prepare_writing(docnames) self.globalcontext['no_search_suffix'] = True @@ -64,8 +58,7 @@ deprecated_alias('sphinx.builders.html', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.setup_extension('sphinx.builders.html') app.add_builder(DirectoryHTMLBuilder) diff --git a/sphinx/builders/dummy.py b/sphinx/builders/dummy.py index d5ae94a82..33d2506ac 100644 --- a/sphinx/builders/dummy.py +++ b/sphinx/builders/dummy.py @@ -8,16 +8,14 @@ :license: BSD, see LICENSE for details. """ +from typing import Any, Dict, Set +from docutils.nodes import Node + +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.locale import __ -if False: - # For type annotation - from typing import Any, Dict, Set # NOQA - from docutils import nodes # NOQA - from sphinx.application import Sphinx # NOQA - class DummyBuilder(Builder): name = 'dummy' @@ -25,33 +23,26 @@ class DummyBuilder(Builder): allow_parallel = True - def init(self): - # type: () -> None + def init(self) -> None: pass - def get_outdated_docs(self): - # type: () -> Set[str] + def get_outdated_docs(self) -> Set[str]: return self.env.found_docs - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return '' - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: pass - def write_doc(self, docname, doctree): - # type: (str, nodes.Node) -> None + def write_doc(self, docname: str, doctree: Node) -> None: pass - def finish(self): - # type: () -> None + def finish(self) -> None: pass -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(DummyBuilder) return { diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py index 9b3f58d7a..5d7121fe6 100644 --- a/sphinx/builders/epub3.py +++ b/sphinx/builders/epub3.py @@ -13,10 +13,12 @@ import html import warnings from collections import namedtuple from os import path +from typing import Any, Dict, List, Set, Tuple from sphinx import package_dir +from sphinx.application import Sphinx from sphinx.builders import _epub_base -from sphinx.config import ENUM +from sphinx.config import Config, ENUM from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.locale import __ from sphinx.util import logging, xmlname_checker @@ -24,12 +26,6 @@ from sphinx.util.fileutil import copy_asset_file from sphinx.util.i18n import format_date from sphinx.util.osutil import make_filename -if False: - # For type annotation - from typing import Any, Dict, List, Set, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - logger = logging.getLogger(__name__) @@ -75,8 +71,7 @@ class Epub3Builder(_epub_base.EpubBuilder): use_meta_charset = True # Finish by building the epub file - def handle_finish(self): - # type: () -> None + def handle_finish(self) -> None: """Create the metainfo files and finally the epub.""" self.get_toc() self.build_mimetype() @@ -86,13 +81,11 @@ class Epub3Builder(_epub_base.EpubBuilder): self.build_toc() self.build_epub() - def validate_config_value(self): - # type: () -> None + def validate_config_value(self) -> None: warnings.warn('Epub3Builder.validate_config_value() is deprecated.', RemovedInSphinx40Warning, stacklevel=2) - def content_metadata(self): - # type: () -> Dict + def content_metadata(self) -> Dict: """Create a dictionary with all metadata for the content.opf file properly escaped. """ @@ -108,8 +101,7 @@ class Epub3Builder(_epub_base.EpubBuilder): metadata['epub_version'] = self.config.epub_version return metadata - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: super().prepare_writing(docnames) writing_mode = self.config.epub_writing_mode @@ -118,8 +110,7 @@ class Epub3Builder(_epub_base.EpubBuilder): self.globalcontext['use_meta_charset'] = self.use_meta_charset self.globalcontext['skip_ua_compatible'] = True - def build_navlist(self, navnodes): - # type: (List[Dict[str, Any]]) -> List[NavPoint] + def build_navlist(self, navnodes: List[Dict[str, Any]]) -> List[NavPoint]: """Create the toc navigation structure. This method is almost same as build_navpoints method in epub.py. @@ -161,8 +152,7 @@ class Epub3Builder(_epub_base.EpubBuilder): return navstack[0].children - def navigation_doc_metadata(self, navlist): - # type: (List[NavPoint]) -> Dict + def navigation_doc_metadata(self, navlist: List[NavPoint]) -> Dict: """Create a dictionary with all metadata for the nav.xhtml file properly escaped. """ @@ -172,8 +162,7 @@ class Epub3Builder(_epub_base.EpubBuilder): metadata['navlist'] = navlist return metadata - def build_navigation_doc(self, outdir=None, outname='nav.xhtml'): - # type: (str, str) -> None + def build_navigation_doc(self, outdir: str = None, outname: str = 'nav.xhtml') -> None: """Write the metainfo file nav.xhtml.""" if outdir: warnings.warn('The arguments of Epub3Builder.build_navigation_doc() ' @@ -202,8 +191,7 @@ class Epub3Builder(_epub_base.EpubBuilder): self.files.append(outname) -def validate_config_values(app): - # type: (Sphinx) -> None +def validate_config_values(app: Sphinx) -> None: if app.builder.name != 'epub': return @@ -242,8 +230,7 @@ def validate_config_values(app): logger.warning(__('conf value "version" should not be empty for EPUB3')) -def convert_epub_css_files(app, config): - # type: (Sphinx, Config) -> None +def convert_epub_css_files(app: Sphinx, config: Config) -> None: """This converts string styled epub_css_files to tuple styled one.""" epub_css_files = [] # type: List[Tuple[str, Dict]] for entry in config.epub_css_files: @@ -260,8 +247,7 @@ def convert_epub_css_files(app, config): config.epub_css_files = epub_css_files # type: ignore -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(Epub3Builder) # config values diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py index f26b831da..2beb4a5ce 100644 --- a/sphinx/builders/gettext.py +++ b/sphinx/builders/gettext.py @@ -14,27 +14,25 @@ from datetime import datetime, tzinfo, timedelta from io import StringIO from os import path, walk, getenv from time import time +from typing import Any, DefaultDict, Dict, Iterable, List, Set, Tuple, Union from uuid import uuid4 +from docutils import nodes +from docutils.nodes import Element + from sphinx import addnodes +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.domains.python import pairindextypes from sphinx.errors import ThemeError from sphinx.locale import __ from sphinx.util import split_index_msg, logging, status_iterator from sphinx.util.console import bold # type: ignore -from sphinx.util.i18n import docname_to_domain +from sphinx.util.i18n import CatalogInfo, docname_to_domain from sphinx.util.nodes import extract_messages, traverse_translatable_index from sphinx.util.osutil import relpath, ensuredir, canon_path from sphinx.util.tags import Tags -if False: - # For type annotation - from typing import Any, DefaultDict, Dict, Iterable, List, Set, Tuple, Union # NOQA - from docutils import nodes # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.util.i18n import CatalogInfo # NOQA - logger = logging.getLogger(__name__) @@ -63,15 +61,13 @@ msgstr "" class Catalog: """Catalog of translatable messages.""" - def __init__(self): - # type: () -> None + def __init__(self) -> None: self.messages = [] # type: List[str] # retain insertion order, a la OrderedDict self.metadata = OrderedDict() # type: Dict[str, List[Tuple[str, int, str]]] # msgid -> file, line, uid - def add(self, msg, origin): - # type: (str, Union[nodes.Element, MsgOrigin]) -> None + def add(self, msg: str, origin: Union[Element, "MsgOrigin"]) -> None: if not hasattr(origin, 'uid'): # Nodes that are replicated like todo don't have a uid, # however i18n is also unnecessary. @@ -87,8 +83,7 @@ class MsgOrigin: Origin holder for Catalog message origin. """ - def __init__(self, source, line): - # type: (str, int) -> None + def __init__(self, source: str, line: int) -> None: self.source = source self.line = line self.uid = uuid4().hex @@ -100,8 +95,7 @@ class I18nTags(Tags): To translate all text inside of only nodes, this class always returns True value even if no tags are defined. """ - def eval_condition(self, condition): - # type: (Any) -> bool + def eval_condition(self, condition: Any) -> bool: return True @@ -115,32 +109,26 @@ class I18nBuilder(Builder): # be set by `gettext_uuid` use_message_catalog = False - def init(self): - # type: () -> None + def init(self) -> None: super().init() self.env.set_versioning_method(self.versioning_method, self.env.config.gettext_uuid) self.tags = I18nTags() self.catalogs = defaultdict(Catalog) # type: DefaultDict[str, Catalog] - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return '' - def get_outdated_docs(self): - # type: () -> Set[str] + def get_outdated_docs(self) -> Set[str]: return self.env.found_docs - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: return - def compile_catalogs(self, catalogs, message): - # type: (Set[CatalogInfo], str) -> None + def compile_catalogs(self, catalogs: Set[CatalogInfo], message: str) -> None: return - def write_doc(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc(self, docname: str, doctree: nodes.document) -> None: catalog = self.catalogs[docname_to_domain(docname, self.config.gettext_compact)] for toctree in self.env.tocs[docname].traverse(addnodes.toctree): @@ -176,26 +164,21 @@ if source_date_epoch is not None: class LocalTimeZone(tzinfo): - - def __init__(self, *args, **kw): - # type: (Any, Any) -> None + def __init__(self, *args, **kw) -> None: super().__init__(*args, **kw) # type: ignore self.tzdelta = tzdelta - def utcoffset(self, dt): - # type: (datetime) -> timedelta + def utcoffset(self, dt: datetime) -> timedelta: return self.tzdelta - def dst(self, dt): - # type: (datetime) -> timedelta + def dst(self, dt: datetime) -> timedelta: return timedelta(0) ltz = LocalTimeZone() -def should_write(filepath, new_content): - # type: (str, str) -> bool +def should_write(filepath: str, new_content: str): if not path.exists(filepath): return True try: @@ -220,14 +203,12 @@ class MessageCatalogBuilder(I18nBuilder): name = 'gettext' epilog = __('The message catalogs are in %(outdir)s.') - def init(self): - # type: () -> None + def init(self) -> None: super().init() self.create_template_bridge() self.templates.init(self) - def _collect_templates(self): - # type: () -> Set[str] + def _collect_templates(self) -> Set[str]: template_files = set() for template_path in self.config.templates_path: tmpl_abs_path = path.join(self.app.srcdir, template_path) @@ -238,8 +219,7 @@ class MessageCatalogBuilder(I18nBuilder): template_files.add(filename) return template_files - def _extract_from_template(self): - # type: () -> None + def _extract_from_template(self) -> None: files = list(self._collect_templates()) files.sort() logger.info(bold(__('building [%s]: ') % self.name), nonl=True) @@ -258,13 +238,11 @@ class MessageCatalogBuilder(I18nBuilder): except Exception as exc: raise ThemeError('%s: %r' % (template, exc)) - def build(self, docnames, summary=None, method='update'): - # type: (Iterable[str], str, str) -> None + def build(self, docnames: Iterable[str], summary: str = None, method: str = 'update') -> None: # NOQA self._extract_from_template() super().build(docnames, summary, method) - def finish(self): - # type: () -> None + def finish(self) -> None: super().finish() data = { 'version': self.config.version, @@ -310,8 +288,7 @@ class MessageCatalogBuilder(I18nBuilder): pofile.write(content) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, 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 504bbc598..1fd9e6cac 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -15,16 +15,21 @@ import sys import warnings from hashlib import md5 from os import path +from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Type, Tuple from docutils import nodes from docutils.core import publish_parts from docutils.frontend import OptionParser from docutils.io import DocTreeInput, StringOutput +from docutils.nodes import Node from docutils.utils import relative_path from sphinx import package_dir, __display_version__ +from sphinx.application import Sphinx from sphinx.builders import Builder +from sphinx.config import Config from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning +from sphinx.domains import Domain, Index, IndexEntry from sphinx.environment.adapters.asset import ImageAdapter from sphinx.environment.adapters.indexentries import IndexEntries from sphinx.environment.adapters.toctree import TocTree @@ -41,16 +46,9 @@ from sphinx.util.i18n import format_date from sphinx.util.inventory import InventoryFile from sphinx.util.matching import patmatch, Matcher, DOTFILES from sphinx.util.osutil import os_path, relative_uri, ensuredir, movefile, copyfile +from sphinx.util.tags import Tags from sphinx.writers.html import HTMLWriter, HTMLTranslator -if False: - # For type annotation - from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Type, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - from sphinx.domains import Domain, Index, IndexEntry # NOQA - from sphinx.util.tags import Tags # NOQA - # HTML5 Writer is avialable or not if is_html5_writer_available(): from sphinx.writers.html5 import HTML5Translator @@ -65,8 +63,7 @@ logger = logging.getLogger(__name__) return_codes_re = re.compile('[\r\n]+') -def get_stable_hash(obj): - # type: (Any) -> str +def get_stable_hash(obj: Any) -> str: """ 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 @@ -89,8 +86,7 @@ class Stylesheet(str): attributes = None # type: Dict[str, str] filename = None # type: str - def __new__(cls, filename, *args, **attributes): - # type: (str, str, str) -> None + def __new__(cls, filename: str, *args: str, **attributes: str) -> None: self = str.__new__(cls, filename) # type: ignore self.filename = filename self.attributes = attributes @@ -105,23 +101,20 @@ class Stylesheet(str): class JSContainer(list): """The container for JavaScript scripts.""" - def insert(self, index, obj): - # type: (int, str) -> None + def insert(self, index: int, obj: str) -> None: warnings.warn('To modify script_files in the theme is deprecated. ' 'Please insert a <script> tag directly in your theme instead.', RemovedInSphinx30Warning, stacklevel=3) super().insert(index, obj) - def extend(self, other): # type: ignore - # type: (List[str]) -> None + def extend(self, other: List[str]) -> None: # type: ignore warnings.warn('To modify script_files in the theme is deprecated. ' 'Please insert a <script> tag directly in your theme instead.', RemovedInSphinx30Warning, stacklevel=3) for item in other: self.append(item) - def __iadd__(self, other): # type: ignore - # type: (List[str]) -> JSContainer + def __iadd__(self, other: List[str]) -> "JSContainer": # type: ignore warnings.warn('To modify script_files in the theme is deprecated. ' 'Please insert a <script> tag directly in your theme instead.', RemovedInSphinx30Warning, stacklevel=3) @@ -129,8 +122,7 @@ class JSContainer(list): self.append(item) return self - def __add__(self, other): - # type: (List[str]) -> JSContainer + def __add__(self, other: List[str]) -> "JSContainer": ret = JSContainer(self) ret += other return ret @@ -146,8 +138,7 @@ class JavaScript(str): attributes = None # type: Dict[str, str] filename = None # type: str - def __new__(cls, filename, **attributes): - # type: (str, **str) -> None + def __new__(cls, filename: str, **attributes: str) -> None: self = str.__new__(cls, filename) # type: ignore self.filename = filename self.attributes = attributes @@ -164,8 +155,7 @@ class BuildInfo: """ @classmethod - def load(cls, f): - # type: (IO) -> BuildInfo + def load(cls, f: IO) -> "BuildInfo": try: lines = f.readlines() assert lines[0].rstrip() == '# Sphinx build info version 1' @@ -179,8 +169,7 @@ class BuildInfo: except Exception as exc: raise ValueError(__('build info file is broken: %r') % exc) - def __init__(self, config=None, tags=None, config_categories=[]): - # type: (Config, Tags, List[str]) -> None + def __init__(self, config: Config = None, tags: Tags = None, config_categories: List[str] = []) -> None: # NOQA self.config_hash = '' self.tags_hash = '' @@ -191,13 +180,11 @@ class BuildInfo: if tags: self.tags_hash = get_stable_hash(sorted(tags)) - def __eq__(self, other): # type: ignore - # type: (BuildInfo) -> bool + def __eq__(self, other: "BuildInfo") -> bool: # type: ignore return (self.config_hash == other.config_hash and self.tags_hash == other.tags_hash) - def dump(self, f): - # type: (IO) -> None + def dump(self, f: IO) -> None: f.write('# Sphinx build info version 1\n' '# This file hashes the configuration used when building these files.' ' When it is not found, a full rebuild will be done.\n' @@ -237,8 +224,7 @@ class StandaloneHTMLBuilder(Builder): imgpath = None # type: str domain_indices = [] # type: List[Tuple[str, Type[Index], List[Tuple[str, List[IndexEntry]]], bool]] # NOQA - def __init__(self, app): - # type: (Sphinx) -> None + def __init__(self, app: Sphinx) -> None: super().__init__(app) # CSS files @@ -247,8 +233,7 @@ class StandaloneHTMLBuilder(Builder): # JS files self.script_files = JSContainer() # type: List[JavaScript] - def init(self): - # type: () -> None + def init(self) -> None: self.build_info = self.create_build_info() # basename of images directory self.imagedir = '_images' @@ -274,12 +259,10 @@ class StandaloneHTMLBuilder(Builder): self.use_index = self.get_builder_config('use_index', 'html') - def create_build_info(self): - # type: () -> BuildInfo + def create_build_info(self) -> BuildInfo: return BuildInfo(self.config, self.tags, ['html']) - def _get_translations_js(self): - # type: () -> str + def _get_translations_js(self) -> str: candidates = [path.join(dir, self.config.language, 'LC_MESSAGES', 'sphinx.js') for dir in self.config.locale_dirs] + \ @@ -293,12 +276,10 @@ class StandaloneHTMLBuilder(Builder): return jsfile return None - def get_theme_config(self): - # type: () -> Tuple[str, Dict] + def get_theme_config(self) -> Tuple[str, Dict]: return self.config.html_theme, self.config.html_theme_options - def init_templates(self): - # type: () -> None + def init_templates(self) -> None: theme_factory = HTMLThemeFactory(self.app) themename, themeoptions = self.get_theme_config() self.theme = theme_factory.create(themename) @@ -306,8 +287,7 @@ class StandaloneHTMLBuilder(Builder): self.create_template_bridge() self.templates.init(self, self.theme) - def init_highlighter(self): - # type: () -> None + def init_highlighter(self) -> None: # determine Pygments style and create the highlighter if self.config.pygments_style is not None: style = self.config.pygments_style @@ -317,23 +297,20 @@ class StandaloneHTMLBuilder(Builder): style = 'sphinx' self.highlighter = PygmentsBridge('html', style) - def init_css_files(self): - # type: () -> None + def init_css_files(self) -> None: for filename, attrs in self.app.registry.css_files: self.add_css_file(filename, **attrs) for filename, attrs in self.get_builder_config('css_files', 'html'): self.add_css_file(filename, **attrs) - def add_css_file(self, filename, **kwargs): - # type: (str, **str) -> None + def add_css_file(self, filename: str, **kwargs: str) -> None: if '://' not in filename: filename = posixpath.join('_static', filename) self.css_files.append(Stylesheet(filename, **kwargs)) # type: ignore - def init_js_files(self): - # type: () -> None + def init_js_files(self) -> None: self.add_js_file('jquery.js') self.add_js_file('underscore.js') self.add_js_file('doctools.js') @@ -348,24 +325,21 @@ class StandaloneHTMLBuilder(Builder): if self.config.language and self._get_translations_js(): self.add_js_file('translations.js') - def add_js_file(self, filename, **kwargs): - # type: (str, **str) -> None + def add_js_file(self, filename: str, **kwargs: str) -> None: if filename and '://' not in filename: filename = posixpath.join('_static', filename) self.script_files.append(JavaScript(filename, **kwargs)) @property - def default_translator_class(self): # type: ignore - # type: () -> Type[nodes.NodeVisitor] + def default_translator_class(self) -> Type[nodes.NodeVisitor]: # type: ignore if not html5_ready or self.config.html4_writer: return HTMLTranslator else: return HTML5Translator @property - def math_renderer_name(self): - # type: () -> str + def math_renderer_name(self) -> str: name = self.get_builder_config('math_renderer', 'html') if name is not None: # use given name @@ -384,8 +358,7 @@ class StandaloneHTMLBuilder(Builder): # many math_renderers are registered. can't choose automatically! return None - def get_outdated_docs(self): - # type: () -> Iterator[str] + def get_outdated_docs(self) -> Iterator[str]: try: with open(path.join(self.outdir, '.buildinfo')) as fp: buildinfo = BuildInfo.load(fp) @@ -421,12 +394,10 @@ class StandaloneHTMLBuilder(Builder): # source doesn't exist anymore pass - def get_asset_paths(self): - # type: () -> List[str] + def get_asset_paths(self) -> List[str]: return self.config.html_extra_path + self.config.html_static_path - def render_partial(self, node): - # type: (nodes.Node) -> Dict[str, str] + def render_partial(self, node: Node) -> Dict[str, str]: """Utility: Render a lone doctree node.""" if node is None: return {'fragment': ''} @@ -440,8 +411,7 @@ class StandaloneHTMLBuilder(Builder): settings_overrides={'output_encoding': 'unicode'}, source=doc) - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: # create the search indexer self.indexer = None if self.search: @@ -550,8 +520,7 @@ class StandaloneHTMLBuilder(Builder): self.theme.get_options(self.theme_options).items()) self.globalcontext.update(self.config.html_context) - def get_doc_context(self, docname, body, metatags): - # type: (str, str, str) -> Dict[str, Any] + def get_doc_context(self, docname: str, body: str, metatags: str) -> Dict[str, Any]: """Collect items for the template context of a page.""" # find out relations prev = next = None @@ -631,8 +600,7 @@ class StandaloneHTMLBuilder(Builder): 'page_source_suffix': source_suffix, } - def write_doc(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc(self, docname: str, doctree: nodes.document) -> None: destination = StringOutput(encoding='utf-8') doctree.settings = self.docsettings @@ -649,16 +617,14 @@ class StandaloneHTMLBuilder(Builder): ctx = self.get_doc_context(docname, body, metatags) self.handle_page(docname, ctx, event_arg=doctree) - def write_doc_serialized(self, docname, doctree): - # type: (str, nodes.document) -> None + def write_doc_serialized(self, docname: str, doctree: nodes.document) -> None: self.imgpath = relative_uri(self.get_target_uri(docname), self.imagedir) self.post_process_images(doctree) title_node = self.env.longtitles.get(docname) title = title_node and self.render_partial(title_node)['title'] or '' self.index_page(docname, doctree, title) - def finish(self): - # type: () -> None + def finish(self) -> 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) @@ -670,8 +636,7 @@ class StandaloneHTMLBuilder(Builder): # dump the search index self.handle_finish() - def gen_indices(self): - # type: () -> None + def gen_indices(self) -> None: logger.info(bold(__('generating indices...')), nonl=True) # the global general index @@ -683,8 +648,7 @@ class StandaloneHTMLBuilder(Builder): logger.info('') - def gen_additional_pages(self): - # type: () -> None + def gen_additional_pages(self) -> None: # pages from extensions for pagelist in self.events.emit('html-collect-pages'): for pagename, context, template in pagelist: @@ -710,8 +674,7 @@ class StandaloneHTMLBuilder(Builder): logger.info('') - def write_genindex(self): - # type: () -> None + def write_genindex(self) -> None: # the total count of lines for each index letter, used to distribute # the entries into two columns genindex = IndexEntries(self.env).create_index(self) @@ -740,8 +703,7 @@ class StandaloneHTMLBuilder(Builder): else: self.handle_page('genindex', genindexcontext, 'genindex.html') - def write_domain_indices(self): - # type: () -> None + def write_domain_indices(self) -> None: for indexname, indexcls, content, collapse in self.domain_indices: indexcontext = { 'indextitle': indexcls.localname, @@ -751,8 +713,7 @@ class StandaloneHTMLBuilder(Builder): logger.info(' ' + indexname, nonl=True) self.handle_page(indexname, indexcontext, 'domainindex.html') - def copy_image_files(self): - # type: () -> None + def copy_image_files(self) -> None: if self.images: stringify_func = ImageAdapter(self.app.env).get_original_image_uri ensuredir(path.join(self.outdir, self.imagedir)) @@ -767,11 +728,10 @@ class StandaloneHTMLBuilder(Builder): 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): - # type: (str) -> str + def copy_download_files(self) -> None: + def to_relpath(f: str) -> str: return relative_path(self.srcdir, f) + # copy downloadable files if self.env.dlfiles: ensuredir(path.join(self.outdir, '_downloads')) @@ -786,8 +746,7 @@ class StandaloneHTMLBuilder(Builder): logger.warning(__('cannot copy downloadable file %r: %s'), path.join(self.srcdir, src), err) - def copy_static_files(self): - # type: () -> None + def copy_static_files(self) -> None: try: # copy static files logger.info(bold(__('copying static files... ')), nonl=True) @@ -851,8 +810,7 @@ class StandaloneHTMLBuilder(Builder): except OSError as err: logger.warning(__('cannot copy static file %r'), err) - def copy_extra_files(self): - # type: () -> None + def copy_extra_files(self) -> None: try: # copy html_extra_path files logger.info(bold(__('copying extra files... ')), nonl=True) @@ -869,22 +827,19 @@ class StandaloneHTMLBuilder(Builder): except OSError as err: logger.warning(__('cannot copy extra file %r'), err) - def write_buildinfo(self): - # type: () -> None + def write_buildinfo(self) -> None: try: with open(path.join(self.outdir, '.buildinfo'), 'w') as fp: self.build_info.dump(fp) except OSError as exc: logger.warning(__('Failed to write build info file: %r'), exc) - def cleanup(self): - # type: () -> None + def cleanup(self) -> None: # clean up theme stuff if self.theme: self.theme.cleanup() - def post_process_images(self, doctree): - # type: (nodes.Node) -> None + def post_process_images(self, doctree: Node) -> None: """Pick the best candidate for an image and link down-scaled images to their high res version. """ @@ -909,8 +864,7 @@ class StandaloneHTMLBuilder(Builder): node.replace_self(reference) reference.append(node) - def load_indexer(self, docnames): - # type: (Iterable[str]) -> None + def load_indexer(self, docnames: Iterable[str]) -> None: keep = set(self.env.all_docs) - set(docnames) try: searchindexfn = path.join(self.outdir, self.searchindex_filename) @@ -928,8 +882,7 @@ class StandaloneHTMLBuilder(Builder): # delete all entries for files that will be rebuilt self.indexer.prune(keep) - def index_page(self, pagename, doctree, title): - # type: (str, nodes.document, str) -> None + def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None: # only index pages with title if self.indexer is not None and title: filename = self.env.doc2path(pagename, base=None) @@ -945,22 +898,19 @@ class StandaloneHTMLBuilder(Builder): indexer_name, indexer_name), RemovedInSphinx40Warning) - def _get_local_toctree(self, docname, collapse=True, **kwds): - # type: (str, bool, Any) -> str + def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds) -> str: if 'includehidden' not in kwds: kwds['includehidden'] = False return self.render_partial(TocTree(self.env).get_toctree_for( docname, self, collapse, **kwds))['fragment'] - def get_outfilename(self, pagename): - # type: (str) -> str + def get_outfilename(self, pagename: str) -> str: return path.join(self.outdir, os_path(pagename) + self.out_suffix) - def add_sidebars(self, pagename, ctx): - # type: (str, Dict) -> None - def has_wildcard(pattern): - # type: (str) -> bool + def add_sidebars(self, pagename: str, ctx: Dict) -> None: + def has_wildcard(pattern: str) -> bool: return any(char in pattern for char in '*?[') + sidebars = None matched = None customsidebar = None @@ -1009,13 +959,11 @@ class StandaloneHTMLBuilder(Builder): # --------- these are overwritten by the serialization builder - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return docname + self.link_suffix - def handle_page(self, pagename, addctx, templatename='page.html', - outfilename=None, event_arg=None): - # type: (str, Dict, str, str, Any) -> None + def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html', + outfilename: str = None, event_arg: Any = None) -> None: ctx = self.globalcontext.copy() # current_page_name is backwards compatibility ctx['pagename'] = ctx['current_page_name'] = pagename @@ -1031,8 +979,7 @@ class StandaloneHTMLBuilder(Builder): else: ctx['pageurl'] = None - def pathto(otheruri, resource=False, baseuri=default_baseuri): - # type: (str, bool, str) -> str + def pathto(otheruri: str, resource: bool = False, baseuri: str = default_baseuri) -> str: # NOQA if resource and '://' in otheruri: # allow non-local resources given by scheme return otheruri @@ -1044,8 +991,7 @@ class StandaloneHTMLBuilder(Builder): return uri ctx['pathto'] = pathto - def css_tag(css): - # type: (Stylesheet) -> str + def css_tag(css: Stylesheet) -> str: attrs = [] for key in sorted(css.attributes): value = css.attributes[key] @@ -1055,8 +1001,7 @@ class StandaloneHTMLBuilder(Builder): return '<link %s />' % ' '.join(attrs) ctx['css_tag'] = css_tag - def hasdoc(name): - # type: (str) -> bool + def hasdoc(name: str) -> bool: if name in self.env.all_docs: return True elif name == 'search' and self.search: @@ -1066,8 +1011,7 @@ class StandaloneHTMLBuilder(Builder): return False ctx['hasdoc'] = hasdoc - def warn(*args, **kwargs): - # type: (Any, Any) -> str + def warn(*args, **kwargs) -> str: """Simple warn() wrapper for themes.""" warnings.warn('The template function warn() was deprecated. ' 'Use warning() instead.', @@ -1114,24 +1058,21 @@ 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): - # type: (str, str, Dict, Any) -> None + def update_page_context(self, pagename: str, templatename: str, + ctx: Dict, event_arg: Any) -> None: pass - def handle_finish(self): - # type: () -> None + def handle_finish(self) -> 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): - # type: () -> None + def dump_inventory(self) -> None: logger.info(bold(__('dumping object inventory... ')), nonl=True) InventoryFile.dump(path.join(self.outdir, INVENTORY_FILENAME), self.env, self) logger.info(__('done')) - def dump_search_index(self): - # type: () -> None + def dump_search_index(self) -> None: logger.info( bold(__('dumping search index in %s ... ') % self.indexer.label()), nonl=True) @@ -1149,8 +1090,7 @@ class StandaloneHTMLBuilder(Builder): logger.info(__('done')) -def convert_html_css_files(app, config): - # type: (Sphinx, Config) -> None +def convert_html_css_files(app: Sphinx, config: Config) -> None: """This converts string styled html_css_files to tuple styled one.""" html_css_files = [] # type: List[Tuple[str, Dict]] for entry in config.html_css_files: @@ -1167,8 +1107,7 @@ def convert_html_css_files(app, config): config.html_css_files = html_css_files # type: ignore -def convert_html_js_files(app, config): - # type: (Sphinx, Config) -> None +def convert_html_js_files(app: Sphinx, config: Config) -> None: """This converts string styled html_js_files to tuple styled one.""" html_js_files = [] # type: List[Tuple[str, Dict]] for entry in config.html_js_files: @@ -1185,16 +1124,15 @@ def convert_html_js_files(app, config): config.html_js_files = html_js_files # type: ignore -def setup_js_tag_helper(app, pagename, templatexname, context, doctree): - # type: (Sphinx, str, str, Dict, nodes.Node) -> None +def setup_js_tag_helper(app: Sphinx, pagename: str, templatexname: str, + context: Dict, doctree: Node) -> None: """Set up js_tag() template helper. .. note:: This set up function is added to keep compatibility with webhelper. """ pathto = context.get('pathto') - def js_tag(js): - # type: (JavaScript) -> str + def js_tag(js: JavaScript) -> str: attrs = [] body = '' if isinstance(js, JavaScript): @@ -1216,8 +1154,7 @@ def setup_js_tag_helper(app, pagename, templatexname, context, doctree): context['js_tag'] = js_tag -def validate_math_renderer(app): - # type: (Sphinx) -> None +def validate_math_renderer(app: Sphinx) -> None: if app.builder.format != 'html': return @@ -1235,8 +1172,7 @@ import sphinx.builders.singlehtml # NOQA import sphinxcontrib.serializinghtml # NOQA -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: # builders app.add_builder(StandaloneHTMLBuilder) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index be365ef7e..7885acd08 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -10,20 +10,16 @@ """ import warnings +from typing import Any, Dict from sphinxcontrib.htmlhelp import ( chm_locales, chm_htmlescape, HTMLHelpBuilder, default_htmlhelp_basename ) +from sphinx.application import Sphinx from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias -if False: - # For type annotation - from typing import Any, Dict # NOQA - from sphinx.application import Sphinx # NOQA - - deprecated_alias('sphinx.builders.htmlhelp', { 'chm_locales': chm_locales, @@ -34,8 +30,7 @@ deprecated_alias('sphinx.builders.htmlhelp', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: warnings.warn('sphinx.builders.htmlhelp has been moved to sphinxcontrib-htmlhelp.', RemovedInSphinx40Warning) app.setup_extension('sphinxcontrib.htmlhelp') diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index e5754ec9b..69735ec47 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -11,14 +11,17 @@ import os import warnings from os import path +from typing import Any, Dict, Iterable, List, Tuple, Union from docutils.frontend import OptionParser +from docutils.nodes import Node import sphinx.builders.latex.nodes # NOQA # Workaround: import this before writer to avoid ImportError from sphinx import package_dir, addnodes, highlighting +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.builders.latex.util import ExtBabel -from sphinx.config import ENUM +from sphinx.config import Config, ENUM from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.environment.adapters.asset import ImageAdapter from sphinx.errors import NoUri, SphinxError @@ -38,12 +41,6 @@ from sphinx.writers.latex import ( # load docutils.nodes after loading sphinx.builders.latex.nodes from docutils import nodes # NOQA -if False: - # For type annotation - from typing import Any, Dict, Iterable, List, Tuple, Union # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - XINDY_LANG_OPTIONS = { # language codes from docutils.writers.latex2e.Babel @@ -125,8 +122,7 @@ class LaTeXBuilder(Builder): supported_remote_images = False default_translator_class = LaTeXTranslator - def init(self): - # type: () -> None + def init(self) -> None: self.babel = None # type: ExtBabel self.context = {} # type: Dict[str, Any] self.docnames = [] # type: Iterable[str] @@ -137,24 +133,20 @@ class LaTeXBuilder(Builder): self.init_context() self.init_babel() - def get_outdated_docs(self): - # type: () -> Union[str, List[str]] + def get_outdated_docs(self) -> Union[str, List[str]]: return 'all documents' # for now - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: if docname not in self.docnames: raise NoUri else: return '%' + docname - def get_relative_uri(self, from_, to, typ=None): - # type: (str, str, str) -> str + def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str: # ignore source path return self.get_target_uri(to, typ) - def init_document_data(self): - # type: () -> None + def init_document_data(self) -> None: preliminary_document_data = [list(x) for x in self.config.latex_documents] if not preliminary_document_data: logger.warning(__('no "latex_documents" config value found; no documents ' @@ -173,8 +165,7 @@ class LaTeXBuilder(Builder): docname = docname[:-5] self.titles.append((docname, entry[2])) - def init_context(self): - # type: () -> None + def init_context(self) -> None: self.context = DEFAULT_SETTINGS.copy() # Add special settings for latex_engine @@ -208,8 +199,7 @@ class LaTeXBuilder(Builder): # Show the release label only if release value exists self.context.setdefault('releasename', _('Release')) - def init_babel(self): - # type: () -> None + def init_babel(self) -> None: self.babel = ExtBabel(self.config.language, not self.context['babel']) if self.config.language and not self.babel.is_supported_language(): # emit warning if specified language is invalid @@ -217,8 +207,7 @@ class LaTeXBuilder(Builder): logger.warning(__('no Babel option known for language %r'), self.config.language) - def write_stylesheet(self): - # type: () -> None + def write_stylesheet(self) -> None: highlighter = highlighting.PygmentsBridge('latex', self.config.pygments_style) stylesheet = path.join(self.outdir, 'sphinxhighlight.sty') with open(stylesheet, 'w') as f: @@ -227,8 +216,7 @@ class LaTeXBuilder(Builder): '[2016/05/29 stylesheet for highlighting with pygments]\n\n') f.write(highlighter.get_stylesheet()) - def write(self, *ignored): - # type: (Any) -> None + def write(self, *ignored) -> None: docwriter = LaTeXWriter(self) docsettings = OptionParser( defaults=self.env.settings, @@ -271,8 +259,7 @@ class LaTeXBuilder(Builder): doctree.settings = docsettings docwriter.write(doctree, destination) - def get_contentsname(self, indexfile): - # type: (str) -> str + def get_contentsname(self, indexfile: str) -> str: tree = self.env.get_doctree(indexfile) contentsname = None for toctree in tree.traverse(addnodes.toctree): @@ -282,13 +269,11 @@ class LaTeXBuilder(Builder): return contentsname - def update_doc_context(self, title, author): - # type: (str, str) -> None + def update_doc_context(self, title: str, author: str) -> None: self.context['title'] = title self.context['author'] = author - def assemble_doctree(self, indexfile, toctree_only, appendices): - # type: (str, bool, List[str]) -> nodes.document + def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[str]) -> nodes.document: # NOQA self.docnames = set([indexfile] + appendices) logger.info(darkgreen(indexfile) + " ", nonl=True) tree = self.env.get_doctree(indexfile) @@ -319,7 +304,7 @@ class LaTeXBuilder(Builder): for pendingnode in largetree.traverse(addnodes.pending_xref): docname = pendingnode['refdocname'] sectname = pendingnode['refsectname'] - newnodes = [nodes.emphasis(sectname, sectname)] # type: List[nodes.Node] + newnodes = [nodes.emphasis(sectname, sectname)] # type: List[Node] for subdir, title in self.titles: if docname.startswith(subdir): newnodes.append(nodes.Text(_(' (in '), _(' (in '))) @@ -331,13 +316,11 @@ class LaTeXBuilder(Builder): pendingnode.replace_self(newnodes) return largetree - def apply_transforms(self, doctree): - # type: (nodes.document) -> None + def apply_transforms(self, doctree: nodes.document) -> None: warnings.warn('LaTeXBuilder.apply_transforms() is deprecated.', RemovedInSphinx40Warning) - def finish(self): - # type: () -> None + def finish(self) -> None: self.copy_image_files() self.write_message_catalog() self.copy_support_files() @@ -346,8 +329,7 @@ class LaTeXBuilder(Builder): self.copy_latex_additional_files() @progress_message(__('copying TeX support files')) - def copy_support_files(self): - # type: () -> None + def copy_support_files(self) -> None: """copy TeX support files from texinputs.""" # configure usage of xindy (impacts Makefile and latexmkrc) # FIXME: convert this rather to a confval with suitable default @@ -387,14 +369,12 @@ class LaTeXBuilder(Builder): copy_asset_file(path.join(self.confdir, self.config.latex_logo), self.outdir) @progress_message(__('copying additional files')) - def copy_latex_additional_files(self): - # type: () -> None + def copy_latex_additional_files(self) -> None: for filename in self.config.latex_additional_files: logger.info(' ' + filename, nonl=True) copy_asset_file(path.join(self.confdir, filename), self.outdir) - def copy_image_files(self): - # type: () -> None + def copy_image_files(self) -> None: if self.images: stringify_func = ImageAdapter(self.app.env).get_original_image_uri for src in status_iterator(self.images, __('copying images... '), "brown", @@ -408,8 +388,7 @@ class LaTeXBuilder(Builder): logger.warning(__('cannot copy image file %r: %s'), path.join(self.srcdir, src), err) - def write_message_catalog(self): - # type: () -> None + def write_message_catalog(self) -> None: formats = self.config.numfig_format context = { 'addtocaptions': r'\@iden', @@ -425,8 +404,7 @@ class LaTeXBuilder(Builder): copy_asset_file(filename, self.outdir, context=context, renderer=LaTeXRenderer()) -def validate_config_values(app, config): - # type: (Sphinx, Config) -> None +def validate_config_values(app: Sphinx, config: Config) -> None: for key in list(config.latex_elements): if key not in DEFAULT_SETTINGS: msg = __("Unknown configure key: latex_elements[%r]. ignored.") @@ -434,8 +412,7 @@ def validate_config_values(app, config): config.latex_elements.pop(key) -def default_latex_engine(config): - # type: (Config) -> str +def default_latex_engine(config: Config) -> str: """ Better default latex_engine settings for specific languages. """ if config.language == 'ja': return 'platex' @@ -445,8 +422,7 @@ def default_latex_engine(config): return 'pdflatex' -def default_latex_docclass(config): - # type: (Config) -> Dict[str, str] +def default_latex_docclass(config: Config) -> Dict[str, str]: """ Better default latex_docclass settings for specific languages. """ if config.language == 'ja': return {'manual': 'jsbook', @@ -455,14 +431,12 @@ def default_latex_docclass(config): return {} -def default_latex_use_xindy(config): - # type: (Config) -> bool +def default_latex_use_xindy(config: Config) -> bool: """ Better default latex_use_xindy settings for specific engines. """ return config.latex_engine in {'xelatex', 'lualatex'} -def default_latex_documents(config): - # type: (Config) -> List[Tuple[str, str, str, str, str]] +def default_latex_documents(config: Config) -> List[Tuple[str, str, str, str, str]]: """ Better default latex_documents settings. """ return [(config.master_doc, make_filename_from_project(config.project) + '.tex', @@ -471,8 +445,7 @@ def default_latex_documents(config): 'manual')] -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.setup_extension('sphinx.builders.latex.transforms') app.add_builder(LaTeXBuilder) diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py index 6381780ae..9fe44bc95 100644 --- a/sphinx/builders/latex/transforms.py +++ b/sphinx/builders/latex/transforms.py @@ -8,11 +8,14 @@ :license: BSD, see LICENSE for details. """ +from typing import Any, Dict, List, Set, Tuple from typing import cast from docutils import nodes +from docutils.nodes import Element, Node from sphinx import addnodes +from sphinx.application import Sphinx from sphinx.builders.latex.nodes import ( captioned_literal_block, footnotemark, footnotetext, math_reference, thebibliography ) @@ -21,11 +24,6 @@ from sphinx.transforms import SphinxTransform from sphinx.transforms.post_transforms import SphinxPostTransform from sphinx.util.nodes import NodeMatcher -if False: - # For type annotation - from typing import Any, Dict, List, Set, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - URI_SCHEMES = ('mailto:', 'http:', 'https:', 'ftp:') @@ -34,8 +32,7 @@ class FootnoteDocnameUpdater(SphinxTransform): default_priority = 700 TARGET_NODES = (nodes.footnote, nodes.footnote_reference) - def apply(self, **kwargs): - # type: (Any) -> None + def apply(self, **kwargs) -> None: matcher = NodeMatcher(*self.TARGET_NODES) for node in self.document.traverse(matcher): # type: nodes.Element node['docname'] = self.env.docname @@ -54,8 +51,7 @@ class ShowUrlsTransform(SphinxPostTransform): # references are expanded to footnotes (or not) expanded = False - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: try: # replace id_prefix temporarily settings = self.document.settings # type: Any @@ -69,8 +65,7 @@ class ShowUrlsTransform(SphinxPostTransform): # restore id_prefix settings.id_prefix = id_prefix - def expand_show_urls(self): - # type: () -> None + def expand_show_urls(self) -> None: show_urls = self.config.latex_show_urls if show_urls is False or show_urls == 'no': return @@ -93,8 +88,7 @@ class ShowUrlsTransform(SphinxPostTransform): textnode = nodes.Text(" (%s)" % uri) node.parent.insert(index + 1, textnode) - def get_docname_for_node(self, node): - # type: (nodes.Node) -> str + def get_docname_for_node(self, node: Node) -> str: while node: if isinstance(node, nodes.document): return self.env.path2doc(node['source']) @@ -105,8 +99,7 @@ class ShowUrlsTransform(SphinxPostTransform): return None # never reached here. only for type hinting - def create_footnote(self, uri, docname): - # type: (str, str) -> Tuple[nodes.footnote, nodes.footnote_reference] + def create_footnote(self, uri: str, docname: str) -> Tuple[nodes.footnote, nodes.footnote_reference]: # NOQA reference = nodes.reference('', nodes.Text(uri), refuri=uri, nolinkurl=True) footnote = nodes.footnote(uri, auto=1, docname=docname) footnote['names'].append('#') @@ -122,8 +115,7 @@ class ShowUrlsTransform(SphinxPostTransform): return footnote, footnote_ref - def renumber_footnotes(self): - # type: () -> None + def renumber_footnotes(self) -> None: collector = FootnoteCollector(self.document) self.document.walkabout(collector) @@ -153,31 +145,26 @@ class ShowUrlsTransform(SphinxPostTransform): class FootnoteCollector(nodes.NodeVisitor): """Collect footnotes and footnote references on the document""" - def __init__(self, document): - # type: (nodes.document) -> None + def __init__(self, document: nodes.document) -> None: self.auto_footnotes = [] # type: List[nodes.footnote] self.used_footnote_numbers = set() # type: Set[str] self.footnote_refs = [] # type: List[nodes.footnote_reference] super().__init__(document) - def unknown_visit(self, node): - # type: (nodes.Node) -> None + def unknown_visit(self, node: Node) -> None: pass - def unknown_departure(self, node): - # type: (nodes.Node) -> None + def unknown_departure(self, node: Node) -> None: pass - def visit_footnote(self, node): - # type: (nodes.footnote) -> None + def visit_footnote(self, node: nodes.footnote) -> None: if node.get('auto'): self.auto_footnotes.append(node) else: for name in node['names']: self.used_footnote_numbers.add(name) - def visit_footnote_reference(self, node): - # type: (nodes.footnote_reference) -> None + def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: self.footnote_refs.append(node) @@ -351,8 +338,7 @@ class LaTeXFootnoteTransform(SphinxPostTransform): default_priority = 600 builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: footnotes = list(self.document.traverse(nodes.footnote)) for node in footnotes: node.parent.remove(node) @@ -362,8 +348,7 @@ class LaTeXFootnoteTransform(SphinxPostTransform): class LaTeXFootnoteVisitor(nodes.NodeVisitor): - def __init__(self, document, footnotes): - # type: (nodes.document, List[nodes.footnote]) -> None + def __init__(self, document: nodes.document, footnotes: List[nodes.footnote]) -> None: self.appeared = set() # type: Set[Tuple[str, str]] self.footnotes = footnotes # type: List[nodes.footnote] self.pendings = [] # type: List[nodes.footnote] @@ -371,21 +356,17 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor): self.restricted = None # type: nodes.Element super().__init__(document) - def unknown_visit(self, node): - # type: (nodes.Node) -> None + def unknown_visit(self, node: Node) -> None: pass - def unknown_departure(self, node): - # type: (nodes.Node) -> None + def unknown_departure(self, node: Node) -> None: pass - def restrict(self, node): - # type: (nodes.Element) -> None + def restrict(self, node: Element) -> None: if self.restricted is None: self.restricted = node - def unrestrict(self, node): - # type: (nodes.Element) -> None + def unrestrict(self, node: Element) -> None: if self.restricted == node: self.restricted = None pos = node.parent.index(node) @@ -394,37 +375,29 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor): node.parent.insert(pos + i + 1, fntext) self.pendings = [] - def visit_figure(self, node): - # type: (nodes.figure) -> None + def visit_figure(self, node: nodes.figure) -> None: self.restrict(node) - def depart_figure(self, node): - # type: (nodes.figure) -> None + def depart_figure(self, node: nodes.figure) -> None: self.unrestrict(node) - def visit_term(self, node): - # type: (nodes.term) -> None + def visit_term(self, node: nodes.term) -> None: self.restrict(node) - def depart_term(self, node): - # type: (nodes.term) -> None + def depart_term(self, node: nodes.term) -> None: self.unrestrict(node) - def visit_caption(self, node): - # type: (nodes.caption) -> None + def visit_caption(self, node: nodes.caption) -> None: self.restrict(node) - def depart_caption(self, node): - # type: (nodes.caption) -> None + def depart_caption(self, node: nodes.caption) -> None: self.unrestrict(node) - def visit_title(self, node): - # type: (nodes.title) -> None + def visit_title(self, node: nodes.title) -> None: if isinstance(node.parent, (nodes.section, nodes.table)): self.restrict(node) - def depart_title(self, node): - # type: (nodes.title) -> None + def depart_title(self, node: nodes.title) -> None: if isinstance(node.parent, nodes.section): self.unrestrict(node) elif isinstance(node.parent, nodes.table): @@ -432,18 +405,15 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor): self.pendings = [] self.unrestrict(node) - def visit_thead(self, node): - # type: (nodes.thead) -> None + def visit_thead(self, node: nodes.thead) -> None: self.restrict(node) - def depart_thead(self, node): - # type: (nodes.thead) -> None + def depart_thead(self, node: nodes.thead) -> None: self.table_footnotes += self.pendings self.pendings = [] self.unrestrict(node) - def depart_table(self, node): - # type: (nodes.table) -> None + def depart_table(self, node: nodes.table) -> None: tbody = list(node.traverse(nodes.tbody))[0] for footnote in reversed(self.table_footnotes): fntext = footnotetext('', *footnote.children) @@ -451,16 +421,13 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor): self.table_footnotes = [] - def visit_footnote(self, node): - # type: (nodes.footnote) -> None + def visit_footnote(self, node: nodes.footnote) -> None: self.restrict(node) - def depart_footnote(self, node): - # type: (nodes.footnote) -> None + def depart_footnote(self, node: nodes.footnote) -> None: self.unrestrict(node) - def visit_footnote_reference(self, node): - # type: (nodes.footnote_reference) -> None + def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: number = node.astext().strip() docname = node['docname'] if self.restricted: @@ -481,8 +448,7 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor): self.appeared.add((docname, number)) raise nodes.SkipNode - def get_footnote_by_reference(self, node): - # type: (nodes.footnote_reference) -> nodes.footnote + def get_footnote_by_reference(self, node: nodes.footnote_reference) -> nodes.footnote: docname = node['docname'] for footnote in self.footnotes: if docname == footnote['docname'] and footnote['ids'][0] == node['refid']: @@ -524,8 +490,7 @@ class BibliographyTransform(SphinxPostTransform): default_priority = 750 builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: citations = thebibliography() for node in self.document.traverse(nodes.citation): node.parent.remove(node) @@ -544,8 +509,7 @@ class CitationReferenceTransform(SphinxPostTransform): default_priority = 5 # before ReferencesResolver builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: domain = cast(CitationDomain, self.env.get_domain('citation')) matcher = NodeMatcher(addnodes.pending_xref, refdomain='citation', reftype='ref') for node in self.document.traverse(matcher): # type: addnodes.pending_xref @@ -565,8 +529,7 @@ class MathReferenceTransform(SphinxPostTransform): default_priority = 5 # before ReferencesResolver builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: equations = self.env.get_domain('math').data['objects'] for node in self.document.traverse(addnodes.pending_xref): if node['refdomain'] == 'math' and node['reftype'] in ('eq', 'numref'): @@ -581,8 +544,7 @@ class LiteralBlockTransform(SphinxPostTransform): default_priority = 400 builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: matcher = NodeMatcher(nodes.container, literal_block=True) for node in self.document.traverse(matcher): # type: nodes.container newnode = captioned_literal_block('', *node.children, **node.attributes) @@ -594,8 +556,7 @@ class DocumentTargetTransform(SphinxPostTransform): default_priority = 400 builders = ('latex',) - def run(self, **kwargs): - # type: (Any) -> None + def run(self, **kwargs) -> None: for node in self.document.traverse(addnodes.start_of_file): section = node.next_node(nodes.section) if section: @@ -639,8 +600,7 @@ class IndexInSectionTitleTransform(SphinxTransform): node.parent.insert(i + 1, index) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_transform(FootnoteDocnameUpdater) app.add_post_transform(BibliographyTransform) app.add_post_transform(CitationReferenceTransform) diff --git a/sphinx/builders/latex/util.py b/sphinx/builders/latex/util.py index 3aa278496..8155d1fd7 100644 --- a/sphinx/builders/latex/util.py +++ b/sphinx/builders/latex/util.py @@ -18,30 +18,25 @@ from sphinx.deprecation import RemovedInSphinx30Warning class ExtBabel(Babel): cyrillic_languages = ('bulgarian', 'kazakh', 'mongolian', 'russian', 'ukrainian') - def __init__(self, language_code, use_polyglossia=False): - # type: (str, bool) -> None + def __init__(self, language_code: str, use_polyglossia: bool = False) -> None: self.language_code = language_code self.use_polyglossia = use_polyglossia self.supported = True super().__init__(language_code or '') - def get_shorthandoff(self): - # type: () -> str + def get_shorthandoff(self) -> str: warnings.warn('ExtBabel.get_shorthandoff() is deprecated.', RemovedInSphinx30Warning, stacklevel=2) from sphinx.writers.latex import SHORTHANDOFF return SHORTHANDOFF - def uses_cyrillic(self): - # type: () -> bool + def uses_cyrillic(self) -> bool: return self.language in self.cyrillic_languages - def is_supported_language(self): - # type: () -> bool + def is_supported_language(self) -> bool: return self.supported - def language_name(self, language_code): - # type: (str) -> str + def language_name(self, language_code: str) -> str: language = super().language_name(language_code) if language == 'ngerman' and self.use_polyglossia: # polyglossia calls new orthography (Neue Rechtschreibung) as @@ -55,8 +50,7 @@ class ExtBabel(Babel): self.supported = False return 'english' # fallback to english - def get_mainlanguage_options(self): - # type: () -> str + def get_mainlanguage_options(self) -> str: """Return options for polyglossia's ``\\setmainlanguage``.""" if self.use_polyglossia is False: return None diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index 164f1e6b7..14aa1c530 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -14,11 +14,14 @@ import socket import threading from html.parser import HTMLParser from os import path +from typing import Any, Dict, List, Set, Tuple from urllib.parse import unquote from docutils import nodes +from docutils.nodes import Node from requests.exceptions import HTTPError +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.locale import __ from sphinx.util import encode_uri, requests, logging @@ -28,12 +31,6 @@ from sphinx.util.console import ( # type: ignore from sphinx.util.nodes import get_node_line from sphinx.util.requests import is_ssl_error -if False: - # For type annotation - from typing import Any, Dict, List, Set, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.util.requests.requests import Response # NOQA - logger = logging.getLogger(__name__) @@ -41,23 +38,20 @@ logger = logging.getLogger(__name__) class AnchorCheckParser(HTMLParser): """Specialized HTML parser that looks for a specific anchor.""" - def __init__(self, search_anchor): - # type: (str) -> None + def __init__(self, search_anchor: str) -> None: super().__init__() self.search_anchor = search_anchor self.found = False - def handle_starttag(self, tag, attrs): - # type: (Any, Any) -> None + def handle_starttag(self, tag: Any, attrs: Any) -> None: for key, value in attrs: if key in ('id', 'name') and value == self.search_anchor: self.found = True break -def check_anchor(response, anchor): - # type: (Response, str) -> bool +def check_anchor(response: requests.requests.Response, anchor: str) -> bool: """Reads HTML data from a response object `response` searching for `anchor`. Returns True if anchor was found, False otherwise. """ @@ -80,8 +74,7 @@ class CheckExternalLinksBuilder(Builder): epilog = __('Look for any errors in the above output or in ' '%(outdir)s/output.txt') - def init(self): - # type: () -> None + def init(self) -> 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] @@ -103,8 +96,7 @@ class CheckExternalLinksBuilder(Builder): thread.start() self.workers.append(thread) - def check_thread(self): - # type: () -> None + def check_thread(self) -> None: kwargs = { 'allow_redirects': True, 'headers': { @@ -115,8 +107,7 @@ class CheckExternalLinksBuilder(Builder): if self.app.config.linkcheck_timeout: kwargs['timeout'] = self.app.config.linkcheck_timeout - def check_uri(): - # type: () -> Tuple[str, str, int] + def check_uri() -> Tuple[str, str, int]: # split off anchor if '#' in uri: req_url, anchor = uri.split('#', 1) @@ -159,6 +150,9 @@ class CheckExternalLinksBuilder(Builder): if err.response.status_code == 401: # We'll take "Unauthorized" as working. return 'working', ' - unauthorized', 0 + elif err.response.status_code == 503: + # We'll take "Service Unavailable" as ignored. + return 'ignored', str(err), 0 else: return 'broken', str(err), 0 except Exception as err: @@ -179,8 +173,7 @@ class CheckExternalLinksBuilder(Builder): else: return 'redirected', new_url, 0 - def check(): - # type: () -> Tuple[str, str, int] + def check() -> Tuple[str, str, int]: # check for various conditions without bothering the network if len(uri) == 0 or uri.startswith(('#', 'mailto:', 'ftp:')): return 'unchecked', '', 0 @@ -218,8 +211,7 @@ class CheckExternalLinksBuilder(Builder): status, info, code = check() self.rqueue.put((uri, docname, lineno, status, info, code)) - def process_result(self, result): - # type: (Tuple[str, str, int, str, str, int]) -> None + def process_result(self, result: Tuple[str, str, int, str, str, int]) -> None: uri, docname, lineno, status, info, code = result if status == 'unchecked': return @@ -256,20 +248,16 @@ class CheckExternalLinksBuilder(Builder): uri + ' to ' + info) logger.info(color('redirect ') + uri + color(' - ' + text + ' to ' + info)) - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return '' - def get_outdated_docs(self): - # type: () -> Set[str] + def get_outdated_docs(self) -> Set[str]: return self.env.found_docs - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: return - def write_doc(self, docname, doctree): - # type: (str, nodes.Node) -> None + def write_doc(self, docname: str, doctree: Node) -> None: logger.info('') n = 0 @@ -298,20 +286,17 @@ class CheckExternalLinksBuilder(Builder): if self.broken: self.app.statuscode = 1 - def write_entry(self, what, docname, line, uri): - # type: (str, str, int, str) -> None + def write_entry(self, what: str, docname: str, line: int, uri: str) -> None: with open(path.join(self.outdir, 'output.txt'), 'a', encoding='utf-8') as output: output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), line, what, uri)) - def finish(self): - # type: () -> None + def finish(self) -> None: for worker in self.workers: self.wqueue.put((None, None, None), False) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, 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 5e424547c..94b312e36 100644 --- a/sphinx/builders/manpage.py +++ b/sphinx/builders/manpage.py @@ -9,12 +9,15 @@ """ from os import path +from typing import Any, Dict, List, Set, Tuple, Union from docutils.frontend import OptionParser from docutils.io import FileOutput from sphinx import addnodes +from sphinx.application import Sphinx from sphinx.builders import Builder +from sphinx.config import Config from sphinx.errors import NoUri from sphinx.locale import __ from sphinx.util import logging @@ -24,12 +27,6 @@ from sphinx.util.nodes import inline_all_toctrees from sphinx.util.osutil import make_filename_from_project from sphinx.writers.manpage import ManualPageWriter, ManualPageTranslator -if False: - # For type annotation - from typing import Any, Dict, List, Set, Tuple, Union # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - logger = logging.getLogger(__name__) @@ -45,25 +42,21 @@ class ManualPageBuilder(Builder): default_translator_class = ManualPageTranslator supported_image_types = [] # type: List[str] - def init(self): - # type: () -> None + def init(self) -> None: if not self.config.man_pages: logger.warning(__('no "man_pages" config value found; no manual pages ' 'will be written')) - def get_outdated_docs(self): - # type: () -> Union[str, List[str]] + def get_outdated_docs(self) -> Union[str, List[str]]: return 'all manpages' # for now - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: if typ == 'token': return '' raise NoUri @progress_message(__('writing')) - def write(self, *ignored): - # type: (Any) -> None + def write(self, *ignored) -> None: docwriter = ManualPageWriter(self) docsettings = OptionParser( defaults=self.env.settings, @@ -106,21 +99,18 @@ class ManualPageBuilder(Builder): docwriter.write(largetree, destination) - def finish(self): - # type: () -> None + def finish(self) -> None: pass -def default_man_pages(config): - # type: (Config) -> List[Tuple[str, str, str, List[str], int]] +def default_man_pages(config: Config) -> List[Tuple[str, str, str, List[str], int]]: """ Better default man_pages settings. """ filename = make_filename_from_project(config.project) return [(config.master_doc, filename, '%s %s' % (config.project, config.release), [config.author], 1)] -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(ManualPageBuilder) app.add_config_value('man_pages', default_man_pages, None) diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index d87246148..4053f437f 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -9,17 +9,14 @@ """ import warnings +from typing import Any, Dict from sphinxcontrib.qthelp import QtHelpBuilder, render_file import sphinx +from sphinx.application import Sphinx from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias -if False: - # For type annotation - from typing import Any, Dict # NOQA - from sphinx.application import Sphinx # NOQA - deprecated_alias('sphinx.builders.qthelp', { @@ -29,8 +26,7 @@ deprecated_alias('sphinx.builders.qthelp', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: warnings.warn('sphinx.builders.qthelp has been moved to sphinxcontrib-qthelp.', RemovedInSphinx40Warning) diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py index 068d1c1c2..3309b024c 100644 --- a/sphinx/builders/singlehtml.py +++ b/sphinx/builders/singlehtml.py @@ -9,9 +9,12 @@ """ from os import path +from typing import Any, Dict, List, Tuple, Union from docutils import nodes +from docutils.nodes import Node +from sphinx.application import Sphinx from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias from sphinx.environment.adapters.toctree import TocTree @@ -21,11 +24,6 @@ from sphinx.util import progress_message from sphinx.util.console import darkgreen # type: ignore from sphinx.util.nodes import inline_all_toctrees -if False: - # For type annotation - from typing import Any, Dict, List, Tuple, Union # NOQA - from sphinx.application import Sphinx # NOQA - logger = logging.getLogger(__name__) @@ -39,12 +37,10 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): copysource = False - def get_outdated_docs(self): # type: ignore - # type: () -> Union[str, List[str]] + def get_outdated_docs(self) -> Union[str, List[str]]: # type: ignore return 'all documents' - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: if docname in self.env.all_docs: # all references are on the same page... return self.config.master_doc + self.out_suffix + \ @@ -53,13 +49,11 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): # chances are this is a html_additional_page return docname + self.out_suffix - def get_relative_uri(self, from_, to, typ=None): - # type: (str, str, str) -> str + def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str: # ignore source return self.get_target_uri(to, typ) - def fix_refuris(self, tree): - # type: (nodes.Node) -> None + def fix_refuris(self, tree: Node) -> None: # fix refuris with double anchor fname = self.config.master_doc + self.out_suffix for refnode in tree.traverse(nodes.reference): @@ -73,8 +67,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): if hashindex >= 0: refnode['refuri'] = fname + refuri[hashindex:] - def _get_local_toctree(self, docname, collapse=True, **kwds): - # type: (str, bool, Any) -> str + def _get_local_toctree(self, docname: str, collapse: bool = True, **kwds) -> str: if 'includehidden' not in kwds: kwds['includehidden'] = False toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwds) @@ -82,8 +75,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): self.fix_refuris(toctree) return self.render_partial(toctree)['fragment'] - def assemble_doctree(self): - # type: () -> nodes.document + def assemble_doctree(self) -> nodes.document: master = self.config.master_doc tree = self.env.get_doctree(master) tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master]) @@ -92,8 +84,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): self.fix_refuris(tree) return tree - def assemble_toc_secnumbers(self): - # type: () -> Dict[str, Dict[str, Tuple[int, ...]]] + def assemble_toc_secnumbers(self) -> Dict[str, Dict[str, Tuple[int, ...]]]: # Assemble toc_secnumbers to resolve section numbers on SingleHTML. # Merge all secnumbers to single secnumber. # @@ -111,8 +102,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return {self.config.master_doc: new_secnumbers} - def assemble_toc_fignumbers(self): - # type: () -> Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]] + def assemble_toc_fignumbers(self) -> Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]]: # Assemble toc_fignumbers to resolve figure numbers on SingleHTML. # Merge all fignumbers to single fignumber. # @@ -133,8 +123,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): return {self.config.master_doc: new_fignumbers} - def get_doc_context(self, docname, body, metatags): - # type: (str, str, str) -> Dict + def get_doc_context(self, docname: str, body: str, metatags: str) -> Dict: # no relation links... toctree = TocTree(self.env).get_toctree_for(self.config.master_doc, self, False) # if there is no toctree, toc is None @@ -160,8 +149,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): 'display_toc': display_toc, } - def write(self, *ignored): - # type: (Any) -> None + def write(self, *ignored) -> None: docnames = self.env.all_docs with progress_message(__('preparing documents')): @@ -176,8 +164,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): self.write_doc_serialized(self.config.master_doc, doctree) self.write_doc(self.config.master_doc, doctree) - def finish(self): - # type: () -> None + def finish(self) -> None: self.write_additional_files() self.copy_image_files() self.copy_download_files() @@ -187,8 +174,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): self.dump_inventory() @progress_message(__('writing additional files')) - def write_additional_files(self): - # type: () -> None + def write_additional_files(self) -> None: # no indices or search pages are supported # additional pages from conf.py @@ -210,8 +196,7 @@ deprecated_alias('sphinx.builders.html', RemovedInSphinx40Warning) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.setup_extension('sphinx.builders.html') app.add_builder(SingleFileHTMLBuilder) diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py index 301f30fe0..16f81c666 100644 --- a/sphinx/builders/texinfo.py +++ b/sphinx/builders/texinfo.py @@ -10,6 +10,7 @@ import os from os import path +from typing import Any, Dict, Iterable, List, Tuple, Union from docutils import nodes from docutils.frontend import OptionParser @@ -17,7 +18,9 @@ from docutils.io import FileOutput from sphinx import addnodes from sphinx import package_dir +from sphinx.application import Sphinx from sphinx.builders import Builder +from sphinx.config import Config from sphinx.environment.adapters.asset import ImageAdapter from sphinx.errors import NoUri from sphinx.locale import _, __ @@ -30,12 +33,6 @@ from sphinx.util.nodes import inline_all_toctrees from sphinx.util.osutil import SEP, ensuredir, make_filename_from_project from sphinx.writers.texinfo import TexinfoWriter, TexinfoTranslator -if False: - # For type annotation - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA - from typing import Any, Dict, Iterable, List, Tuple, Union # NOQA - logger = logging.getLogger(__name__) template_dir = os.path.join(package_dir, 'templates', 'texinfo') @@ -57,29 +54,24 @@ class TexinfoBuilder(Builder): 'image/gif'] default_translator_class = TexinfoTranslator - def init(self): - # type: () -> None + def init(self) -> None: self.docnames = [] # type: Iterable[str] self.document_data = [] # type: List[Tuple[str, str, str, str, str, str, str, bool]] - def get_outdated_docs(self): - # type: () -> Union[str, List[str]] + def get_outdated_docs(self) -> Union[str, List[str]]: return 'all documents' # for now - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: if docname not in self.docnames: raise NoUri else: return '%' + docname - def get_relative_uri(self, from_, to, typ=None): - # type: (str, str, str) -> str + def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str: # ignore source path return self.get_target_uri(to, typ) - def init_document_data(self): - # type: () -> None + def init_document_data(self) -> None: preliminary_document_data = [list(x) for x in self.config.texinfo_documents] if not preliminary_document_data: logger.warning(__('no "texinfo_documents" config value found; no documents ' @@ -98,8 +90,7 @@ class TexinfoBuilder(Builder): docname = docname[:-5] self.titles.append((docname, entry[2])) - def write(self, *ignored): - # type: (Any) -> None + def write(self, *ignored) -> None: self.init_document_data() for entry in self.document_data: docname, targetname, title, author = entry[:4] @@ -136,8 +127,7 @@ class TexinfoBuilder(Builder): docwriter.write(doctree, destination) self.copy_image_files(targetname[:-5]) - def assemble_doctree(self, indexfile, toctree_only, appendices): - # type: (str, bool, List[str]) -> nodes.document + def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[str]) -> nodes.document: # NOQA self.docnames = set([indexfile] + appendices) logger.info(darkgreen(indexfile) + " ", nonl=True) tree = self.env.get_doctree(indexfile) @@ -179,12 +169,10 @@ class TexinfoBuilder(Builder): pendingnode.replace_self(newnodes) return largetree - def finish(self): - # type: () -> None + def finish(self) -> None: self.copy_support_files() - def copy_image_files(self, targetname): - # type: (str) -> None + def copy_image_files(self, targetname: str) -> None: if self.images: stringify_func = ImageAdapter(self.app.env).get_original_image_uri for src in status_iterator(self.images, __('copying images... '), "brown", @@ -199,8 +187,7 @@ class TexinfoBuilder(Builder): logger.warning(__('cannot copy image file %r: %s'), path.join(self.srcdir, src), err) - def copy_support_files(self): - # type: () -> None + def copy_support_files(self) -> None: try: with progress_message(__('copying Texinfo support files')): logger.info('Makefile ', nonl=True) @@ -209,16 +196,14 @@ class TexinfoBuilder(Builder): logger.warning(__("error writing file Makefile: %s"), err) -def default_texinfo_documents(config): - # type: (Config) -> List[Tuple[str, str, str, str, str, str, str]] +def default_texinfo_documents(config: Config) -> List[Tuple[str, str, str, str, str, str, str]]: # NOQA """ Better default texinfo_documents settings. """ filename = make_filename_from_project(config.project) return [(config.master_doc, filename, config.project, config.author, filename, 'One line description of project', 'Miscellaneous')] -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(TexinfoBuilder) app.add_config_value('texinfo_documents', default_texinfo_documents, None) diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py index d0875161d..475513cf9 100644 --- a/sphinx/builders/text.py +++ b/sphinx/builders/text.py @@ -9,21 +9,18 @@ """ from os import path +from typing import Any, Dict, Iterator, Set, Tuple from docutils.io import StringOutput +from docutils.nodes import Node +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.locale import __ from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path from sphinx.writers.text import TextWriter, TextTranslator -if False: - # For type annotation - from typing import Any, Dict, Iterator, Set, Tuple # NOQA - from docutils import nodes # NOQA - from sphinx.application import Sphinx # NOQA - logger = logging.getLogger(__name__) @@ -38,13 +35,11 @@ class TextBuilder(Builder): current_docname = None # type: str - def init(self): - # type: () -> None + def init(self) -> None: # section numbers for headings in the currently visited document self.secnumbers = {} # type: Dict[str, Tuple[int, ...]] - def get_outdated_docs(self): - # type: () -> Iterator[str] + def get_outdated_docs(self) -> Iterator[str]: for docname in self.env.found_docs: if docname not in self.env.all_docs: yield docname @@ -62,16 +57,13 @@ class TextBuilder(Builder): # source doesn't exist anymore pass - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return '' - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: self.writer = TextWriter(self) - def write_doc(self, docname, doctree): - # type: (str, nodes.Node) -> None + def write_doc(self, docname: str, doctree: Node) -> None: self.current_docname = docname self.secnumbers = self.env.toc_secnumbers.get(docname, {}) destination = StringOutput(encoding='utf-8') @@ -84,13 +76,11 @@ class TextBuilder(Builder): except OSError as err: logger.warning(__("error writing file %s: %s"), outfilename, err) - def finish(self): - # type: () -> None + def finish(self) -> None: pass -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(TextBuilder) app.add_config_value('text_sectionchars', '*=-~"+`', 'env') diff --git a/sphinx/builders/xml.py b/sphinx/builders/xml.py index b3d12149b..4aaa0811d 100644 --- a/sphinx/builders/xml.py +++ b/sphinx/builders/xml.py @@ -9,23 +9,20 @@ """ from os import path +from typing import Any, Dict, Iterator, Set, Type, Union from docutils import nodes from docutils.io import StringOutput +from docutils.nodes import Node from docutils.writers.docutils_xml import XMLTranslator +from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.locale import __ from sphinx.util import logging from sphinx.util.osutil import ensuredir, os_path from sphinx.writers.xml import XMLWriter, PseudoXMLWriter -if False: - # For type annotation - from typing import Any, Dict, Iterator, Set, Type # NOQA - from docutils.writers.xml import BaseXMLWriter # NOQA - from sphinx.application import Sphinx # NOQA - logger = logging.getLogger(__name__) @@ -40,15 +37,13 @@ class XMLBuilder(Builder): out_suffix = '.xml' allow_parallel = True - _writer_class = XMLWriter # type: Type[BaseXMLWriter] + _writer_class = XMLWriter # type: Union[Type[XMLWriter], Type[PseudoXMLWriter]] default_translator_class = XMLTranslator - def init(self): - # type: () -> None + def init(self) -> None: pass - def get_outdated_docs(self): - # type: () -> Iterator[str] + def get_outdated_docs(self) -> Iterator[str]: for docname in self.env.found_docs: if docname not in self.env.all_docs: yield docname @@ -66,16 +61,13 @@ class XMLBuilder(Builder): # source doesn't exist anymore pass - def get_target_uri(self, docname, typ=None): - # type: (str, str) -> str + def get_target_uri(self, docname: str, typ: str = None) -> str: return docname - def prepare_writing(self, docnames): - # type: (Set[str]) -> None + def prepare_writing(self, docnames: Set[str]) -> None: self.writer = self._writer_class(self) - def write_doc(self, docname, doctree): - # type: (str, nodes.Node) -> None + def write_doc(self, docname: str, doctree: Node) -> None: # work around multiple string % tuple issues in docutils; # replace tuples in attribute values with lists doctree = doctree.deepcopy() @@ -98,8 +90,7 @@ class XMLBuilder(Builder): except OSError as err: logger.warning(__("error writing file %s: %s"), outfilename, err) - def finish(self): - # type: () -> None + def finish(self) -> None: pass @@ -116,8 +107,7 @@ class PseudoXMLBuilder(XMLBuilder): _writer_class = PseudoXMLWriter -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: Sphinx) -> Dict[str, Any]: app.add_builder(XMLBuilder) app.add_builder(PseudoXMLBuilder) diff --git a/sphinx/cmd/quickstart.py b/sphinx/cmd/quickstart.py index 49abc2fa1..2a509bacb 100644 --- a/sphinx/cmd/quickstart.py +++ b/sphinx/cmd/quickstart.py @@ -310,7 +310,7 @@ you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see -http://sphinx-doc.org/config.html#confval-language.''')) +https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.''')) d['language'] = do_prompt(__('Project language'), 'en') if d['language'] == 'en': d['language'] = None diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 40f838c48..13f48e827 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -9,23 +9,24 @@ """ import re -from typing import List, cast +from typing import Any, Dict, List, Tuple +from typing import cast from docutils import nodes +from docutils.nodes import Node from docutils.parsers.rst import directives, roles from sphinx import addnodes +from sphinx.addnodes import desc_signature from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias from sphinx.util import docutils -from sphinx.util.docfields import DocFieldTransformer, TypedField +from sphinx.util.docfields import DocFieldTransformer, Field, TypedField from sphinx.util.docutils import SphinxDirective +from sphinx.util.typing import DirectiveOption if False: # For type annotation - from typing import Any, Dict, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.util.docfields import Field # NOQA - from sphinx.util.typing import DirectiveOption # NOQA + from sphinx.application import Sphinx # RE to strip backslash escapes @@ -70,8 +71,7 @@ class ObjectDescription(SphinxDirective): # Warning: this might be removed in future version. Don't touch this from extensions. _doc_field_type_map = {} # type: Dict[str, Tuple[Field, bool]] - def get_field_type_map(self): - # type: () -> Dict[str, Tuple[Field, bool]] + def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]: if self._doc_field_type_map == {}: for field in self.doc_field_types: for name in field.names: @@ -84,8 +84,7 @@ class ObjectDescription(SphinxDirective): return self._doc_field_type_map - def get_signatures(self): - # type: () -> List[str] + def get_signatures(self) -> List[str]: """ Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line. @@ -96,8 +95,7 @@ class ObjectDescription(SphinxDirective): # remove backslashes to support (dummy) escapes; helps Vim highlighting return [strip_backslash_re.sub(r'\1', line.strip()) for line in lines] - def handle_signature(self, sig, signode): - # type: (str, addnodes.desc_signature) -> Any + def handle_signature(self, sig: str, signode: 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 @@ -109,8 +107,7 @@ class ObjectDescription(SphinxDirective): """ raise ValueError - def add_target_and_index(self, name, sig, signode): - # type: (Any, str, addnodes.desc_signature) -> None + def add_target_and_index(self, name: Any, sig: str, signode: desc_signature) -> None: """ Add cross-reference IDs and entries to self.indexnode, if applicable. @@ -118,24 +115,21 @@ class ObjectDescription(SphinxDirective): """ return # do nothing by default - def before_content(self): - # type: () -> None + def before_content(self) -> None: """ Called before parsing content. Used to set information about the current directive context on the build environment. """ pass - def after_content(self): - # type: () -> None + def after_content(self) -> None: """ Called after parsing content. Used to reset information about the current directive context on the build environment. """ pass - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: """ Main directive entry function, called by docutils upon encountering the directive. @@ -212,8 +206,7 @@ class DefaultRole(SphinxDirective): optional_arguments = 1 final_argument_whitespace = False - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: if not self.arguments: docutils.unregister_role('') return [] @@ -244,8 +237,7 @@ class DefaultDomain(SphinxDirective): final_argument_whitespace = False option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: domain_name = self.arguments[0].lower() # if domain_name not in env.domains: # # try searching by label @@ -294,8 +286,7 @@ deprecated_alias('sphinx.directives', DescDirective = ObjectDescription -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: "Sphinx") -> Dict[str, 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 ff21bcdab..aa5192f78 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -9,12 +9,15 @@ import sys import warnings from difflib import unified_diff +from typing import Any, Dict, List, Tuple from docutils import nodes +from docutils.nodes import Element, Node from docutils.parsers.rst import directives from docutils.statemachine import StringList from sphinx import addnodes +from sphinx.config import Config from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.locale import __ from sphinx.util import logging @@ -23,9 +26,7 @@ from sphinx.util.docutils import SphinxDirective if False: # For type annotation - from typing import Any, Dict, List, Tuple # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA + from sphinx.application import Sphinx logger = logging.getLogger(__name__) @@ -45,8 +46,7 @@ class Highlight(SphinxDirective): 'linenothreshold': directives.positive_int, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: language = self.arguments[0].strip() linenothreshold = self.options.get('linenothreshold', sys.maxsize) force = 'force' in self.options @@ -60,16 +60,14 @@ class Highlight(SphinxDirective): class HighlightLang(Highlight): """highlightlang directive (deprecated)""" - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: warnings.warn('highlightlang directive is deprecated. ' 'Please use highlight directive instead.', RemovedInSphinx40Warning, stacklevel=2) return super().run() -def dedent_lines(lines, dedent, location=None): - # type: (List[str], int, Tuple[str, int]) -> List[str] +def dedent_lines(lines: List[str], dedent: int, location: Tuple[str, int] = None) -> List[str]: if not dedent: return lines @@ -86,8 +84,7 @@ def dedent_lines(lines, dedent, location=None): return new_lines -def container_wrapper(directive, literal_node, caption): - # type: (SphinxDirective, nodes.Node, str) -> nodes.container +def container_wrapper(directive: SphinxDirective, literal_node: Node, caption: str) -> nodes.container: # NOQA container_node = nodes.container('', literal_block=True, classes=['literal-block-wrapper']) parsed = nodes.Element() @@ -129,8 +126,7 @@ class CodeBlock(SphinxDirective): 'name': directives.unchanged, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: document = self.state.document code = '\n'.join(self.content) location = self.state_machine.get_source_and_line(self.lineno) @@ -157,7 +153,7 @@ class CodeBlock(SphinxDirective): lines = dedent_lines(lines, self.options['dedent'], location=location) code = '\n'.join(lines) - literal = nodes.literal_block(code, code) # type: nodes.Element + literal = nodes.literal_block(code, code) # type: Element if 'linenos' in self.options or 'lineno-start' in self.options: literal['linenos'] = True literal['classes'] += self.options.get('class', []) @@ -209,8 +205,7 @@ class LiteralIncludeReader: ('diff', 'end-at'), ] - def __init__(self, filename, options, config): - # type: (str, Dict, Config) -> None + def __init__(self, filename: str, options: Dict, config: Config) -> None: self.filename = filename self.options = options self.encoding = options.get('encoding', config.source_encoding) @@ -218,15 +213,13 @@ class LiteralIncludeReader: self.parse_options() - def parse_options(self): - # type: () -> None + def parse_options(self) -> None: for option1, option2 in self.INVALID_OPTIONS_PAIR: if option1 in self.options and option2 in self.options: raise ValueError(__('Cannot use both "%s" and "%s" options') % (option1, option2)) - def read_file(self, filename, location=None): - # type: (str, Tuple[str, int]) -> List[str] + def read_file(self, filename: str, location: Tuple[str, int] = None) -> List[str]: try: with open(filename, encoding=self.encoding, errors='strict') as f: text = f.read() @@ -241,8 +234,7 @@ class LiteralIncludeReader: 'be wrong, try giving an :encoding: option') % (self.encoding, filename)) - def read(self, location=None): - # type: (Tuple[str, int]) -> Tuple[str, int] + def read(self, location: Tuple[str, int] = None) -> Tuple[str, int]: if 'diff' in self.options: lines = self.show_diff() else: @@ -259,16 +251,14 @@ class LiteralIncludeReader: return ''.join(lines), len(lines) - def show_diff(self, location=None): - # type: (Tuple[str, int]) -> List[str] + def show_diff(self, location: Tuple[str, int] = None) -> List[str]: new_lines = self.read_file(self.filename) old_filename = self.options.get('diff') old_lines = self.read_file(old_filename) diff = unified_diff(old_lines, new_lines, old_filename, self.filename) return list(diff) - def pyobject_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def pyobject_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: pyobject = self.options.get('pyobject') if pyobject: from sphinx.pycode import ModuleAnalyzer @@ -286,8 +276,7 @@ class LiteralIncludeReader: return lines - def lines_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def lines_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: linespec = self.options.get('lines') if linespec: linelist = parselinenos(linespec, len(lines)) @@ -311,8 +300,7 @@ class LiteralIncludeReader: return lines - def start_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def start_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: if 'start-at' in self.options: start = self.options.get('start-at') inclusive = False @@ -343,8 +331,7 @@ class LiteralIncludeReader: return lines - def end_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def end_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: if 'end-at' in self.options: end = self.options.get('end-at') inclusive = True @@ -371,24 +358,21 @@ class LiteralIncludeReader: return lines - def prepend_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def prepend_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: prepend = self.options.get('prepend') if prepend: lines.insert(0, prepend + '\n') return lines - def append_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def append_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: append = self.options.get('append') if append: lines.append(append + '\n') return lines - def dedent_filter(self, lines, location=None): - # type: (List[str], Tuple[str, int]) -> List[str] + def dedent_filter(self, lines: List[str], location: Tuple[str, int] = None) -> List[str]: if 'dedent' in self.options: return dedent_lines(lines, self.options.get('dedent'), location=location) else: @@ -430,8 +414,7 @@ class LiteralInclude(SphinxDirective): 'diff': directives.unchanged_required, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: document = self.state.document if not document.settings.file_insertion_enabled: return [document.reporter.warning('File insertion disabled', @@ -449,7 +432,7 @@ class LiteralInclude(SphinxDirective): reader = LiteralIncludeReader(filename, self.options, self.config) text, lines = reader.read(location=location) - retnode = nodes.literal_block(text, text, source=filename) # type: nodes.Element + retnode = nodes.literal_block(text, text, source=filename) # type: Element retnode['force'] = 'force' in self.options self.set_source_info(retnode) if self.options.get('diff'): # if diff is set, set udiff @@ -483,8 +466,7 @@ class LiteralInclude(SphinxDirective): return [document.reporter.warning(exc, line=self.lineno)] -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: "Sphinx") -> Dict[str, Any]: directives.register_directive('highlight', Highlight) directives.register_directive('highlightlang', HighlightLang) directives.register_directive('code-block', CodeBlock) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 5863541bf..1113e8241 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -7,9 +7,11 @@ """ import re +from typing import Any, Dict, List from typing import cast from docutils import nodes +from docutils.nodes import Element, Node from docutils.parsers.rst import directives from docutils.parsers.rst.directives.admonitions import BaseAdmonition from docutils.parsers.rst.directives.misc import Class @@ -25,15 +27,13 @@ from sphinx.util.nodes import explicit_title_re, process_index_entry if False: # For type annotation - from typing import Any, Dict, List # NOQA - from sphinx.application import Sphinx # NOQA + from sphinx.application import Sphinx glob_re = re.compile(r'.*[*?\[].*') -def int_or_nothing(argument): - # type: (str) -> int +def int_or_nothing(argument: str) -> int: if not argument: return 999 return int(argument) @@ -60,8 +60,7 @@ class TocTree(SphinxDirective): 'reversed': directives.flag, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: subnode = addnodes.toctree() subnode['parent'] = self.env.docname @@ -160,11 +159,10 @@ class Author(SphinxDirective): final_argument_whitespace = True option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: if not self.config.show_authors: return [] - para = nodes.paragraph(translatable=False) # type: nodes.Element + para = nodes.paragraph(translatable=False) # type: Element emph = nodes.emphasis() para += emph if self.name == 'sectionauthor': @@ -179,7 +177,7 @@ class Author(SphinxDirective): inodes, messages = self.state.inline_text(self.arguments[0], self.lineno) emph.extend(inodes) - ret = [para] # type: List[nodes.Node] + ret = [para] # type: List[Node] ret += messages return ret @@ -194,8 +192,7 @@ class Index(SphinxDirective): final_argument_whitespace = True option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: arguments = self.arguments[0].split('\n') targetid = 'index-%s' % self.env.new_serialno('index') targetnode = nodes.target('', '', ids=[targetid]) @@ -226,8 +223,7 @@ class TabularColumns(SphinxDirective): final_argument_whitespace = True option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: node = addnodes.tabular_col_spec() node['spec'] = self.arguments[0] self.set_source_info(node) @@ -244,15 +240,14 @@ class Centered(SphinxDirective): final_argument_whitespace = True option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: if not self.arguments: return [] - subnode = addnodes.centered() # type: nodes.Element + subnode = addnodes.centered() # type: Element inodes, messages = self.state.inline_text(self.arguments[0], self.lineno) subnode.extend(inodes) - ret = [subnode] # type: List[nodes.Node] + ret = [subnode] # type: List[Node] ret += messages return ret @@ -267,8 +262,7 @@ class Acks(SphinxDirective): final_argument_whitespace = False option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: node = addnodes.acks() node.document = self.state.document self.state.nested_parse(self.content, self.content_offset, node) @@ -291,8 +285,7 @@ class HList(SphinxDirective): 'columns': int, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: ncolumns = self.options.get('columns', 2) node = nodes.paragraph() node.document = self.state.document @@ -325,8 +318,7 @@ class Only(SphinxDirective): final_argument_whitespace = True option_spec = {} # type: Dict - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: node = addnodes.only() node.document = self.state.document self.set_source_info(node) @@ -380,8 +372,7 @@ class Include(BaseInclude, SphinxDirective): "correctly", i.e. relative to source directory. """ - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: if self.arguments[0].startswith('<') and \ self.arguments[0].endswith('>'): # docutils "standard" includes, do not do path processing @@ -392,8 +383,7 @@ class Include(BaseInclude, SphinxDirective): return super().run() -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: "Sphinx") -> Dict[str, Any]: directives.register_directive('toctree', TocTree) directives.register_directive('sectionauthor', Author) directives.register_directive('moduleauthor', Author) diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py index 189e1f7e3..b4b1664ab 100644 --- a/sphinx/directives/patches.py +++ b/sphinx/directives/patches.py @@ -6,10 +6,11 @@ :license: BSD, see LICENSE for details. """ +from typing import Any, Dict, List, Tuple from typing import cast from docutils import nodes -from docutils.nodes import make_id +from docutils.nodes import Node, make_id, system_message from docutils.parsers.rst import directives from docutils.parsers.rst.directives import images, html, tables @@ -20,8 +21,7 @@ from sphinx.util.nodes import set_source_info if False: # For type annotation - from typing import Dict, List, Tuple # NOQA - from sphinx.application import Sphinx # NOQA + from sphinx.application import Sphinx class Figure(images.Figure): @@ -29,8 +29,7 @@ class Figure(images.Figure): instead of the image node. """ - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: name = self.options.pop('name', None) result = super().run() if len(result) == 2 or isinstance(result[0], nodes.system_message): @@ -52,8 +51,7 @@ class Figure(images.Figure): class Meta(html.Meta, SphinxDirective): - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: result = super().run() for node in result: if (isinstance(node, nodes.pending) and @@ -74,8 +72,7 @@ class RSTTable(tables.RSTTable): Only for docutils-0.13 or older version.""" - def make_title(self): - # type: () -> Tuple[nodes.title, List[nodes.system_message]] + def make_title(self) -> Tuple[nodes.title, List[system_message]]: title, message = super().make_title() if title: set_source_info(self, title) @@ -88,8 +85,7 @@ class CSVTable(tables.CSVTable): Only for docutils-0.13 or older version.""" - def make_title(self): - # type: () -> Tuple[nodes.title, List[nodes.system_message]] + def make_title(self) -> Tuple[nodes.title, List[system_message]]: title, message = super().make_title() if title: set_source_info(self, title) @@ -102,8 +98,7 @@ class ListTable(tables.ListTable): Only for docutils-0.13 or older version.""" - def make_title(self): - # type: () -> Tuple[nodes.title, List[nodes.system_message]] + def make_title(self) -> Tuple[nodes.title, List[system_message]]: title, message = super().make_title() if title: set_source_info(self, title) @@ -125,8 +120,7 @@ class Code(SphinxDirective): } has_content = True - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: self.assert_has_content() code = '\n'.join(self.content) @@ -169,8 +163,7 @@ class MathDirective(SphinxDirective): 'nowrap': directives.flag, } - def run(self): - # type: () -> List[nodes.Node] + def run(self) -> List[Node]: latex = '\n'.join(self.content) if self.arguments and self.arguments[0]: latex = self.arguments[0] + '\n\n' + latex @@ -184,12 +177,11 @@ class MathDirective(SphinxDirective): self.add_name(node) self.set_source_info(node) - ret = [node] # type: List[nodes.Node] + ret = [node] # type: List[Node] self.add_target(ret) return ret - def add_target(self, ret): - # type: (List[nodes.Node]) -> None + def add_target(self, ret: List[Node]) -> None: node = cast(nodes.math_block, ret[0]) # assign label automatically if math_number_all enabled @@ -216,8 +208,7 @@ class MathDirective(SphinxDirective): self.state_machine.reporter.warning(exc, line=self.lineno) -def setup(app): - # type: (Sphinx) -> Dict +def setup(app: "Sphinx") -> Dict[str, Any]: directives.register_directive('figure', Figure) directives.register_directive('meta', Meta) directives.register_directive('table', RSTTable) diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index dd6652c19..2a9a120ef 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -337,7 +337,8 @@ class PyObject(ObjectDescription): self.state.document.note_explicit_target(signode) domain = cast(PythonDomain, self.env.get_domain('py')) - domain.note_object(fullname, self.objtype) + domain.note_object(fullname, self.objtype, + location=(self.env.docname, self.lineno)) indextext = self.get_index_text(modname, name_cls) if indextext: @@ -752,7 +753,7 @@ class PyModule(SphinxDirective): self.options.get('synopsis', ''), self.options.get('platform', ''), 'deprecated' in self.options) - domain.note_object(modname, 'module') + domain.note_object(modname, 'module', location=(self.env.docname, self.lineno)) targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True) diff --git a/sphinx/environment/collectors/asset.py b/sphinx/environment/collectors/asset.py index 572dea7a4..fed8280c1 100644 --- a/sphinx/environment/collectors/asset.py +++ b/sphinx/environment/collectors/asset.py @@ -137,7 +137,7 @@ class DownloadFileCollector(EnvironmentCollector): logger.warning(__('download file not readable: %s') % filename, location=node, type='download', subtype='not_readable') continue - node['filename'] = app.env.dlfiles.add_file(app.env.docname, filename) + node['filename'] = app.env.dlfiles.add_file(app.env.docname, rel_filename) def setup(app): diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index f66269a6b..7172553ac 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -549,10 +549,8 @@ class Documenter: if self.analyzer: attr_docs = self.analyzer.find_attr_docs() - tagorder = self.analyzer.tagorder else: attr_docs = {} - tagorder = {} # process members and determine which to skip for (membername, member) in members: @@ -582,13 +580,12 @@ class Documenter: membername in self.options.special_members: keep = has_doc or self.options.undoc_members elif (namespace, membername) in attr_docs: - has_doc = bool(attr_docs[namespace, membername]) if want_all and membername.startswith('_'): # ignore members whose name starts with _ by default - keep = has_doc and self.options.private_members + keep = self.options.private_members else: # keep documented attributes - keep = has_doc + keep = True isattr = True elif want_all and membername.startswith('_'): # ignore members whose name starts with _ by default @@ -597,8 +594,6 @@ class Documenter: else: # ignore undocumented members if :undoc-members: is not given keep = has_doc or self.options.undoc_members - # module top level item or not - isattr = membername in tagorder # give the user a chance to decide whether this member # should be skipped @@ -1296,10 +1291,6 @@ class DataDocumenter(ModuleLevelDocumenter): return self.get_attr(self.parent or self.object, '__module__', None) \ or self.modname - def get_doc(self, encoding=None, ignore=1): - # type: (str, int) -> List[List[str]] - return [] - class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: ignore """ diff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py index 37bdae8a9..0c6f47039 100644 --- a/sphinx/ext/autodoc/importer.py +++ b/sphinx/ext/autodoc/importer.py @@ -128,7 +128,7 @@ def get_object_members(subject, objpath, attrgetter, analyzer=None): members[name] = Attribute(name, True, value) # members in __slots__ - if isclass(subject) and hasattr(subject, '__slots__'): + if isclass(subject) and getattr(subject, '__slots__', None) is not None: from sphinx.ext.autodoc import SLOTSATTR for name in subject.__slots__: diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 262b36cea..6eb0fea9b 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -754,7 +754,6 @@ def process_generate_options(app): imported_members = app.config.autosummary_imported_members with mock(app.config.autosummary_mock_imports): generate_autosummary_docs(genfiles, builder=app.builder, - warn=logger.warning, info=logger.info, suffix=suffix, base_path=app.srcdir, app=app, imported_members=imported_members) diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index ba1ec219a..4a699dd9f 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -23,6 +23,7 @@ import os import pydoc import re import sys +import warnings from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound from jinja2.sandbox import SandboxedEnvironment @@ -30,10 +31,12 @@ from jinja2.sandbox import SandboxedEnvironment import sphinx.locale from sphinx import __display_version__ from sphinx import package_dir +from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.ext.autosummary import import_by_name, get_documenter from sphinx.jinja2glue import BuiltinTemplateLoader from sphinx.locale import __ from sphinx.registry import SphinxComponentRegistry +from sphinx.util import logging from sphinx.util import rst from sphinx.util.inspect import safe_getattr from sphinx.util.osutil import ensuredir @@ -45,12 +48,17 @@ if False: from sphinx.ext.autodoc import Documenter # NOQA +logger = logging.getLogger(__name__) + + class DummyApplication: """Dummy Application class for sphinx-autogen command.""" def __init__(self): # type: () -> None self.registry = SphinxComponentRegistry() + self.messagelog = [] # type: List[str] + self.verbosity = 0 def setup_documenters(app): @@ -127,10 +135,20 @@ class AutosummaryRenderer: # -- Generating output --------------------------------------------------------- def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', - warn=_simple_warn, info=_simple_info, - base_path=None, builder=None, template_dir=None, - imported_members=False, app=None): + warn=None, info=None, base_path=None, builder=None, + template_dir=None, imported_members=False, app=None): # type: (List[str], str, str, Callable, Callable, str, Builder, str, bool, Any) -> None + if info: + warnings.warn('info argument for generate_autosummary_docs() is deprecated.', + RemovedInSphinx40Warning) + else: + info = logger.info + + if warn: + warnings.warn('warn argument for generate_autosummary_docs() is deprecated.', + RemovedInSphinx40Warning) + else: + warn = logger.warning showed_sources = list(sorted(sources)) if len(showed_sources) > 20: @@ -221,7 +239,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', get_members(obj, {'attribute', 'property'}) parts = name.split('.') - if doc.objtype in ('method', 'attribute'): + if doc.objtype in ('method', 'attribute', 'property'): mod_name = '.'.join(parts[:-2]) cls_name = parts[-2] obj_name = '.'.join(parts[-2:]) @@ -420,6 +438,7 @@ def main(argv=sys.argv[1:]): sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx') app = DummyApplication() + logging.setup(app, sys.stdout, sys.stderr) # type: ignore setup_documenters(app) args = get_parser().parse_args(argv) generate_autosummary_docs(args.source_file, args.output_dir, diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 0fea99fb8..7ff184961 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -328,6 +328,9 @@ class GoogleDocstring: def _escape_args_and_kwargs(self, name): # type: (str) -> str + if name.endswith('_'): + name = name[:-1] + r'\_' + if name[:2] == '**': return r'\*\*' + name[2:] elif name[:1] == '*': @@ -555,7 +558,7 @@ class GoogleDocstring: # type: () -> None self._parsed_lines = self._consume_empty() - if self._name and (self._what == 'attribute' or self._what == 'data'): + if self._name and self._what in ('attribute', 'data', 'property'): # Implicit stop using StopIteration no longer allowed in # Python 3.7; see PEP 479 res = [] # type: List[str] diff --git a/sphinx/locale/ar/LC_MESSAGES/sphinx.po b/sphinx/locale/ar/LC_MESSAGES/sphinx.po index 2452773d1..48df63fc1 100644 --- a/sphinx/locale/ar/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ar/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/bn/LC_MESSAGES/sphinx.po b/sphinx/locale/bn/LC_MESSAGES/sphinx.po index 897bc0d6b..89c81694d 100644 --- a/sphinx/locale/bn/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/bn/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ca/LC_MESSAGES/sphinx.po b/sphinx/locale/ca/LC_MESSAGES/sphinx.po index 16c5dd220..dcb638253 100644 --- a/sphinx/locale/ca/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ca/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/cak/LC_MESSAGES/sphinx.po b/sphinx/locale/cak/LC_MESSAGES/sphinx.po index 0c652d72f..338d62059 100644 --- a/sphinx/locale/cak/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cak/LC_MESSAGES/sphinx.po @@ -1448,8 +1448,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nWe xetz'ib'an ri wuj pa jun ch'abäl man Q'anch' ta,\nyatikïr nacha' jun chïk runuk'unem ch'ab'äl wawe' chi Sphinx tiq'ax\nruch'abäl ri wuj xtik'iyij pa ri ch'ab'äl re.\n\nChi natz'u rucholajem runuk'unem ch'ab'äl k'o chïk pa Sphinx, tab'e pa\nhttp://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nWe xetz'ib'an ri wuj pa jun ch'abäl man Q'anch' ta,\nyatikïr nacha' jun chïk runuk'unem ch'ab'äl wawe' chi Sphinx tiq'ax\nruch'abäl ri wuj xtik'iyij pa ri ch'ab'äl re.\n\nChi natz'u rucholajem runuk'unem ch'ab'äl k'o chïk pa Sphinx, tab'e pa\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.po b/sphinx/locale/cs/LC_MESSAGES/sphinx.po index ed2dbfe76..825dc2166 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/cy/LC_MESSAGES/sphinx.po b/sphinx/locale/cy/LC_MESSAGES/sphinx.po index bc00d3b12..67faadf88 100644 --- a/sphinx/locale/cy/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cy/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/da/LC_MESSAGES/sphinx.po b/sphinx/locale/da/LC_MESSAGES/sphinx.po index b7d6f2a4e..721553d0f 100644 --- a/sphinx/locale/da/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/da/LC_MESSAGES/sphinx.po @@ -1450,7 +1450,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.po b/sphinx/locale/de/LC_MESSAGES/sphinx.po index 96b24539d..cac01042e 100644 --- a/sphinx/locale/de/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/de/LC_MESSAGES/sphinx.po @@ -1451,7 +1451,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/el/LC_MESSAGES/sphinx.po b/sphinx/locale/el/LC_MESSAGES/sphinx.po index 2586e7e27..54a19f5fd 100644 --- a/sphinx/locale/el/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/el/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/eo/LC_MESSAGES/sphinx.po b/sphinx/locale/eo/LC_MESSAGES/sphinx.po index 62b11e910..bd6def59d 100644 --- a/sphinx/locale/eo/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/eo/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.po b/sphinx/locale/es/LC_MESSAGES/sphinx.po index 1b877fdd1..a54f40ef8 100644 --- a/sphinx/locale/es/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/es/LC_MESSAGES/sphinx.po @@ -1454,8 +1454,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nSi los documentos están escritos en un idioma distinto al Inglés,\npuedes seleccionar un idioma aqui a través de su código. Sphinx traducirá\nlos textos que genere en dicho idioma.\n\nPara una lista de los códigos soportados visita: \nhttp://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nSi los documentos están escritos en un idioma distinto al Inglés,\npuedes seleccionar un idioma aqui a través de su código. Sphinx traducirá\nlos textos que genere en dicho idioma.\n\nPara una lista de los códigos soportados visita: \nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/et/LC_MESSAGES/sphinx.po b/sphinx/locale/et/LC_MESSAGES/sphinx.po index 2237960ae..abc73f875 100644 --- a/sphinx/locale/et/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/et/LC_MESSAGES/sphinx.po @@ -1451,8 +1451,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nKui su dokumendid pole kirjutatud inglise keeles, siis võid siin määrata\nkeele vastava keelekoodi abil. Sel juhul tõlgib Sphinx enda genereeritud\nteksti vastavasse keelde.\n\nToetatud keelekoodide kohta vaata\nhttp://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nKui su dokumendid pole kirjutatud inglise keeles, siis võid siin määrata\nkeele vastava keelekoodi abil. Sel juhul tõlgib Sphinx enda genereeritud\nteksti vastavasse keelde.\n\nToetatud keelekoodide kohta vaata\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/eu/LC_MESSAGES/sphinx.po b/sphinx/locale/eu/LC_MESSAGES/sphinx.po index 6ad672fa5..02ac72526 100644 --- a/sphinx/locale/eu/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/eu/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/fa/LC_MESSAGES/sphinx.po b/sphinx/locale/fa/LC_MESSAGES/sphinx.po index c80f85f81..e9d5a9934 100644 --- a/sphinx/locale/fa/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/fa/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.po b/sphinx/locale/fi/LC_MESSAGES/sphinx.po index ee28d41a7..d9832746a 100644 --- a/sphinx/locale/fi/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.po b/sphinx/locale/fr/LC_MESSAGES/sphinx.po index 6762dc21e..0516db6d5 100644 --- a/sphinx/locale/fr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.po @@ -1465,8 +1465,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nSi le documents doit être écrit dans une autre langue que l'anglais, vous pouvez choisir une langue ici en saisissant son code. Sphinx traduira le texte qu'il génère dans cette langue. Pour une liste des codes supportés : http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nSi le documents doit être écrit dans une autre langue que l'anglais, vous pouvez choisir une langue ici en saisissant son code. Sphinx traduira le texte qu'il génère dans cette langue. Pour une liste des codes supportés : https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/he/LC_MESSAGES/sphinx.po b/sphinx/locale/he/LC_MESSAGES/sphinx.po index 2e222d711..7cf0d6e87 100644 --- a/sphinx/locale/he/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/he/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/hi/LC_MESSAGES/sphinx.po b/sphinx/locale/hi/LC_MESSAGES/sphinx.po index 6a95b6be4..0668fb5b9 100644 --- a/sphinx/locale/hi/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/hi/LC_MESSAGES/sphinx.po @@ -1449,8 +1449,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nयदि प्रलेखों को अंग्रेजी के अलावा अन्य किसी भाषा में लिखा जाना है,\nतो यहाँ पर आप भाषा का कूटशब्द दे सकते हैं. स्फिंक्स तदपुरांत,\nजो वाक्यांश बनाता है उसे उस भाषा में अनुवादित करेगा.\n\nमान्य भाषा कूटशब्द सूची यहाँ पर देखें\nhttp://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nयदि प्रलेखों को अंग्रेजी के अलावा अन्य किसी भाषा में लिखा जाना है,\nतो यहाँ पर आप भाषा का कूटशब्द दे सकते हैं. स्फिंक्स तदपुरांत,\nजो वाक्यांश बनाता है उसे उस भाषा में अनुवादित करेगा.\n\nमान्य भाषा कूटशब्द सूची यहाँ पर देखें\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/hi_IN/LC_MESSAGES/sphinx.po b/sphinx/locale/hi_IN/LC_MESSAGES/sphinx.po index 3168863d3..81f7b7cfc 100644 --- a/sphinx/locale/hi_IN/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/hi_IN/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/hr/LC_MESSAGES/sphinx.po b/sphinx/locale/hr/LC_MESSAGES/sphinx.po index df4eea180..71fa20ac8 100644 --- a/sphinx/locale/hr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/hr/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/hu/LC_MESSAGES/sphinx.po b/sphinx/locale/hu/LC_MESSAGES/sphinx.po index 8d172470f..c64a9a59c 100644 --- a/sphinx/locale/hu/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/hu/LC_MESSAGES/sphinx.po @@ -1452,7 +1452,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/id/LC_MESSAGES/sphinx.po b/sphinx/locale/id/LC_MESSAGES/sphinx.po index f4ae7cc2c..bd323c2fb 100644 --- a/sphinx/locale/id/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/id/LC_MESSAGES/sphinx.po @@ -1451,7 +1451,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.po b/sphinx/locale/it/LC_MESSAGES/sphinx.po index baec45df5..19a951be0 100644 --- a/sphinx/locale/it/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.po @@ -1452,7 +1452,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.po b/sphinx/locale/ja/LC_MESSAGES/sphinx.po index 01a10f634..93f03c07f 100644 --- a/sphinx/locale/ja/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ja/LC_MESSAGES/sphinx.po @@ -1460,8 +1460,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nドキュメントを英語以外の言語で書く場合は、\n 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。\n\nサポートされているコードのリストについては、\nhttp://sphinx-doc.org/config.html#confval-language を参照してください。" +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nドキュメントを英語以外の言語で書く場合は、\n 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。\n\nサポートされているコードのリストについては、\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。" #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/ko/LC_MESSAGES/sphinx.po b/sphinx/locale/ko/LC_MESSAGES/sphinx.po index b88f11d2a..50a7f7448 100644 --- a/sphinx/locale/ko/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ko/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/lt/LC_MESSAGES/sphinx.po b/sphinx/locale/lt/LC_MESSAGES/sphinx.po index 9d9707c71..908d02a22 100644 --- a/sphinx/locale/lt/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/lt/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/lv/LC_MESSAGES/sphinx.po b/sphinx/locale/lv/LC_MESSAGES/sphinx.po index bcfda0332..4b0385fb3 100644 --- a/sphinx/locale/lv/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/lv/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/mk/LC_MESSAGES/sphinx.po b/sphinx/locale/mk/LC_MESSAGES/sphinx.po index fc4a16386..4a17380ca 100644 --- a/sphinx/locale/mk/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/mk/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/nb_NO/LC_MESSAGES/sphinx.po b/sphinx/locale/nb_NO/LC_MESSAGES/sphinx.po index 77db4ca5a..53b038c25 100644 --- a/sphinx/locale/nb_NO/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/nb_NO/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ne/LC_MESSAGES/sphinx.po b/sphinx/locale/ne/LC_MESSAGES/sphinx.po index e87d8a887..5949d78a9 100644 --- a/sphinx/locale/ne/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ne/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.po b/sphinx/locale/nl/LC_MESSAGES/sphinx.po index a52f5ecaa..02b3d2786 100644 --- a/sphinx/locale/nl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/nl/LC_MESSAGES/sphinx.po @@ -1453,7 +1453,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.po b/sphinx/locale/pl/LC_MESSAGES/sphinx.po index 6128a6de6..82903c2de 100644 --- a/sphinx/locale/pl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pl/LC_MESSAGES/sphinx.po @@ -1451,8 +1451,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\nJeśli dokumenty mają być pisane w języku innym niż angielski,\nmożesz tutaj wybrać język przez jego kod. Sphinx następnie\nprzetłumaczy tekst, który generuje, na ten język.\n\nListę wspieranych kodów znajdziesz na\nhttp://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\nJeśli dokumenty mają być pisane w języku innym niż angielski,\nmożesz tutaj wybrać język przez jego kod. Sphinx następnie\nprzetłumaczy tekst, który generuje, na ten język.\n\nListę wspieranych kodów znajdziesz na\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/pt/LC_MESSAGES/sphinx.po b/sphinx/locale/pt/LC_MESSAGES/sphinx.po index 058d87dde..47ce06ee0 100644 --- a/sphinx/locale/pt/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pt/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po index e54e9288d..4715e32e7 100644 --- a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po @@ -1451,7 +1451,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/pt_PT/LC_MESSAGES/sphinx.po b/sphinx/locale/pt_PT/LC_MESSAGES/sphinx.po index b896e2779..75e9f3135 100644 --- a/sphinx/locale/pt_PT/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pt_PT/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ro/LC_MESSAGES/sphinx.po b/sphinx/locale/ro/LC_MESSAGES/sphinx.po index a0a850740..1ac7ef043 100644 --- a/sphinx/locale/ro/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ro/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ru/LC_MESSAGES/sphinx.po b/sphinx/locale/ru/LC_MESSAGES/sphinx.po index 4ccab39b5..f9cdfba3a 100644 --- a/sphinx/locale/ru/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ru/LC_MESSAGES/sphinx.po @@ -1453,7 +1453,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/si/LC_MESSAGES/sphinx.po b/sphinx/locale/si/LC_MESSAGES/sphinx.po index 5852306a2..59e13eaed 100644 --- a/sphinx/locale/si/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/si/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sk/LC_MESSAGES/sphinx.po b/sphinx/locale/sk/LC_MESSAGES/sphinx.po index 70275b891..90213cf37 100644 --- a/sphinx/locale/sk/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sk/LC_MESSAGES/sphinx.po @@ -1450,7 +1450,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.po b/sphinx/locale/sl/LC_MESSAGES/sphinx.po index 0353526c0..3d94d0f54 100644 --- a/sphinx/locale/sl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sl/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sphinx.pot b/sphinx/locale/sphinx.pot index 07f4216c4..c4f9a54fb 100644 --- a/sphinx/locale/sphinx.pot +++ b/sphinx/locale/sphinx.pot @@ -1461,7 +1461,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sr/LC_MESSAGES/sphinx.po b/sphinx/locale/sr/LC_MESSAGES/sphinx.po index e13bb82d9..1e99514a3 100644 --- a/sphinx/locale/sr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sr/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sr@latin/LC_MESSAGES/sphinx.po b/sphinx/locale/sr@latin/LC_MESSAGES/sphinx.po index 941497ee1..0fe6b5ca7 100644 --- a/sphinx/locale/sr@latin/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sr@latin/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sr_RS/LC_MESSAGES/sphinx.po b/sphinx/locale/sr_RS/LC_MESSAGES/sphinx.po index 3e78b6f2b..8c95c6cd9 100644 --- a/sphinx/locale/sr_RS/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sr_RS/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/sv/LC_MESSAGES/sphinx.po b/sphinx/locale/sv/LC_MESSAGES/sphinx.po index 8f26be6f1..d6004ba71 100644 --- a/sphinx/locale/sv/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sv/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ta/LC_MESSAGES/sphinx.po b/sphinx/locale/ta/LC_MESSAGES/sphinx.po index 9d42b0728..ef9ac7d92 100644 --- a/sphinx/locale/ta/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ta/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/tr/LC_MESSAGES/sphinx.po b/sphinx/locale/tr/LC_MESSAGES/sphinx.po index 4c1f310c4..c6dac42b8 100644 --- a/sphinx/locale/tr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/tr/LC_MESSAGES/sphinx.po @@ -1449,7 +1449,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po index 9506624c0..fd08c96bf 100644 --- a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/ur/LC_MESSAGES/sphinx.po b/sphinx/locale/ur/LC_MESSAGES/sphinx.po index 1464969b7..975cd09ca 100644 --- a/sphinx/locale/ur/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ur/LC_MESSAGES/sphinx.po @@ -1447,7 +1447,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/vi/LC_MESSAGES/sphinx.po b/sphinx/locale/vi/LC_MESSAGES/sphinx.po index 01bae6d8c..f2e3e766b 100644 --- a/sphinx/locale/vi/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/vi/LC_MESSAGES/sphinx.po @@ -1448,7 +1448,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/locale/zh_CN/LC_MESSAGES/sphinx.po b/sphinx/locale/zh_CN/LC_MESSAGES/sphinx.po index a5c28080b..72429ac95 100644 --- a/sphinx/locale/zh_CN/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/zh_CN/LC_MESSAGES/sphinx.po @@ -1456,8 +1456,8 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." -msgstr "\n如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。\nSphinx 会把内置文本翻译成相应语言的版本。\n\n支持的语言代码列表见：\nhttp://sphinx-doc.org/config.html#confval-language。" +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." +msgstr "\n如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。\nSphinx 会把内置文本翻译成相应语言的版本。\n\n支持的语言代码列表见：\nhttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language。" #: sphinx/cmd/quickstart.py:314 msgid "Project language" diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po index cafadd80a..ebe07553b 100644 --- a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po @@ -1453,7 +1453,7 @@ msgid "" "translate text that it generates into that language.\n" "\n" "For a list of supported codes, see\n" -"http://sphinx-doc.org/config.html#confval-language." +"https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language." msgstr "" #: sphinx/cmd/quickstart.py:314 diff --git a/sphinx/pycode/parser.py b/sphinx/pycode/parser.py index f9489e91a..1746537bb 100644 --- a/sphinx/pycode/parser.py +++ b/sphinx/pycode/parser.py @@ -357,6 +357,17 @@ class VariableCommentPicker(ast.NodeVisitor): except TypeError: pass # this assignment is not new definition! + def visit_Try(self, node): + # type: (ast.Try) -> None + """Handles Try node and processes body and else-clause. + + .. note:: pycode parser ignores objects definition in except-clause. + """ + for subnode in node.body: + self.visit(subnode) + for subnode in node.orelse: + self.visit(subnode) + def visit_ClassDef(self, node): # type: (ast.ClassDef) -> None """Handles ClassDef node and set context.""" diff --git a/sphinx/templates/apidoc/package.rst b/sphinx/templates/apidoc/package.rst index 0026af34c..ed9f669ea 100644 --- a/sphinx/templates/apidoc/package.rst +++ b/sphinx/templates/apidoc/package.rst @@ -40,8 +40,8 @@ Submodules {{- [submodule, "module"] | join(" ") | e | heading(2) }} {% endif %} {{ automodule(submodule, automodule_options) }} -{%- endfor %} -{% endif %} +{% endfor %} +{%- endif %} {% endif %} {%- if not modulefirst and not is_namespace %} diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 6ace6a9ce..184b0d820 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,7 +6,7 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2019/01/12 v1.8.4 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2019/06/04 v2.1.1 LaTeX package (Sphinx markup)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -1444,7 +1444,7 @@ % Some are quite plain % the spx@notice@bordercolor etc are set in the sphinxadmonition environment \newenvironment{sphinxlightbox}{% - \par\allowbreak + \par \noindent{\color{spx@notice@bordercolor}% \rule{\linewidth}{\spx@notice@border}}\par\nobreak {\parskip\z@skip\noindent}% diff --git a/sphinx/themes/classic/static/classic.css_t b/sphinx/themes/classic/static/classic.css_t index 1ee0d2298..a062d6d14 100644 --- a/sphinx/themes/classic/static/classic.css_t +++ b/sphinx/themes/classic/static/classic.css_t @@ -13,6 +13,11 @@ /* -- page layout ----------------------------------------------------------- */ +html { + /* CSS hack for macOS's scrollbar (see #1125) */ + background-color: #FFFFFF; +} + body { font-family: {{ theme_bodyfont }}; font-size: 100%; diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 66c53b37e..1fb7bcde6 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -337,15 +337,13 @@ _coding_re = re.compile(r'coding[:=]\s*([-\w.]+)') def detect_encoding(readline: Callable[[], bytes]) -> str: """Like tokenize.detect_encoding() from Py3k, but a bit simplified.""" - def read_or_stop(): - # type: () -> bytes + def read_or_stop() -> bytes: try: return readline() except StopIteration: return None - def get_normal_name(orig_enc): - # type: (str) -> str + def get_normal_name(orig_enc: str) -> str: """Imitates get_normal_name in tokenizer.c.""" # Only care about the first 12 characters. enc = orig_enc[:12].lower().replace('_', '-') @@ -356,8 +354,7 @@ def detect_encoding(readline: Callable[[], bytes]) -> str: return 'iso-8859-1' return orig_enc - def find_cookie(line): - # type: (bytes) -> str + def find_cookie(line: bytes) -> str: try: line_string = line.decode('ascii') except UnicodeDecodeError: diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index 492c313d0..75ef90350 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -10,23 +10,22 @@ import sys import warnings +from typing import Any, Dict from docutils.utils import get_source_line from sphinx import addnodes +from sphinx.config import Config from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning from sphinx.transforms import SphinxTransform from sphinx.util import import_object if False: # For type annotation - from typing import Any, Dict # NOQA - from sphinx.application import Sphinx # NOQA - from sphinx.config import Config # NOQA + from sphinx.application import Sphinx -def deprecate_source_parsers(app, config): - # type: (Sphinx, Config) -> None +def deprecate_source_parsers(app: "Sphinx", config: Config) -> None: if config.source_parsers: warnings.warn('The config variable "source_parsers" is deprecated. ' 'Please update your extension for the parser and remove the setting.', @@ -37,8 +36,7 @@ def deprecate_source_parsers(app, config): app.add_source_parser(suffix, parser) -def register_application_for_autosummary(app): - # type: (Sphinx) -> None +def register_application_for_autosummary(app: "Sphinx") -> None: """Register application object to autosummary module. Since Sphinx-1.7, documenters and attrgetters are registered into @@ -55,8 +53,7 @@ class IndexEntriesMigrator(SphinxTransform): """Migrating indexentries from old style (4columns) to new style (5columns).""" default_priority = 700 - def apply(self, **kwargs): - # type: (Any) -> None + def apply(self, **kwargs) -> None: for node in self.document.traverse(addnodes.index): for i, entries in enumerate(node['entries']): if len(entries) == 4: @@ -66,8 +63,7 @@ class IndexEntriesMigrator(SphinxTransform): node['entries'][i] = entries + (None,) -def setup(app): - # type: (Sphinx) -> Dict[str, Any] +def setup(app: "Sphinx") -> Dict[str, Any]: app.add_transform(IndexEntriesMigrator) app.connect('config-inited', deprecate_source_parsers) app.connect('builder-inited', register_application_for_autosummary) diff --git a/sphinx/util/console.py b/sphinx/util/console.py index c207d32ac..d73d0563e 100644 --- a/sphinx/util/console.py +++ b/sphinx/util/console.py @@ -11,6 +11,7 @@ import os import re import sys +from typing import Dict try: # check if colorama is installed to support color on Windows @@ -18,23 +19,17 @@ try: except ImportError: colorama = None -if False: - # For type annotation - from typing import Dict # NOQA - _ansi_re = re.compile('\x1b\\[(\\d\\d;){0,2}\\d\\dm') codes = {} # type: Dict[str, str] -def terminal_safe(s): - # type: (str) -> str +def terminal_safe(s: str) -> str: """safely encode a string for printing to the terminal.""" return s.encode('ascii', 'backslashreplace').decode('ascii') -def get_terminal_width(): - # type: () -> int +def get_terminal_width() -> int: """Borrowed from the py lib.""" try: import termios @@ -53,8 +48,7 @@ def get_terminal_width(): _tw = get_terminal_width() -def term_width_line(text): - # type: (str) -> str +def term_width_line(text: str) -> str: if not codes: # if no coloring, don't output fancy backspaces return text + '\n' @@ -63,8 +57,7 @@ def term_width_line(text): return text.ljust(_tw + len(text) - len(_ansi_re.sub('', text))) + '\r' -def color_terminal(): - # type: () -> bool +def color_terminal() -> bool: if sys.platform == 'win32' and colorama is not None: colorama.init() return True @@ -80,21 +73,18 @@ def color_terminal(): return False -def nocolor(): - # type: () -> None +def nocolor() -> None: if sys.platform == 'win32' and colorama is not None: colorama.deinit() codes.clear() -def coloron(): - # type: () -> None +def coloron() -> None: codes.update(_orig_codes) -def colorize(name, text, input_mode=False): - # type: (str, str, bool) -> str - def escseq(name): +def colorize(name: str, text: str, input_mode: bool = False) -> str: + def escseq(name: str) -> str: # Wrap escape sequence with ``\1`` and ``\2`` to let readline know # it is non-printable characters # ref: https://tiswww.case.edu/php/chet/readline/readline.html @@ -109,15 +99,12 @@ def colorize(name, text, input_mode=False): return escseq(name) + text + escseq('reset') -def strip_colors(s): - # type: (str) -> str +def strip_colors(s: str) -> str: return re.compile('\x1b.*?m').sub('', s) -def create_color_func(name): - # type: (str) -> None - def inner(text): - # type: (str) -> str +def create_color_func(name: str) -> None: + def inner(text: str) -> str: return colorize(name, text) globals()[name] = inner diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py index 9b19d229d..f3729c0c9 100644 --- a/sphinx/util/docfields.py +++ b/sphinx/util/docfields.py @@ -10,23 +10,23 @@ """ import warnings -from typing import List, Tuple, cast +from typing import Any, Dict, List, Tuple, Type, Union +from typing import cast from docutils import nodes +from docutils.nodes import Node from sphinx import addnodes from sphinx.deprecation import RemovedInSphinx40Warning +from sphinx.util.typing import TextlikeNode if False: # For type annotation - from typing import Any, Dict, Type, Union # NOQA - from sphinx.directive import ObjectDescription # NOQA - from sphinx.environment import BuildEnvironment # NOQA - from sphinx.util.typing import TextlikeNode # NOQA + from sphinx.environment import BuildEnvironment + from sphinx.directive import ObjectDescription -def _is_single_paragraph(node): - # type: (nodes.field_body) -> bool +def _is_single_paragraph(node: nodes.field_body) -> bool: """True if the node only contains one paragraph (and system messages).""" if len(node) == 0: return False @@ -55,9 +55,8 @@ class Field: is_grouped = False is_typed = False - def __init__(self, name, names=(), label=None, has_arg=True, rolename=None, - bodyrolename=None): - # type: (str, Tuple[str, ...], str, bool, str, str) -> None + def __init__(self, name: str, names: Tuple[str, ...] = (), label: str = None, + has_arg: bool = True, rolename: str = None, bodyrolename: str = None) -> None: self.name = name self.names = names self.label = label @@ -65,15 +64,9 @@ class Field: self.rolename = rolename self.bodyrolename = bodyrolename - def make_xref(self, - rolename, # type: str - domain, # type: str - target, # type: str - innernode=addnodes.literal_emphasis, # type: Type[TextlikeNode] - contnode=None, # type: nodes.Node - env=None, # type: BuildEnvironment - ): - # type: (...) -> nodes.Node + def make_xref(self, rolename: str, domain: str, target: str, + innernode: Type[TextlikeNode] = addnodes.literal_emphasis, + contnode: Node = None, env: "BuildEnvironment" = None) -> Node: if not rolename: return contnode or innernode(target, target) refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False, @@ -83,28 +76,16 @@ class Field: env.get_domain(domain).process_field_xref(refnode) return refnode - def make_xrefs(self, - rolename, # type: str - domain, # type: str - target, # type: str - innernode=addnodes.literal_emphasis, # type: Type[TextlikeNode] - contnode=None, # type: nodes.Node - env=None, # type: BuildEnvironment - ): - # type: (...) -> List[nodes.Node] + def make_xrefs(self, rolename: str, domain: str, target: str, + innernode: Type[TextlikeNode] = addnodes.literal_emphasis, + contnode: Node = None, env: "BuildEnvironment" = None) -> List[Node]: return [self.make_xref(rolename, domain, target, innernode, contnode, env)] - def make_entry(self, fieldarg, content): - # type: (str, List[nodes.Node]) -> Tuple[str, List[nodes.Node]] + def make_entry(self, fieldarg: str, content: List[Node]) -> Tuple[str, List[Node]]: return (fieldarg, content) - def make_field(self, - types, # type: Dict[str, List[nodes.Node]] - domain, # type: str - item, # type: Tuple - env=None, # type: BuildEnvironment - ): - # type: (...) -> nodes.field + def make_field(self, types: Dict[str, List[Node]], domain: str, + item: Tuple, env: "BuildEnvironment" = None) -> nodes.field: fieldarg, content = item fieldname = nodes.field_name('', self.label) if fieldarg: @@ -138,19 +119,13 @@ class GroupedField(Field): is_grouped = True list_type = nodes.bullet_list - def __init__(self, name, names=(), label=None, rolename=None, - can_collapse=False): - # type: (str, Tuple[str, ...], str, str, bool) -> None + def __init__(self, name: str, names: Tuple[str, ...] = (), label: str = None, + rolename: str = None, can_collapse: bool = False) -> None: super().__init__(name, names, label, True, rolename) self.can_collapse = can_collapse - def make_field(self, - types, # type: Dict[str, List[nodes.Node]] - domain, # type: str - items, # type: Tuple - env=None, # type: BuildEnvironment - ): - # type: (...) -> nodes.field + def make_field(self, types: Dict[str, List[Node]], domain: str, + items: Tuple, env: "BuildEnvironment" = None) -> nodes.field: fieldname = nodes.field_name('', self.label) listnode = self.list_type() for fieldarg, content in items: @@ -191,22 +166,16 @@ class TypedField(GroupedField): """ is_typed = True - def __init__(self, name, names=(), typenames=(), label=None, - rolename=None, typerolename=None, can_collapse=False): - # type: (str, Tuple[str, ...], Tuple[str, ...], str, str, str, bool) -> None + def __init__(self, name: str, names: Tuple[str, ...] = (), typenames: Tuple[str, ...] = (), + label: str = None, rolename: str = None, typerolename: str = None, + can_collapse: bool = False) -> None: super().__init__(name, names, label, rolename, can_collapse) self.typenames = typenames self.typerolename = typerolename - def make_field(self, - types, # type: Dict[str, List[nodes.Node]] - domain, # type: str - items, # type: Tuple - env=None, # type: BuildEnvironment - ): - # type: (...) -> nodes.field - def handle_item(fieldarg, content): - # type: (str, str) -> nodes.paragraph + def make_field(self, types: Dict[str, List[Node]], domain: str, + items: Tuple, env: "BuildEnvironment" = None) -> nodes.field: + def handle_item(fieldarg: str, content: str) -> nodes.paragraph: par = nodes.paragraph() par.extend(self.make_xrefs(self.rolename, domain, fieldarg, addnodes.literal_strong, env=env)) @@ -246,13 +215,11 @@ class DocFieldTransformer: """ typemap = None # type: Dict[str, Tuple[Field, bool]] - def __init__(self, directive): - # type: (ObjectDescription) -> None + def __init__(self, directive: "ObjectDescription") -> None: self.directive = directive self.typemap = directive.get_field_type_map() - def preprocess_fieldtypes(self, types): - # type: (List[Field]) -> Dict[str, Tuple[Field, bool]] + def preprocess_fieldtypes(self, types: List[Field]) -> Dict[str, Tuple[Field, bool]]: warnings.warn('DocFieldTransformer.preprocess_fieldtypes() is deprecated.', RemovedInSphinx40Warning) typemap = {} @@ -265,16 +232,14 @@ class DocFieldTransformer: typemap[name] = typed_field, True return typemap - def transform_all(self, node): - # type: (addnodes.desc_content) -> None + def transform_all(self, node: addnodes.desc_content) -> None: """Transform all field list children of a node.""" # don't traverse, only handle field lists that are immediate children for child in node: if isinstance(child, nodes.field_list): self.transform(child) - def transform(self, node): - # type: (nodes.field_list) -> None + def transform(self, node: nodes.field_list) -> None: """Transform a single field list *node*.""" typemap = self.typemap diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index eebfec464..b9795e7e4 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -16,33 +16,33 @@ from contextlib import contextmanager from copy import copy from distutils.version import LooseVersion from os import path -from typing import IO, cast +from types import ModuleType +from typing import Any, Callable, Dict, Generator, IO, List, Optional, Set, Tuple, Type +from typing import cast import docutils from docutils import nodes from docutils.io import FileOutput +from docutils.nodes import Element, Node, system_message from docutils.parsers.rst import Directive, directives, roles, convert_directive_function -from docutils.statemachine import StateMachine +from docutils.parsers.rst.states import Inliner +from docutils.statemachine import StateMachine, State, StringList from docutils.utils import Reporter, unescape from sphinx.deprecation import RemovedInSphinx30Warning from sphinx.errors import ExtensionError, SphinxError from sphinx.locale import __ from sphinx.util import logging +from sphinx.util.typing import RoleFunction logger = logging.getLogger(__name__) report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ') if False: # For type annotation - from types import ModuleType # NOQA - from typing import Any, Callable, Dict, Generator, List, Set, Tuple, Type # NOQA - from docutils.parsers.rst.states import Inliner # NOQA - from docutils.statemachine import State, StringList # NOQA - from sphinx.builders import Builder # NOQA - from sphinx.config import Config # NOQA - from sphinx.environment import BuildEnvironment # NOQA - from sphinx.util.typing import RoleFunction # NOQA + from sphinx.builders import Builder + from sphinx.config import Config + from sphinx.environment import BuildEnvironment __version_info__ = tuple(LooseVersion(docutils.__version__).version) @@ -50,8 +50,7 @@ additional_nodes = set() # type: Set[Type[nodes.Element]] @contextmanager -def docutils_namespace(): - # type: () -> Generator[None, None, None] +def docutils_namespace() -> Generator[None, None, None]: """Create namespace for reST parsers.""" try: _directives = copy(directives._directives) # type: ignore @@ -67,14 +66,12 @@ def docutils_namespace(): additional_nodes.discard(node) -def is_directive_registered(name): - # type: (str) -> bool +def is_directive_registered(name: str) -> bool: """Check the *name* directive is already registered.""" return name in directives._directives # type: ignore -def register_directive(name, directive): - # type: (str, Type[Directive]) -> None +def register_directive(name: str, directive: Type[Directive]) -> None: """Register a directive to docutils. This modifies global state of docutils. So it is better to use this @@ -83,14 +80,12 @@ def register_directive(name, directive): directives.register_directive(name, directive) -def is_role_registered(name): - # type: (str) -> bool +def is_role_registered(name: str) -> bool: """Check the *name* role is already registered.""" return name in roles._roles # type: ignore -def register_role(name, role): - # type: (str, RoleFunction) -> None +def register_role(name: str, role: RoleFunction) -> None: """Register a role to docutils. This modifies global state of docutils. So it is better to use this @@ -99,20 +94,17 @@ def register_role(name, role): roles.register_local_role(name, role) -def unregister_role(name): - # type: (str) -> None +def unregister_role(name: str) -> None: """Unregister a role from docutils.""" roles._roles.pop(name, None) # type: ignore -def is_node_registered(node): - # type: (Type[nodes.Element]) -> bool +def is_node_registered(node: Type[Element]) -> bool: """Check the *node* is already registered.""" return hasattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__) -def register_node(node): - # type: (Type[nodes.Element]) -> None +def register_node(node: Type[Element]) -> None: """Register a node to docutils. This modifies global state of some visitors. So it is better to use this @@ -123,8 +115,7 @@ def register_node(node): additional_nodes.add(node) -def unregister_node(node): - # type: (Type[nodes.Element]) -> None +def unregister_node(node: Type[Element]) -> None: """Unregister a node from docutils. This is inverse of ``nodes._add_nodes_class_names()``. @@ -137,8 +128,7 @@ def unregister_node(node): @contextmanager -def patched_get_language(): - # type: () -> Generator[None, None, None] +def patched_get_language() -> Generator[None, None, None]: """Patch docutils.languages.get_language() temporarily. This ignores the second argument ``reporter`` to suppress warnings. @@ -146,8 +136,7 @@ def patched_get_language(): """ from docutils.languages import get_language - def patched_get_language(language_code, reporter=None): - # type: (str, Reporter) -> Any + def patched_get_language(language_code: str, reporter: Reporter = None) -> Any: return get_language(language_code) try: @@ -159,8 +148,7 @@ def patched_get_language(): @contextmanager -def using_user_docutils_conf(confdir): - # type: (str) -> Generator[None, None, None] +def using_user_docutils_conf(confdir: str) -> Generator[None, None, None]: """Let docutils know the location of ``docutils.conf`` for Sphinx.""" try: docutilsconfig = os.environ.get('DOCUTILSCONFIG', None) @@ -176,8 +164,7 @@ def using_user_docutils_conf(confdir): @contextmanager -def patch_docutils(confdir=None): - # type: (str) -> Generator[None, None, None] +def patch_docutils(confdir: str = None) -> Generator[None, None, None]: """Patch to docutils temporarily.""" with patched_get_language(), using_user_docutils_conf(confdir): yield @@ -191,35 +178,30 @@ class sphinx_domains: """Monkey-patch directive and role dispatch, so that domain-specific markup takes precedence. """ - def __init__(self, env): - # type: (BuildEnvironment) -> None + def __init__(self, env: "BuildEnvironment") -> None: self.env = env self.directive_func = None # type: Callable self.roles_func = None # type: Callable - def __enter__(self): - # type: () -> None + def __enter__(self) -> None: self.enable() - def __exit__(self, type, value, traceback): - # type: (str, str, str) -> None + def __exit__(self, exc_type: Type[Exception], exc_value: Exception, traceback: Any) -> bool: # NOQA self.disable() + return True - def enable(self): - # type: () -> None + def enable(self) -> None: self.directive_func = directives.directive self.role_func = roles.role - directives.directive = self.lookup_directive # type: ignore - roles.role = self.lookup_role # type: ignore + directives.directive = self.lookup_directive + roles.role = self.lookup_role - def disable(self): - # type: () -> None + def disable(self) -> None: directives.directive = self.directive_func roles.role = self.role_func - def lookup_domain_element(self, type, name): - # type: (str, str) -> Any + def lookup_domain_element(self, type: str, name: str) -> Any: """Lookup a markup element (directive or role), given its name which can be a full name (with domain). """ @@ -247,24 +229,21 @@ class sphinx_domains: raise ElementLookupError - def lookup_directive(self, name, lang_module, document): - # type: (str, ModuleType, nodes.document) -> Tuple[Type[Directive], List[nodes.system_message]] # NOQA + def lookup_directive(self, directive_name: str, language_module: ModuleType, document: nodes.document) -> Tuple[Optional[Type[Directive]], List[system_message]]: # NOQA try: - return self.lookup_domain_element('directive', name) + return self.lookup_domain_element('directive', directive_name) except ElementLookupError: - return self.directive_func(name, lang_module, document) + return self.directive_func(directive_name, language_module, document) - def lookup_role(self, name, lang_module, lineno, reporter): - # type: (str, ModuleType, int, Reporter) -> Tuple[RoleFunction, List[nodes.system_message]] # NOQA + def lookup_role(self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter) -> Tuple[RoleFunction, List[system_message]]: # NOQA try: - return self.lookup_domain_element('role', name) + return self.lookup_domain_element('role', role_name) except ElementLookupError: - return self.role_func(name, lang_module, lineno, reporter) + return self.role_func(role_name, language_module, lineno, reporter) class WarningStream: - def write(self, text): - # type: (str) -> None + def write(self, text: str) -> None: matched = report_re.search(text) if not matched: logger.warning(text.rstrip("\r\n")) @@ -276,16 +255,14 @@ class WarningStream: class LoggingReporter(Reporter): @classmethod - def from_reporter(cls, reporter): - # type: (Reporter) -> LoggingReporter + def from_reporter(cls, reporter: Reporter) -> "LoggingReporter": """Create an instance of LoggingReporter from other reporter object.""" return cls(reporter.source, reporter.report_level, reporter.halt_level, reporter.debug_flag, reporter.error_handler) - def __init__(self, source, report_level=Reporter.WARNING_LEVEL, - halt_level=Reporter.SEVERE_LEVEL, debug=False, - error_handler='backslashreplace'): - # type: (str, int, int, bool, str) -> None + def __init__(self, source: str, report_level: int = Reporter.WARNING_LEVEL, + halt_level: int = Reporter.SEVERE_LEVEL, debug: bool = False, + error_handler: str = 'backslashreplace') -> None: stream = cast(IO, WarningStream()) super().__init__(source, report_level, halt_level, stream, debug, error_handler=error_handler) @@ -294,18 +271,15 @@ class LoggingReporter(Reporter): class NullReporter(Reporter): """A dummy reporter; write nothing.""" - def __init__(self): - # type: () -> None + def __init__(self) -> None: super().__init__('', 999, 4) -def is_html5_writer_available(): - # type: () -> bool +def is_html5_writer_available() -> bool: return __version_info__ > (0, 13, 0) -def directive_helper(obj, has_content=None, argument_spec=None, **option_spec): - # type: (Any, bool, Tuple[int, int, bool], Any) -> Any +def directive_helper(obj: Any, has_content: bool = None, argument_spec: Tuple[int, int, bool] = None, **option_spec) -> Any: # NOQA warnings.warn('function based directive support is now deprecated. ' 'Use class based directive instead.', RemovedInSphinx30Warning) @@ -323,8 +297,7 @@ def directive_helper(obj, has_content=None, argument_spec=None, **option_spec): @contextmanager -def switch_source_input(state, content): - # type: (State, StringList) -> Generator[None, None, None] +def switch_source_input(state: State, content: StringList) -> Generator[None, None, None]: """Switch current source input of state temporarily.""" try: # remember the original ``get_source_and_line()`` method @@ -344,13 +317,11 @@ def switch_source_input(state, content): class SphinxFileOutput(FileOutput): """Better FileOutput class for Sphinx.""" - def __init__(self, **kwargs): - # type: (Any) -> None + def __init__(self, **kwargs) -> None: self.overwrite_if_changed = kwargs.pop('overwrite_if_changed', False) super().__init__(**kwargs) - def write(self, data): - # type: (str) -> str + def write(self, data: str) -> str: if (self.destination_path and self.autoclose and 'b' not in self.mode and self.overwrite_if_changed and os.path.exists(self.destination_path)): with open(self.destination_path, encoding=self.encoding) as f: @@ -371,19 +342,16 @@ class SphinxDirective(Directive): """ @property - def env(self): - # type: () -> BuildEnvironment + def env(self) -> "BuildEnvironment": """Reference to the :class:`.BuildEnvironment` object.""" return self.state.document.settings.env @property - def config(self): - # type: () -> Config + def config(self) -> "Config": """Reference to the :class:`.Config` object.""" return self.env.config - def set_source_info(self, node): - # type: (nodes.Node) -> None + def set_source_info(self, node: Node) -> None: """Set source and line number to the node.""" node.source, node.line = self.state_machine.get_source_and_line(self.lineno) @@ -406,8 +374,9 @@ class SphinxRole: content = None #: A list of strings, the directive content for customization #: (from the "role" directive). - def __call__(self, name, rawtext, text, lineno, inliner, options={}, content=[]): - # type: (str, str, str, int, Inliner, Dict, List[str]) -> Tuple[List[nodes.Node], List[nodes.system_message]] # NOQA + def __call__(self, name: str, rawtext: str, text: str, lineno: int, + inliner: Inliner, options: Dict = {}, content: List[str] = [] + ) -> Tuple[List[Node], List[system_message]]: self.rawtext = rawtext self.text = unescape(text) self.lineno = lineno @@ -427,24 +396,20 @@ class SphinxRole: return self.run() - def run(self): - # type: () -> Tuple[List[nodes.Node], List[nodes.system_message]] + def run(self) -> Tuple[List[Node], List[system_message]]: raise NotImplementedError @property - def env(self): - # type: () -> BuildEnvironment + def env(self) -> "BuildEnvironment": """Reference to the :class:`.BuildEnvironment` object.""" return self.inliner.document.settings.env @property - def config(self): - # type: () -> Config + def config(self) -> "Config": """Reference to the :class:`.Config` object.""" return self.env.config - def set_source_info(self, node, lineno=None): - # type: (nodes.Node, int) -> None + def set_source_info(self, node: Node, lineno: int = None) -> None: if lineno is None: lineno = self.lineno @@ -466,8 +431,9 @@ class ReferenceRole(SphinxRole): # \x00 means the "<" was backslash-escaped explicit_title_re = re.compile(r'^(.+?)\s*(?<!\x00)<(.*?)>$', re.DOTALL) - def __call__(self, name, rawtext, text, lineno, inliner, options={}, content=[]): - # type: (str, str, str, int, Inliner, Dict, List[str]) -> Tuple[List[nodes.Node], List[nodes.system_message]] # NOQA + def __call__(self, name: str, rawtext: str, text: str, lineno: int, + inliner: Inliner, options: Dict = {}, content: List[str] = [] + ) -> Tuple[List[Node], List[system_message]]: matched = self.explicit_title_re.match(text) if matched: self.has_explicit_title = True @@ -490,8 +456,7 @@ class SphinxTranslator(nodes.NodeVisitor): This class is strongly coupled with Sphinx. """ - def __init__(self, document, builder): - # type: (nodes.document, Builder) -> None + def __init__(self, document: nodes.document, builder: "Builder") -> None: super().__init__(document) self.builder = builder self.config = builder.config @@ -503,8 +468,7 @@ class SphinxTranslator(nodes.NodeVisitor): __document_cache__ = None # type: nodes.document -def new_document(source_path, settings=None): - # type: (str, Any) -> nodes.document +def new_document(source_path: str, settings: Any = None) -> nodes.document: """Return a new empty document object. This is an alternative of docutils'. This is a simple wrapper for ``docutils.utils.new_document()``. It diff --git a/sphinx/util/inventory.py b/sphinx/util/inventory.py index 0fdc3e833..43a868e95 100644 --- a/sphinx/util/inventory.py +++ b/sphinx/util/inventory.py @@ -10,20 +10,20 @@ import os import re import zlib +from typing import Callable, IO, Iterator from sphinx.util import logging - -if False: - # For type annotation - from typing import Callable, IO, Iterator # NOQA - from sphinx.builders import Builder # NOQA - from sphinx.environment import BuildEnvironment # NOQA - from sphinx.util.typing import Inventory # NOQA +from sphinx.util.typing import Inventory BUFSIZE = 16 * 1024 logger = logging.getLogger(__name__) +if False: + # For type annotation + from sphinx.builders import Builder + from sphinx.environment import BuildEnvironment + class InventoryFileReader: """A file reader for inventory file. @@ -31,21 +31,18 @@ class InventoryFileReader: This reader supports mixture of texts and compressed texts. """ - def __init__(self, stream): - # type: (IO) -> None + def __init__(self, stream: IO) -> None: self.stream = stream self.buffer = b'' self.eof = False - def read_buffer(self): - # type: () -> None + def read_buffer(self) -> None: chunk = self.stream.read(BUFSIZE) if chunk == b'': self.eof = True self.buffer += chunk - def readline(self): - # type: () -> str + def readline(self) -> str: pos = self.buffer.find(b'\n') if pos != -1: line = self.buffer[:pos].decode() @@ -59,15 +56,13 @@ class InventoryFileReader: return line - def readlines(self): - # type: () -> Iterator[str] + def readlines(self) -> Iterator[str]: while not self.eof: line = self.readline() if line: yield line - def read_compressed_chunks(self): - # type: () -> Iterator[bytes] + def read_compressed_chunks(self) -> Iterator[bytes]: decompressor = zlib.decompressobj() while not self.eof: self.read_buffer() @@ -75,8 +70,7 @@ class InventoryFileReader: self.buffer = b'' yield decompressor.flush() - def read_compressed_lines(self): - # type: () -> Iterator[str] + def read_compressed_lines(self) -> Iterator[str]: buf = b'' for chunk in self.read_compressed_chunks(): buf += chunk @@ -89,8 +83,7 @@ class InventoryFileReader: class InventoryFile: @classmethod - def load(cls, stream, uri, joinfunc): - # type: (IO, str, Callable) -> Inventory + def load(cls, stream: IO, uri: str, joinfunc: Callable) -> Inventory: reader = InventoryFileReader(stream) line = reader.readline().rstrip() if line == '# Sphinx inventory version 1': @@ -101,8 +94,7 @@ class InventoryFile: raise ValueError('invalid inventory header: %s' % line) @classmethod - def load_v1(cls, stream, uri, join): - # type: (InventoryFileReader, str, Callable) -> Inventory + def load_v1(cls, stream: InventoryFileReader, uri: str, join: Callable) -> Inventory: invdata = {} # type: Inventory projname = stream.readline().rstrip()[11:] version = stream.readline().rstrip()[11:] @@ -120,8 +112,7 @@ class InventoryFile: return invdata @classmethod - def load_v2(cls, stream, uri, join): - # type: (InventoryFileReader, str, Callable) -> Inventory + def load_v2(cls, stream: InventoryFileReader, uri: str, join: Callable) -> Inventory: invdata = {} # type: Inventory projname = stream.readline().rstrip()[11:] version = stream.readline().rstrip()[11:] @@ -150,10 +141,8 @@ class InventoryFile: return invdata @classmethod - def dump(cls, filename, env, builder): - # type: (str, BuildEnvironment, Builder) -> None - def escape(string): - # type: (str) -> str + def dump(cls, filename: str, env: "BuildEnvironment", builder: "Builder") -> None: + def escape(string: str) -> str: return re.sub("\\s+", " ", string) with open(os.path.join(filename), 'wb') as f: diff --git a/sphinx/util/jsdump.py b/sphinx/util/jsdump.py index 0bab2f014..bfdba170b 100644 --- a/sphinx/util/jsdump.py +++ b/sphinx/util/jsdump.py @@ -10,10 +10,7 @@ """ import re - -if False: - # For type annotation - from typing import Any, Dict, IO, List, Match, Union # NOQA +from typing import Any, Dict, IO, List, Match, Union _str_re = re.compile(r'"(\\\\|\\"|[^"])*"') _int_re = re.compile(r'\d+') @@ -35,10 +32,8 @@ ESCAPE_DICT = { ESCAPED = re.compile(r'\\u.{4}|\\.') -def encode_string(s): - # type: (str) -> str - def replace(match): - # type: (Match) -> str +def encode_string(s: str) -> str: + def replace(match: Match) -> str: s = match.group(0) try: return ESCAPE_DICT[s] @@ -55,8 +50,7 @@ def encode_string(s): return '"' + str(ESCAPE_ASCII.sub(replace, s)) + '"' -def decode_string(s): - # type: (str) -> str +def decode_string(s: str) -> str: return ESCAPED.sub(lambda m: eval('"' + m.group() + '"'), s) @@ -78,8 +72,7 @@ do import static with double in super""".split()) -def dumps(obj, key=False): - # type: (Any, bool) -> str +def dumps(obj: Any, key: bool = False) -> str: if key: if not isinstance(obj, str): obj = str(obj) @@ -107,13 +100,11 @@ def dumps(obj, key=False): raise TypeError(type(obj)) -def dump(obj, f): - # type: (Any, IO) -> None +def dump(obj: Any, f: IO) -> None: f.write(dumps(obj)) -def loads(x): - # type: (str) -> Any +def loads(x: str) -> Any: """Loader that can read the JS subset the indexer produces.""" nothing = object() i = 0 @@ -205,6 +196,5 @@ def loads(x): return obj -def load(f): - # type: (IO) -> Any +def load(f: IO) -> Any: return loads(f.read()) diff --git a/sphinx/util/jsonimpl.py b/sphinx/util/jsonimpl.py index 4fb8e1f5d..c5336a195 100644 --- a/sphinx/util/jsonimpl.py +++ b/sphinx/util/jsonimpl.py @@ -11,13 +11,10 @@ import json import warnings from collections import UserString +from typing import Any, IO from sphinx.deprecation import RemovedInSphinx40Warning -if False: - # For type annotation - from typing import Any, IO # NOQA - warnings.warn('sphinx.util.jsonimpl is deprecated', RemovedInSphinx40Warning, stacklevel=2) @@ -25,30 +22,25 @@ warnings.warn('sphinx.util.jsonimpl is deprecated', class SphinxJSONEncoder(json.JSONEncoder): """JSONEncoder subclass that forces translation proxies.""" - def default(self, obj): - # type: (Any) -> str + def default(self, obj: Any) -> str: if isinstance(obj, UserString): return str(obj) return super().default(obj) -def dump(obj, fp, *args, **kwds): - # type: (Any, IO, Any, Any) -> None +def dump(obj: Any, fp: IO, *args, **kwds) -> None: kwds['cls'] = SphinxJSONEncoder json.dump(obj, fp, *args, **kwds) -def dumps(obj, *args, **kwds): - # type: (Any, Any, Any) -> str +def dumps(obj: Any, *args, **kwds) -> str: kwds['cls'] = SphinxJSONEncoder return json.dumps(obj, *args, **kwds) -def load(*args, **kwds): - # type: (Any, Any) -> Any +def load(*args, **kwds) -> Any: return json.load(*args, **kwds) -def loads(*args, **kwds): - # type: (Any, Any) -> Any +def loads(*args, **kwds) -> Any: return json.loads(*args, **kwds) diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index afa4ebd23..d6667dacd 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -12,8 +12,10 @@ import logging import logging.handlers from collections import defaultdict from contextlib import contextmanager +from typing import Any, Dict, Generator, IO, List, Tuple, Type, Union from docutils import nodes +from docutils.nodes import Node from docutils.utils import get_source_line from sphinx.errors import SphinxWarning @@ -21,8 +23,7 @@ from sphinx.util.console import colorize if False: # For type annotation - from typing import Any, Dict, Generator, IO, List, Tuple, Type, Union # NOQA - from sphinx.application import Sphinx # NOQA + from sphinx.application import Sphinx NAMESPACE = 'sphinx' @@ -54,8 +55,7 @@ COLOR_MAP = defaultdict(lambda: 'blue', }) -def getLogger(name): - # type: (str) -> SphinxLoggerAdapter +def getLogger(name: str) -> "SphinxLoggerAdapter": """Get logger wrapped by :class:`sphinx.util.logging.SphinxLoggerAdapter`. Sphinx logger always uses ``sphinx.*`` namespace to be independent from @@ -77,8 +77,7 @@ def getLogger(name): return SphinxLoggerAdapter(logger, {}) -def convert_serializable(records): - # type: (List[logging.LogRecord]) -> None +def convert_serializable(records: List[logging.LogRecord]) -> None: """Convert LogRecord serializable.""" for r in records: # extract arguments to a message and clear them @@ -95,8 +94,7 @@ class SphinxLogRecord(logging.LogRecord): prefix = '' location = None # type: Any - def getMessage(self): - # type: () -> str + def getMessage(self) -> str: message = super().getMessage() location = getattr(self, 'location', None) if location: @@ -120,20 +118,17 @@ class SphinxWarningLogRecord(SphinxLogRecord): class SphinxLoggerAdapter(logging.LoggerAdapter): """LoggerAdapter allowing ``type`` and ``subtype`` keywords.""" - def log(self, level, msg, *args, **kwargs): - # type: (Union[int, str], str, Any, Any) -> None + def log(self, level: Union[int, str], msg: str, *args, **kwargs) -> None: if isinstance(level, int): super().log(level, msg, *args, **kwargs) else: levelno = LEVEL_NAMES[level] super().log(levelno, msg, *args, **kwargs) - def verbose(self, msg, *args, **kwargs): - # type: (str, Any, Any) -> None + def verbose(self, msg: str, *args, **kwargs) -> None: self.log(VERBOSE, msg, *args, **kwargs) - def process(self, msg, kwargs): # type: ignore - # type: (str, Dict) -> Tuple[str, Dict] + def process(self, msg: str, kwargs: Dict) -> Tuple[str, Dict]: # type: ignore extra = kwargs.setdefault('extra', {}) if 'type' in kwargs: extra['type'] = kwargs.pop('type') @@ -148,8 +143,7 @@ class SphinxLoggerAdapter(logging.LoggerAdapter): return msg, kwargs - def handle(self, record): - # type: (logging.LogRecord) -> None + def handle(self, record: logging.LogRecord) -> None: self.logger.handle(record) @@ -161,8 +155,7 @@ class WarningStreamHandler(logging.StreamHandler): class NewLineStreamHandler(logging.StreamHandler): """StreamHandler which switches line terminator by record.nonl flag.""" - def emit(self, record): - # type: (logging.LogRecord) -> None + def emit(self, record: logging.LogRecord) -> None: try: self.acquire() if getattr(record, 'nonl', False): @@ -177,16 +170,13 @@ class NewLineStreamHandler(logging.StreamHandler): class MemoryHandler(logging.handlers.BufferingHandler): """Handler buffering all logs.""" - def __init__(self): - # type: () -> None + def __init__(self) -> None: super().__init__(-1) - def shouldFlush(self, record): - # type: (logging.LogRecord) -> bool + def shouldFlush(self, record: logging.LogRecord) -> bool: return False # never flush - def flushTo(self, logger): - # type: (logging.Logger) -> None + def flushTo(self, logger: logging.Logger) -> None: self.acquire() try: for record in self.buffer: @@ -195,15 +185,13 @@ class MemoryHandler(logging.handlers.BufferingHandler): finally: self.release() - def clear(self): - # type: () -> List[logging.LogRecord] + def clear(self) -> List[logging.LogRecord]: buffer, self.buffer = self.buffer, [] return buffer @contextmanager -def pending_warnings(): - # type: () -> Generator +def pending_warnings() -> Generator[logging.Handler, None, None]: """Contextmanager to pend logging warnings temporary. Similar to :func:`pending_logging`. @@ -231,8 +219,7 @@ def pending_warnings(): @contextmanager -def pending_logging(): - # type: () -> Generator +def pending_logging() -> Generator[MemoryHandler, None, None]: """Contextmanager to pend logging all logs temporary. For example:: @@ -264,8 +251,7 @@ def pending_logging(): @contextmanager -def skip_warningiserror(skip=True): - # type: (bool) -> Generator +def skip_warningiserror(skip: bool = True) -> Generator[None, None, None]: """contextmanager to skip WarningIsErrorFilter for a while.""" logger = logging.getLogger(NAMESPACE) @@ -285,8 +271,7 @@ def skip_warningiserror(skip=True): @contextmanager -def prefixed_warnings(prefix): - # type: (str) -> Generator +def prefixed_warnings(prefix: str) -> Generator[None, None, None]: """Prepend prefix to all records for a while. For example:: @@ -332,13 +317,11 @@ def prefixed_warnings(prefix): class LogCollector: - def __init__(self): - # type: () -> None + def __init__(self) -> None: self.logs = [] # type: List[logging.LogRecord] @contextmanager - def collect(self): - # type: () -> Generator + def collect(self) -> Generator[None, None, None]: with pending_logging() as memhandler: yield @@ -348,16 +331,14 @@ class LogCollector: class InfoFilter(logging.Filter): """Filter error and warning messages.""" - def filter(self, record): - # type: (logging.LogRecord) -> bool + def filter(self, record: logging.LogRecord) -> bool: if record.levelno < logging.WARNING: return True else: return False -def is_suppressed_warning(type, subtype, suppress_warnings): - # type: (str, str, List[str]) -> bool +def is_suppressed_warning(type: str, subtype: str, suppress_warnings: List[str]) -> bool: """Check the warning is suppressed or not.""" if type is None: return False @@ -379,13 +360,11 @@ def is_suppressed_warning(type, subtype, suppress_warnings): class WarningSuppressor(logging.Filter): """Filter logs by `suppress_warnings`.""" - def __init__(self, app): - # type: (Sphinx) -> None + def __init__(self, app: "Sphinx") -> None: self.app = app super().__init__() - def filter(self, record): - # type: (logging.LogRecord) -> bool + def filter(self, record: logging.LogRecord) -> bool: type = getattr(record, 'type', None) subtype = getattr(record, 'subtype', None) @@ -405,13 +384,11 @@ class WarningSuppressor(logging.Filter): class WarningIsErrorFilter(logging.Filter): """Raise exception if warning emitted.""" - def __init__(self, app): - # type: (Sphinx) -> None + def __init__(self, app: "Sphinx") -> None: self.app = app super().__init__() - def filter(self, record): - # type: (logging.LogRecord) -> bool + def filter(self, record: logging.LogRecord) -> bool: if getattr(record, 'skip_warningsiserror', False): # disabled by DisableWarningIsErrorFilter return True @@ -433,8 +410,7 @@ class WarningIsErrorFilter(logging.Filter): class DisableWarningIsErrorFilter(logging.Filter): """Disable WarningIsErrorFilter if this filter installed.""" - def filter(self, record): - # type: (logging.LogRecord) -> bool + def filter(self, record: logging.LogRecord) -> bool: record.skip_warningsiserror = True # type: ignore return True @@ -442,13 +418,11 @@ class DisableWarningIsErrorFilter(logging.Filter): class MessagePrefixFilter(logging.Filter): """Prepend prefix to all records.""" - def __init__(self, prefix): - # type: (str) -> None + def __init__(self, prefix: str) -> None: self.prefix = prefix super().__init__() - def filter(self, record): - # type: (logging.LogRecord) -> bool + def filter(self, record: logging.LogRecord) -> bool: if self.prefix: record.msg = self.prefix + ' ' + record.msg return True @@ -462,13 +436,11 @@ class SphinxLogRecordTranslator(logging.Filter): """ LogRecordClass = None # type: Type[logging.LogRecord] - def __init__(self, app): - # type: (Sphinx) -> None + def __init__(self, app: "Sphinx") -> None: self.app = app super().__init__() - def filter(self, record): # type: ignore - # type: (SphinxWarningLogRecord) -> bool + def filter(self, record: SphinxWarningLogRecord) -> bool: # type: ignore if isinstance(record, logging.LogRecord): # force subclassing to handle location record.__class__ = self.LogRecordClass # type: ignore @@ -500,8 +472,7 @@ class WarningLogRecordTranslator(SphinxLogRecordTranslator): LogRecordClass = SphinxWarningLogRecord -def get_node_location(node): - # type: (nodes.Node) -> str +def get_node_location(node: Node) -> str: (source, line) = get_source_line(node) if source and line: return "%s:%s" % (source, line) @@ -514,8 +485,7 @@ def get_node_location(node): class ColorizeFormatter(logging.Formatter): - def format(self, record): - # type: (logging.LogRecord) -> str + def format(self, record: logging.LogRecord) -> str: message = super().format(record) color = getattr(record, 'color', None) if color is None: @@ -529,13 +499,11 @@ class ColorizeFormatter(logging.Formatter): class SafeEncodingWriter: """Stream writer which ignores UnicodeEncodeError silently""" - def __init__(self, stream): - # type: (IO) -> None + def __init__(self, stream: IO) -> None: self.stream = stream self.encoding = getattr(stream, 'encoding', 'ascii') or 'ascii' - def write(self, data): - # type: (str) -> None + def write(self, data: str) -> None: try: self.stream.write(data) except UnicodeEncodeError: @@ -543,25 +511,21 @@ class SafeEncodingWriter: # non-encodable characters, then decode them. self.stream.write(data.encode(self.encoding, 'replace').decode(self.encoding)) - def flush(self): - # type: () -> None + def flush(self) -> None: if hasattr(self.stream, 'flush'): self.stream.flush() class LastMessagesWriter: """Stream writer which memories last 10 messages to save trackback""" - def __init__(self, app, stream): - # type: (Sphinx, IO) -> None + def __init__(self, app: "Sphinx", stream: IO) -> None: self.app = app - def write(self, data): - # type: (str) -> None + def write(self, data: str) -> None: self.app.messagelog.append(data) -def setup(app, status, warning): - # type: (Sphinx, IO, IO) -> None +def setup(app: "Sphinx", status: IO, warning: IO) -> None: """Setup root logger for Sphinx""" logger = logging.getLogger(NAMESPACE) logger.setLevel(logging.DEBUG) diff --git a/sphinx/util/matching.py b/sphinx/util/matching.py index b1725cb46..97eeff40f 100644 --- a/sphinx/util/matching.py +++ b/sphinx/util/matching.py @@ -9,16 +9,12 @@ """ import re +from typing import Callable, Dict, List, Match, Pattern from sphinx.util.osutil import canon_path -if False: - # For type annotation - from typing import Callable, Dict, List, Match, Pattern # NOQA - -def _translate_pattern(pat): - # type: (str) -> str +def _translate_pattern(pat: str) -> str: """Translate a shell-style glob pattern to a regular expression. Adapted from the fnmatch module, but enhanced so that single stars don't @@ -64,8 +60,7 @@ def _translate_pattern(pat): return res + '$' -def compile_matchers(patterns): - # type: (List[str]) -> List[Callable[[str], Match[str]]] +def compile_matchers(patterns: List[str]) -> List[Callable[[str], Match[str]]]: return [re.compile(_translate_pattern(pat)).match for pat in patterns] @@ -76,17 +71,14 @@ class Matcher: For example, "**/index.rst" matches with "index.rst" """ - def __init__(self, patterns): - # type: (List[str]) -> None + def __init__(self, patterns: List[str]) -> None: expanded = [pat[3:] for pat in patterns if pat.startswith('**/')] self.patterns = compile_matchers(patterns + expanded) - def __call__(self, string): - # type: (str) -> bool + def __call__(self, string: str) -> bool: return self.match(string) - def match(self, string): - # type: (str) -> bool + def match(self, string: str) -> bool: string = canon_path(string) return any(pat(string) for pat in self.patterns) @@ -97,16 +89,14 @@ DOTFILES = Matcher(['**/.*']) _pat_cache = {} # type: Dict[str, Pattern] -def patmatch(name, pat): - # type: (str, str) -> Match[str] +def patmatch(name: str, pat: str) -> Match[str]: """Return if name matches pat. Adapted from fnmatch module.""" if pat not in _pat_cache: _pat_cache[pat] = re.compile(_translate_pattern(pat)) return _pat_cache[pat].match(name) -def patfilter(names, pat): - # type: (List[str], str) -> List[str] +def patfilter(names: List[str], pat: str) -> List[str]: """Return the subset of the list NAMES that match PAT. Adapted from fnmatch module. diff --git a/sphinx/util/math.py b/sphinx/util/math.py index d296a3fe0..2af4e4db6 100644 --- a/sphinx/util/math.py +++ b/sphinx/util/math.py @@ -8,15 +8,12 @@ :license: BSD, see LICENSE for details. """ +from docutils import nodes -if False: - # For type annotation - from docutils import nodes # NOQA - from sphinx.builders.html import HTMLTranslator # NOQA +from sphinx.builders.html import HTMLTranslator -def get_node_equation_number(writer, node): - # type: (HTMLTranslator, nodes.math_block) -> str +def get_node_equation_number(writer: HTMLTranslator, node: nodes.math_block) -> str: if writer.builder.config.math_numfig and writer.builder.config.numfig: figtype = 'displaymath' if writer.builder.name == 'singlehtml': @@ -31,10 +28,8 @@ def get_node_equation_number(writer, node): return node['number'] -def wrap_displaymath(text, label, numbering): - # type: (str, str, bool) -> str - def is_equation(part): - # type: (str) -> str +def wrap_displaymath(text: str, label: str, numbering: bool) -> str: + def is_equation(part: str) -> str: return part.strip() if label is None: diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py index 58c6a6698..e0aaaa14e 100644 --- a/sphinx/util/nodes.py +++ b/sphinx/util/nodes.py @@ -10,9 +10,14 @@ import re import warnings -from typing import Any, cast +from typing import Any, Callable, Iterable, List, Set, Tuple, Type +from typing import cast from docutils import nodes +from docutils.nodes import Element, Node +from docutils.parsers.rst import Directive +from docutils.parsers.rst.states import Inliner +from docutils.statemachine import StringList from sphinx import addnodes from sphinx.deprecation import RemovedInSphinx40Warning @@ -21,11 +26,8 @@ from sphinx.util import logging if False: # For type annotation - from typing import Callable, Iterable, List, Optional, Set, Tuple, Type # NOQA - from docutils.parsers.rst.states import Inliner # NOQA - from docutils.statemachine import StringList # NOQA - from sphinx.builders import Builder # NOQA - from sphinx.utils.tags import Tags # NOQA + from sphinx.builders import Builder + from sphinx.utils.tags import Tags logger = logging.getLogger(__name__) @@ -57,13 +59,11 @@ class NodeMatcher: # => [<reference ...>, <reference ...>, ...] """ - def __init__(self, *classes, **attrs): - # type: (Type[nodes.Node], Any) -> None + def __init__(self, *classes: Type[Node], **attrs) -> None: self.classes = classes self.attrs = attrs - def match(self, node): - # type: (nodes.Node) -> bool + def match(self, node: Node) -> bool: try: if self.classes and not isinstance(node, self.classes): return False @@ -85,13 +85,11 @@ class NodeMatcher: # for non-Element nodes return False - def __call__(self, node): - # type: (nodes.Node) -> bool + def __call__(self, node: Node) -> bool: return self.match(node) -def get_full_module_name(node): - # type: (nodes.Node) -> str +def get_full_module_name(node: Node) -> str: """ return full module dotted path like: 'docutils.nodes.paragraph' @@ -101,8 +99,7 @@ def get_full_module_name(node): return '{}.{}'.format(node.__module__, node.__class__.__name__) -def repr_domxml(node, length=80): - # type: (nodes.Node, Optional[int]) -> str +def repr_domxml(node: Node, length: int = 80) -> str: """ return DOM XML representation of the specified node like: '<paragraph translatable="False"><inline classes="versionmodified">New in version...' @@ -122,8 +119,7 @@ def repr_domxml(node, length=80): return text -def apply_source_workaround(node): - # type: (nodes.Element) -> None +def apply_source_workaround(node: Element) -> 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, @@ -186,8 +182,7 @@ IGNORED_NODES = ( ) -def is_pending_meta(node): - # type: (nodes.Node) -> bool +def is_pending_meta(node: Node) -> bool: if (isinstance(node, nodes.pending) and isinstance(node.details.get('nodes', [None])[0], addnodes.meta)): return True @@ -195,8 +190,7 @@ def is_pending_meta(node): return False -def is_translatable(node): - # type: (nodes.Node) -> bool +def is_translatable(node: Node) -> bool: if isinstance(node, addnodes.translatable): return True @@ -251,8 +245,7 @@ META_TYPE_NODES = ( ) -def extract_messages(doctree): - # type: (nodes.Element) -> Iterable[Tuple[nodes.Element, str]] +def extract_messages(doctree: Element) -> Iterable[Tuple[Element, str]]: """Extract translatable messages from a document tree.""" for node in doctree.traverse(is_translatable): # type: nodes.Element if isinstance(node, addnodes.translatable): @@ -279,39 +272,34 @@ def extract_messages(doctree): yield node, msg -def find_source_node(node): - # type: (nodes.Element) -> str +def find_source_node(node: Element) -> str: warnings.warn('find_source_node() is deprecated.', RemovedInSphinx40Warning) return get_node_source(node) -def get_node_source(node): - # type: (nodes.Element) -> str +def get_node_source(node: Element) -> str: for pnode in traverse_parent(node): if pnode.source: return pnode.source return None -def get_node_line(node): - # type: (nodes.Element) -> int +def get_node_line(node: Element) -> int: for pnode in traverse_parent(node): if pnode.line: return pnode.line return None -def traverse_parent(node, cls=None): - # type: (nodes.Element, Any) -> Iterable[nodes.Element] +def traverse_parent(node: Element, cls: Any = None) -> Iterable[Element]: while node: if cls is None or isinstance(node, cls): yield node node = node.parent -def get_prev_node(node): - # type: (nodes.Node) -> nodes.Node +def get_prev_node(node: Node) -> Node: pos = node.parent.index(node) if pos > 0: return node.parent[pos - 1] @@ -319,8 +307,7 @@ def get_prev_node(node): return None -def traverse_translatable_index(doctree): - # type: (nodes.Element) -> Iterable[Tuple[nodes.Element, List[str]]] +def traverse_translatable_index(doctree: Element) -> Iterable[Tuple[Element, List[str]]]: """Traverse translatable index node from a document tree.""" for node in doctree.traverse(NodeMatcher(addnodes.index, inline=False)): # type: addnodes.index # NOQA if 'raw_entries' in node: @@ -330,8 +317,7 @@ def traverse_translatable_index(doctree): yield node, entries -def nested_parse_with_titles(state, content, node): - # type: (Any, StringList, nodes.Node) -> str +def nested_parse_with_titles(state: Any, content: StringList, node: Node) -> str: """Version of state.nested_parse() that allows titles and does not require titles to have the same decoration as the calling document. @@ -350,8 +336,7 @@ def nested_parse_with_titles(state, content, node): state.memo.section_level = surrounding_section_level -def clean_astext(node): - # type: (nodes.Element) -> str +def clean_astext(node: Element) -> str: """Like node.astext(), but ignore images.""" node = node.deepcopy() for img in node.traverse(nodes.image): @@ -361,8 +346,7 @@ def clean_astext(node): return node.astext() -def split_explicit_title(text): - # type: (str) -> Tuple[bool, str, str] +def split_explicit_title(text: str) -> Tuple[bool, str, str]: """Split role content into title and target, if given.""" match = explicit_title_re.match(text) if match: @@ -375,8 +359,7 @@ indextypes = [ ] -def process_index_entry(entry, targetid): - # type: (str, str) -> List[Tuple[str, str, str, str, str]] +def process_index_entry(entry: str, targetid: str) -> List[Tuple[str, str, str, str, str]]: from sphinx.domains.python import pairindextypes indexentries = [] # type: List[Tuple[str, str, str, str, str]] @@ -414,8 +397,9 @@ def process_index_entry(entry, targetid): return indexentries -def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed): - # type: (Builder, Set[str], str, nodes.document, Callable, List[str]) -> nodes.document +def inline_all_toctrees(builder: "Builder", docnameset: Set[str], docname: str, + tree: nodes.document, colorfunc: Callable, traversed: List[str] + ) -> nodes.document: """Inline all toctrees in the *tree*. Record all docnames in *docnameset*, and output docnames with *colorfunc*. @@ -447,8 +431,8 @@ def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed return tree -def make_refnode(builder, fromdocname, todocname, targetid, child, title=None): - # type: (Builder, str, str, str, nodes.Node, str) -> nodes.reference +def make_refnode(builder: "Builder", fromdocname: str, todocname: str, targetid: str, + child: Node, title: str = None) -> nodes.reference: """Shortcut to create a reference node.""" node = nodes.reference('', '', internal=True) if fromdocname == todocname and targetid: @@ -465,19 +449,16 @@ def make_refnode(builder, fromdocname, todocname, targetid, child, title=None): return node -def set_source_info(directive, node): - # type: (Any, nodes.Node) -> None +def set_source_info(directive: Directive, node: Node) -> None: node.source, node.line = \ directive.state_machine.get_source_and_line(directive.lineno) -def set_role_source_info(inliner, lineno, node): - # type: (Inliner, int, nodes.Node) -> None +def set_role_source_info(inliner: Inliner, lineno: int, node: Node) -> None: node.source, node.line = inliner.reporter.get_source_and_line(lineno) # type: ignore -def copy_source_info(src, dst): - # type: (nodes.Element, nodes.Element) -> None +def copy_source_info(src: Element, dst: Element) -> None: dst.source = get_node_source(src) dst.line = get_node_line(src) @@ -493,8 +474,7 @@ NON_SMARTQUOTABLE_PARENT_NODES = ( ) -def is_smartquotable(node): - # type: (nodes.Node) -> bool +def is_smartquotable(node: Node) -> bool: """Check the node is smart-quotable or not.""" if isinstance(node.parent, NON_SMARTQUOTABLE_PARENT_NODES): return False @@ -506,8 +486,7 @@ def is_smartquotable(node): return True -def process_only_nodes(document, tags): - # type: (nodes.Node, Tags) -> None +def process_only_nodes(document: Node, tags: "Tags") -> None: """Filter ``only`` nodes which does not match *tags*.""" for node in document.traverse(addnodes.only): try: @@ -530,8 +509,7 @@ def process_only_nodes(document, tags): # monkey-patch Element.copy to copy the rawsource and line # for docutils-0.14 or older versions. -def _new_copy(self): - # type: (nodes.Element) -> nodes.Element +def _new_copy(self: Element) -> Element: 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 2b3fe51b0..3751fcc08 100644 --- a/sphinx/util/osutil.py +++ b/sphinx/util/osutil.py @@ -19,14 +19,11 @@ import time import warnings from io import StringIO from os import path +from typing import Any, Generator, Iterator, List, Tuple, Type from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning from sphinx.testing.path import path as Path -if False: - # For type annotation - from typing import Any, Iterator, List, Tuple # NOQA - # Errnos that we need. EEXIST = getattr(errno, 'EEXIST', 0) # RemovedInSphinx40Warning ENOENT = getattr(errno, 'ENOENT', 0) # RemovedInSphinx40Warning @@ -41,19 +38,16 @@ EINVAL = getattr(errno, 'EINVAL', 0) # RemovedInSphinx40Warning SEP = "/" -def os_path(canonicalpath): - # type: (str) -> str +def os_path(canonicalpath: str) -> str: return canonicalpath.replace(SEP, path.sep) -def canon_path(nativepath): - # type: (str) -> str +def canon_path(nativepath: str) -> str: """Return path in OS-independent form""" return nativepath.replace(path.sep, SEP) -def relative_uri(base, to): - # type: (str, str) -> str +def relative_uri(base: str, to: str) -> str: """Return a relative URL from ``base`` to ``to``.""" if to.startswith(SEP): return to @@ -76,22 +70,19 @@ def relative_uri(base, to): return ('..' + SEP) * (len(b2) - 1) + SEP.join(t2) -def ensuredir(path): - # type: (str) -> None +def ensuredir(path: str) -> None: """Ensure that a path exists.""" os.makedirs(path, exist_ok=True) -def walk(top, topdown=True, followlinks=False): - # type: (str, bool, bool) -> Iterator[Tuple[str, List[str], List[str]]] +def walk(top: str, topdown: bool = True, followlinks: bool = False) -> Iterator[Tuple[str, List[str], List[str]]]: # NOQA warnings.warn('sphinx.util.osutil.walk() is deprecated for removal. ' 'Please use os.walk() instead.', RemovedInSphinx40Warning) return os.walk(top, topdown=topdown, followlinks=followlinks) -def mtimes_of_files(dirnames, suffix): - # type: (List[str], str) -> Iterator[float] +def mtimes_of_files(dirnames: List[str], suffix: str) -> Iterator[float]: for dirname in dirnames: for root, dirs, files in os.walk(dirname): for sfile in files: @@ -102,8 +93,7 @@ def mtimes_of_files(dirnames, suffix): pass -def movefile(source, dest): - # type: (str, str) -> None +def movefile(source: str, dest: str) -> None: """Move a file, removing the destination if it exists.""" if os.path.exists(dest): try: @@ -113,16 +103,14 @@ def movefile(source, dest): os.rename(source, dest) -def copytimes(source, dest): - # type: (str, str) -> None +def copytimes(source: str, dest: str) -> None: """Copy a file's modification times.""" st = os.stat(source) if hasattr(os, 'utime'): os.utime(dest, (st.st_atime, st.st_mtime)) -def copyfile(source, dest): - # type: (str, str) -> None +def copyfile(source: str, dest: str) -> None: """Copy a file and its modification times, if possible. Note: ``copyfile`` skips copying if the file has not been changed""" @@ -139,18 +127,15 @@ no_fn_re = re.compile(r'[^a-zA-Z0-9_-]') project_suffix_re = re.compile(' Documentation$') -def make_filename(string): - # type: (str) -> str +def make_filename(string: str) -> str: return no_fn_re.sub('', string) or 'sphinx' -def make_filename_from_project(project): - # type: (str) -> str +def make_filename_from_project(project: str) -> str: return make_filename(project_suffix_re.sub('', project)).lower() -def ustrftime(format, *args): - # type: (str, Any) -> str +def ustrftime(format: str, *args) -> str: """[DEPRECATED] strftime for unicode strings.""" warnings.warn('sphinx.util.osutil.ustrtime is deprecated for removal', RemovedInSphinx30Warning, stacklevel=2) @@ -171,8 +156,7 @@ def ustrftime(format, *args): return r.encode().decode('unicode-escape') -def relpath(path, start=os.curdir): - # type: (str, str) -> str +def relpath(path: str, start: str = os.curdir) -> str: """Return a relative filepath to *path* either from the current directory or from an optional *start* directory. @@ -189,8 +173,7 @@ safe_relpath = relpath # for compatibility fs_encoding = sys.getfilesystemencoding() or sys.getdefaultencoding() -def abspath(pathdir): - # type: (str) -> str +def abspath(pathdir: str) -> str: if isinstance(pathdir, Path): return pathdir.abspath() else: @@ -205,8 +188,7 @@ def abspath(pathdir): return pathdir -def getcwd(): - # type: () -> str +def getcwd() -> str: warnings.warn('sphinx.util.osutil.getcwd() is deprecated. ' 'Please use os.getcwd() instead.', RemovedInSphinx40Warning) @@ -214,8 +196,7 @@ def getcwd(): @contextlib.contextmanager -def cd(target_dir): - # type: (str) -> Iterator[None] +def cd(target_dir: str) -> Generator[None, None, None]: cwd = os.getcwd() try: os.chdir(target_dir) @@ -236,19 +217,16 @@ class FileAvoidWrite: Objects can be used as context managers. """ - def __init__(self, path): - # type: (str) -> None + def __init__(self, path: str) -> None: self._path = path self._io = None # type: StringIO - def write(self, data): - # type: (str) -> None + def write(self, data: str) -> None: if not self._io: self._io = StringIO() self._io.write(data) - def close(self): - # type: () -> None + def close(self) -> None: """Stop accepting writes and write file, if needed.""" if not self._io: raise Exception('FileAvoidWrite does not support empty files.') @@ -267,16 +245,14 @@ class FileAvoidWrite: with open(self._path, 'w') as f: f.write(buf) - def __enter__(self): - # type: () -> FileAvoidWrite + def __enter__(self) -> "FileAvoidWrite": return self - def __exit__(self, type, value, traceback): - # type: (str, str, str) -> None + def __exit__(self, exc_type: Type[Exception], exc_value: Exception, traceback: Any) -> bool: # NOQA self.close() + return True - def __getattr__(self, name): - # type: (str) -> Any + def __getattr__(self, name: str) -> Any: # Proxy to _io instance. if not self._io: raise Exception('Must write to FileAvoidWrite before other ' @@ -285,8 +261,7 @@ class FileAvoidWrite: return getattr(self._io, name) -def rmtree(path): - # type: (str) -> None +def rmtree(path: str) -> None: if os.path.isdir(path): shutil.rmtree(path) else: diff --git a/sphinx/util/parallel.py b/sphinx/util/parallel.py index 013dc3071..2d519a8d3 100644 --- a/sphinx/util/parallel.py +++ b/sphinx/util/parallel.py @@ -12,6 +12,7 @@ import os import time import traceback from math import sqrt +from typing import Any, Callable, Dict, List, Sequence try: import multiprocessing @@ -21,10 +22,6 @@ except ImportError: from sphinx.errors import SphinxParallelError from sphinx.util import logging -if False: - # For type annotation - from typing import Any, Callable, Dict, List, Sequence # NOQA - logger = logging.getLogger(__name__) @@ -35,12 +32,10 @@ parallel_available = multiprocessing and (os.name == 'posix') class SerialTasks: """Has the same interface as ParallelTasks, but executes tasks directly.""" - def __init__(self, nproc=1): - # type: (int) -> None + def __init__(self, nproc: int = 1) -> None: pass - def add_task(self, task_func, arg=None, result_func=None): - # type: (Callable, Any, Callable) -> None + def add_task(self, task_func: Callable, arg: Any = None, result_func: Callable = None) -> None: # NOQA if arg is not None: res = task_func(arg) else: @@ -48,16 +43,14 @@ class SerialTasks: if result_func: result_func(res) - def join(self): - # type: () -> None + def join(self) -> None: pass class ParallelTasks: """Executes *nproc* tasks in parallel after forking.""" - def __init__(self, nproc): - # type: (int) -> None + def __init__(self, nproc: int) -> None: self.nproc = nproc # (optional) function performed by each task on the result of main task self._result_funcs = {} # type: Dict[int, Callable] @@ -74,8 +67,7 @@ class ParallelTasks: # task number of each subprocess self._taskid = 0 - def _process(self, pipe, func, arg): - # type: (Any, Callable, Any) -> None + def _process(self, pipe: Any, func: Callable, arg: Any) -> None: try: collector = logging.LogCollector() with collector.collect(): @@ -91,8 +83,7 @@ class ParallelTasks: 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 + def add_task(self, task_func: Callable, arg: Any = None, result_func: Callable = None) -> None: # NOQA tid = self._taskid self._taskid += 1 self._result_funcs[tid] = result_func or (lambda arg, result: None) @@ -104,13 +95,11 @@ class ParallelTasks: self._precvsWaiting[tid] = precv self._join_one() - def join(self): - # type: () -> None + def join(self) -> None: while self._pworking: self._join_one() - def _join_one(self): - # type: () -> None + def _join_one(self) -> None: for tid, pipe in self._precvs.items(): if pipe.poll(): exc, logs, result = pipe.recv() @@ -132,8 +121,7 @@ class ParallelTasks: self._pworking += 1 -def make_chunks(arguments, nproc, maxbatch=10): - # type: (Sequence[str], int, int) -> List[Any] +def make_chunks(arguments: Sequence[str], nproc: int, maxbatch: int = 10) -> List[Any]: # determine how many documents to read in one go nargs = len(arguments) chunksize = nargs // nproc diff --git a/sphinx/util/png.py b/sphinx/util/png.py index 2fb97a901..911547db6 100644 --- a/sphinx/util/png.py +++ b/sphinx/util/png.py @@ -20,8 +20,7 @@ DEPTH_CHUNK_START = b'tEXtDepth\x00' IEND_CHUNK = b'\x00\x00\x00\x00IEND\xAE\x42\x60\x82' -def read_png_depth(filename): - # type: (str) -> int +def read_png_depth(filename: str) -> int: """Read the special tEXt chunk indicating the depth from a PNG file.""" with open(filename, 'rb') as f: f.seek(- (LEN_IEND + LEN_DEPTH), 2) @@ -33,8 +32,7 @@ def read_png_depth(filename): return struct.unpack('!i', depthchunk[14:18])[0] -def write_png_depth(filename, depth): - # type: (str, int) -> None +def write_png_depth(filename: str, depth: int) -> None: """Write the special tEXt chunk indicating the depth to a PNG file. The chunk is placed immediately before the special IEND chunk. diff --git a/sphinx/util/pycompat.py b/sphinx/util/pycompat.py index dca2849c2..06d3bcc2c 100644 --- a/sphinx/util/pycompat.py +++ b/sphinx/util/pycompat.py @@ -13,6 +13,7 @@ import io import sys import textwrap import warnings +from typing import Any, Callable from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias from sphinx.locale import __ @@ -20,10 +21,6 @@ from sphinx.util import logging from sphinx.util.console import terminal_safe from sphinx.util.typing import NoneType -if False: - # For type annotation - from typing import Any, Callable # NOQA - logger = logging.getLogger(__name__) @@ -33,8 +30,7 @@ logger = logging.getLogger(__name__) # convert_with_2to3(): # support for running 2to3 over config files -def convert_with_2to3(filepath): - # type: (str) -> str +def convert_with_2to3(filepath: str) -> str: from lib2to3.refactor import RefactoringTool, get_fixers_from_package from lib2to3.pgen2.parse import ParseError fixers = get_fixers_from_package('lib2to3.fixes') @@ -62,8 +58,7 @@ class UnicodeMixin: return self.__unicode__() -def execfile_(filepath, _globals, open=open): - # type: (str, Any, Callable) -> None +def execfile_(filepath: str, _globals: Any, open: Callable = open) -> None: from sphinx.util.osutil import fs_encoding with open(filepath, 'rb') as f: source = f.read() diff --git a/sphinx/util/requests.py b/sphinx/util/requests.py index dee52e281..a279b4eb4 100644 --- a/sphinx/util/requests.py +++ b/sphinx/util/requests.py @@ -10,11 +10,14 @@ import warnings from contextlib import contextmanager +from typing import Generator, Union from urllib.parse import urlsplit import pkg_resources import requests +from sphinx.config import Config + try: from requests.packages.urllib3.exceptions import SSLError except ImportError: @@ -54,17 +57,12 @@ else: pkg_resources.VersionConflict): pass # ignored -if False: - # For type annotation - from typing import Any, Generator, Union # NOQA - from sphinx.config import Config # NOQA useragent_header = [('User-Agent', 'Mozilla/5.0 (X11; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0')] -def is_ssl_error(exc): - # type: (Exception) -> bool +def is_ssl_error(exc: Exception) -> bool: """Check an exception is SSLError.""" if isinstance(exc, SSLError): return True @@ -77,8 +75,7 @@ def is_ssl_error(exc): @contextmanager -def ignore_insecure_warning(**kwargs): - # type: (Any) -> Generator +def ignore_insecure_warning(**kwargs) -> Generator[None, None, None]: with warnings.catch_warnings(): if not kwargs.get('verify') and InsecureRequestWarning: # ignore InsecureRequestWarning if verify=False @@ -86,8 +83,7 @@ def ignore_insecure_warning(**kwargs): yield -def _get_tls_cacert(url, config): - # type: (str, Config) -> Union[str, bool] +def _get_tls_cacert(url: str, config: Config) -> Union[str, bool]: """Get additional CA cert for a specific URL. This also returns ``False`` if verification is disabled. @@ -109,8 +105,7 @@ def _get_tls_cacert(url, config): return certs.get(hostname, True) -def get(url, **kwargs): - # type: (str, Any) -> requests.Response +def get(url: str, **kwargs) -> requests.Response: """Sends a GET request like requests.get(). This sets up User-Agent header and TLS verification automatically.""" @@ -123,8 +118,7 @@ def get(url, **kwargs): return requests.get(url, **kwargs) -def head(url, **kwargs): - # type: (str, Any) -> requests.Response +def head(url: str, **kwargs) -> requests.Response: """Sends a HEAD request like requests.head(). This sets up User-Agent header and TLS verification automatically.""" diff --git a/sphinx/util/rst.py b/sphinx/util/rst.py index c897b075a..0824e413f 100644 --- a/sphinx/util/rst.py +++ b/sphinx/util/rst.py @@ -11,23 +11,20 @@ import re from collections import defaultdict from contextlib import contextmanager +from typing import Dict, Generator from unicodedata import east_asian_width from docutils.parsers.rst import roles from docutils.parsers.rst.languages import en as english +from docutils.statemachine import StringList from docutils.utils import Reporter +from jinja2 import Environment from jinja2 import environmentfilter from sphinx.locale import __ from sphinx.util import docutils from sphinx.util import logging -if False: - # For type annotation - from typing import Callable, Dict, Generator # NOQA - from docutils.statemachine import StringList # NOQA - from jinja2 import Environment # NOQA - logger = logging.getLogger(__name__) docinfo_re = re.compile(':\\w+:.*?') @@ -40,18 +37,15 @@ WIDECHARS = defaultdict(lambda: "WF") # type: Dict[str, str] WIDECHARS["ja"] = "WFA" # In Japanese, Ambiguous characters also have double width -def escape(text): - # type: (str) -> str +def escape(text: str) -> str: text = symbols_re.sub(r'\\\1', text) text = re.sub(r'^\.', r'\.', text) # escape a dot at top return text -def textwidth(text, widechars='WF'): - # type: (str, str) -> int +def textwidth(text: str, widechars: str = 'WF') -> int: """Get width of text.""" - def charwidth(char, widechars): - # type: (str, str) -> int + def charwidth(char: str, widechars: str) -> int: if east_asian_width(char) in widechars: return 2 else: @@ -61,8 +55,7 @@ def textwidth(text, widechars='WF'): @environmentfilter -def heading(env, text, level=1): - # type: (Environment, str, int) -> str +def heading(env: Environment, text: str, level: int = 1) -> str: """Create a heading for *level*.""" assert level <= 3 width = textwidth(text, WIDECHARS[env.language]) # type: ignore @@ -71,8 +64,7 @@ def heading(env, text, level=1): @contextmanager -def default_role(docname, name): - # type: (str, str) -> Generator +def default_role(docname: str, name: str) -> Generator[None, None, None]: if name: dummy_reporter = Reporter('', 4, 4) role_fn, _ = roles.role(name, english, 0, dummy_reporter) @@ -86,8 +78,7 @@ def default_role(docname, name): docutils.unregister_role('') -def prepend_prolog(content, prolog): - # type: (StringList, str) -> None +def prepend_prolog(content: StringList, prolog: str) -> None: """Prepend a string to content body as prolog.""" if prolog: pos = 0 @@ -109,8 +100,7 @@ def prepend_prolog(content, prolog): content.insert(pos + lineno + 1, '', '<generated>', 0) -def append_epilog(content, epilog): - # type: (StringList, str) -> None +def append_epilog(content: StringList, epilog: str) -> None: """Append a string to content body as epilog.""" if epilog: content.append('', '<generated>', 0) diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py index 7450e07b8..47f8b59b2 100644 --- a/sphinx/util/smartypants.py +++ b/sphinx/util/smartypants.py @@ -26,14 +26,12 @@ """ import re +from typing import Generator, Iterable, Tuple from docutils.utils import smartquotes from sphinx.util.docutils import __version_info__ as docutils_version -if False: # For type annotation - from typing import Generator, Iterable, Tuple # NOQA - langquotes = {'af': '“”‘’', 'af-x-altquot': '„”‚’', @@ -125,8 +123,7 @@ langquotes = {'af': '“”‘’', } -def educateQuotes(text, language='en'): - # type: (str, str) -> str +def educateQuotes(text: str, language: str = 'en') -> str: """ Parameter: - text string (unicode or bytes). - language (`BCP 47` language tag.) @@ -240,8 +237,10 @@ def educateQuotes(text, language='en'): return text -def educate_tokens(text_tokens, attr=smartquotes.default_smartypants_attr, language='en'): - # type: (Iterable[Tuple[str, str]], str, str) -> Generator[str, None, None] +def educate_tokens(text_tokens: Iterable[Tuple[str, str]], + attr: str = smartquotes.default_smartypants_attr, + language: str = 'en' + ) -> Generator[str, None, None]: """Return iterator that "educates" the items of `text_tokens`. This is modified to intercept the ``attr='2'`` as it was used by the diff --git a/sphinx/util/stemmer/__init__.py b/sphinx/util/stemmer/__init__.py index 047aac708..bda5d2bc2 100644 --- a/sphinx/util/stemmer/__init__.py +++ b/sphinx/util/stemmer/__init__.py @@ -18,18 +18,15 @@ except ImportError: class BaseStemmer: - def stem(self, word): - # type: (str) -> str + def stem(self, word: str) -> str: raise NotImplementedError() class PyStemmer(BaseStemmer): - def __init__(self): - # type: () -> None + def __init__(self) -> None: self.stemmer = _PyStemmer('porter') - def stem(self, word): - # type: (str) -> str + def stem(self, word: str) -> str: return self.stemmer.stemWord(word) @@ -37,13 +34,11 @@ class StandardStemmer(PorterStemmer, BaseStemmer): # type: ignore """All those porter stemmer implementations look hideous; make at least the stem method nicer. """ - def stem(self, word): # type: ignore - # type: (str) -> str + def stem(self, word: str) -> str: # type: ignore return super().stem(word, 0, len(word) - 1) -def get_stemmer(): - # type: () -> BaseStemmer +def get_stemmer() -> BaseStemmer: if PYSTEMMER: return PyStemmer() else: diff --git a/sphinx/util/stemmer/porter.py b/sphinx/util/stemmer/porter.py index 51c132c2c..1f979624a 100644 --- a/sphinx/util/stemmer/porter.py +++ b/sphinx/util/stemmer/porter.py @@ -30,8 +30,7 @@ class PorterStemmer: - def __init__(self): - # type: () -> None + def __init__(self) -> None: """The main part of the stemming algorithm starts here. b is a buffer holding a word to be stemmed. The letters are in b[k0], b[k0+1] ... ending at b[k]. In fact k0 = 0 in this demo program. k is @@ -47,8 +46,7 @@ class PorterStemmer: self.k0 = 0 self.j = 0 # j is a general offset into the string - def cons(self, i): - # type: (int) -> int + def cons(self, i: int) -> int: """cons(i) is TRUE <=> b[i] is a consonant.""" if self.b[i] == 'a' or self.b[i] == 'e' or self.b[i] == 'i' \ or self.b[i] == 'o' or self.b[i] == 'u': @@ -60,8 +58,7 @@ class PorterStemmer: return (not self.cons(i - 1)) return 1 - def m(self): - # type: () -> int + def m(self) -> int: """m() measures the number of consonant sequences between k0 and j. if c is a consonant sequence and v a vowel sequence, and <..> indicates arbitrary presence, @@ -98,16 +95,14 @@ class PorterStemmer: i = i + 1 i = i + 1 - def vowelinstem(self): - # type: () -> int + def vowelinstem(self) -> int: """vowelinstem() is TRUE <=> k0,...j contains a vowel""" for i in range(self.k0, self.j + 1): if not self.cons(i): return 1 return 0 - def doublec(self, j): - # type: (int) -> int + def doublec(self, j: int) -> int: """doublec(j) is TRUE <=> j,(j-1) contain a double consonant.""" if j < (self.k0 + 1): return 0 @@ -115,8 +110,7 @@ class PorterStemmer: return 0 return self.cons(j) - def cvc(self, i): - # type: (int) -> int + def cvc(self, i: int) -> int: """cvc(i) is TRUE <=> i-2,i-1,i has the form consonant - vowel - consonant and also if the second c is not w,x or y. this is used when trying to @@ -133,8 +127,7 @@ class PorterStemmer: return 0 return 1 - def ends(self, s): - # type: (str) -> int + def ends(self, s: str) -> int: """ends(s) is TRUE <=> k0,...k ends with the string s.""" length = len(s) if s[length - 1] != self.b[self.k]: # tiny speed-up @@ -146,22 +139,19 @@ class PorterStemmer: self.j = self.k - length return 1 - def setto(self, s): - # type: (str) -> None + def setto(self, s: str) -> None: """setto(s) sets (j+1),...k to the characters in the string s, readjusting k.""" length = len(s) self.b = self.b[:self.j + 1] + s + self.b[self.j + length + 1:] self.k = self.j + length - def r(self, s): - # type: (str) -> None + def r(self, s: str) -> None: """r(s) is used further down.""" if self.m() > 0: self.setto(s) - def step1ab(self): - # type: () -> None + def step1ab(self) -> None: """step1ab() gets rid of plurals and -ed or -ing. e.g. caresses -> caress @@ -208,15 +198,13 @@ class PorterStemmer: elif (self.m() == 1 and self.cvc(self.k)): self.setto("e") - def step1c(self): - # type: () -> None + def step1c(self) -> None: """step1c() turns terminal y to i when there is another vowel in the stem.""" if (self.ends("y") and self.vowelinstem()): self.b = self.b[:self.k] + 'i' + self.b[self.k + 1:] - def step2(self): - # type: () -> None + def step2(self) -> None: """step2() maps double suffices to single ones. so -ization ( = -ize plus -ation) maps to -ize etc. note that the string before the suffix must give m() > 0. @@ -275,8 +263,7 @@ class PorterStemmer: self.r("log") # To match the published algorithm, delete this phrase - def step3(self): - # type: () -> None + def step3(self) -> None: """step3() dels with -ic-, -full, -ness etc. similar strategy to step2.""" if self.b[self.k] == 'e': @@ -298,8 +285,7 @@ class PorterStemmer: if self.ends("ness"): self.r("") - def step4(self): - # type: () -> None + def step4(self) -> None: """step4() takes off -ant, -ence etc., in context <c>vcvc<v>.""" if self.b[self.k - 1] == 'a': if self.ends("al"): @@ -382,8 +368,7 @@ class PorterStemmer: if self.m() > 1: self.k = self.j - def step5(self): - # type: () -> None + def step5(self) -> None: """step5() removes a final -e if m() > 1, and changes -ll to -l if m() > 1. """ @@ -395,8 +380,7 @@ class PorterStemmer: if self.b[self.k] == 'l' and self.doublec(self.k) and self.m() > 1: self.k = self.k - 1 - def stem(self, p, i, j): - # type: (str, int, int) -> str + def stem(self, p: str, i: int, j: int) -> str: """In stem(p,i,j), p is a char pointer, and the string to be stemmed is from p[i] to p[j] inclusive. Typically i is zero and j is the offset to the last character of a string, (p[j+1] == '\0'). The diff --git a/sphinx/util/tags.py b/sphinx/util/tags.py index 193e7ef1e..7e7ba4661 100644 --- a/sphinx/util/tags.py +++ b/sphinx/util/tags.py @@ -6,26 +6,23 @@ :license: BSD, see LICENSE for details. """ -# (ab)use the Jinja parser for parsing our boolean expressions +from typing import Iterator, List + from jinja2 import nodes from jinja2.environment import Environment +from jinja2.nodes import Node from jinja2.parser import Parser env = Environment() -if False: - # For type annotation - from typing import Iterator, List # NOQA - class BooleanParser(Parser): """ Only allow condition exprs and/or/not operations. """ - def parse_compare(self): - # type: () -> nodes.Node - node = None # type: nodes.Node + def parse_compare(self) -> Node: + node = None # type: Node token = self.stream.current if token.type == 'name': if token.value in ('true', 'false', 'True', 'False'): @@ -46,38 +43,31 @@ class BooleanParser(Parser): class Tags: - def __init__(self, tags=None): - # type: (List[str]) -> None + def __init__(self, tags: List[str] = None) -> None: self.tags = dict.fromkeys(tags or [], True) - def has(self, tag): - # type: (str) -> bool + def has(self, tag: str) -> bool: return tag in self.tags __contains__ = has - def __iter__(self): - # type: () -> Iterator[str] + def __iter__(self) -> Iterator[str]: return iter(self.tags) - def add(self, tag): - # type: (str) -> None + def add(self, tag: str) -> None: self.tags[tag] = True - def remove(self, tag): - # type: (str) -> None + def remove(self, tag: str) -> None: self.tags.pop(tag, None) - def eval_condition(self, condition): - # type: (str) -> bool + def eval_condition(self, condition: str) -> bool: # exceptions are handled by the caller parser = BooleanParser(env, condition, state='variable') expr = parser.parse_expression() if not parser.stream.eos: raise ValueError('chunk after expression') - def eval_node(node): - # type: (nodes.Node) -> bool + def eval_node(node: Node) -> bool: if isinstance(node, nodes.CondExpr): if eval_node(node.test): # type: ignore return eval_node(node.expr1) # type: ignore diff --git a/sphinx/util/template.py b/sphinx/util/template.py index b521c5c79..636767d41 100644 --- a/sphinx/util/template.py +++ b/sphinx/util/template.py @@ -9,7 +9,9 @@ """ import os +from typing import Dict +from jinja2.loaders import BaseLoader from jinja2.sandbox import SandboxedEnvironment from sphinx import package_dir @@ -17,58 +19,45 @@ from sphinx.jinja2glue import SphinxFileSystemLoader from sphinx.locale import get_translator from sphinx.util import rst, texescape -if False: - # For type annotation - from typing import Dict # NOQA - from jinja2.loaders import BaseLoader # NOQA - class BaseRenderer: - def __init__(self, loader=None): - # type: (BaseLoader) -> None + def __init__(self, loader: BaseLoader = None) -> None: self.env = SandboxedEnvironment(loader=loader, extensions=['jinja2.ext.i18n']) self.env.filters['repr'] = repr self.env.install_gettext_translations(get_translator()) # type: ignore - def render(self, template_name, context): - # type: (str, Dict) -> str + def render(self, template_name: str, context: Dict) -> str: return self.env.get_template(template_name).render(context) - def render_string(self, source, context): - # type: (str, Dict) -> str + def render_string(self, source: str, context: Dict) -> str: return self.env.from_string(source).render(context) class FileRenderer(BaseRenderer): - def __init__(self, search_path): - # type: (str) -> None + def __init__(self, search_path: str) -> None: loader = SphinxFileSystemLoader(search_path) super().__init__(loader) @classmethod - def render_from_file(cls, filename, context): - # type: (str, Dict) -> str + def render_from_file(cls, filename: str, context: Dict) -> str: dirname = os.path.dirname(filename) basename = os.path.basename(filename) return cls(dirname).render(basename, context) class SphinxRenderer(FileRenderer): - def __init__(self, template_path=None): - # type: (str) -> None + def __init__(self, template_path: str = None) -> None: if template_path is None: template_path = os.path.join(package_dir, 'templates') super().__init__(template_path) @classmethod - def render_from_file(cls, filename, context): - # type: (str, Dict) -> str + def render_from_file(cls, filename: str, context: Dict) -> str: return FileRenderer.render_from_file(filename, context) class LaTeXRenderer(SphinxRenderer): - def __init__(self, template_path=None): - # type: (str) -> None + def __init__(self, template_path: str = None) -> None: if template_path is None: template_path = os.path.join(package_dir, 'templates', 'latex') super().__init__(template_path) @@ -87,8 +76,7 @@ class LaTeXRenderer(SphinxRenderer): class ReSTRenderer(SphinxRenderer): - def __init__(self, template_path=None, language=None): - # type: (str, str) -> None + def __init__(self, template_path: str = None, language: str = None) -> None: super().__init__(template_path) # add language to environment diff --git a/sphinx/util/texescape.py b/sphinx/util/texescape.py index cc8c0fe1e..408ec1253 100644 --- a/sphinx/util/texescape.py +++ b/sphinx/util/texescape.py @@ -9,10 +9,7 @@ """ import re - -if False: - # For type annotation - from typing import Dict # NOQA +from typing import Dict tex_replacements = [ # map TeX special chars @@ -78,20 +75,17 @@ tex_replace_map = {} tex_hl_escape_map_new = {} -def escape(s): - # type: (str) -> str +def escape(s: str) -> str: """Escape text for LaTeX output.""" return s.translate(tex_escape_map) -def escape_abbr(text): - # type: (str) -> str +def escape_abbr(text: str) -> str: """Adjust spacing after abbreviations. Works with @ letter or other.""" return re.sub(r'\.(?=\s|$)', r'.\@{}', text) -def init(): - # type: () -> None +def init() -> None: for a, b in tex_replacements: tex_escape_map[ord(a)] = b tex_replace_map[ord(a)] = '_' diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py index 77724d38b..67f396e73 100644 --- a/sphinx/util/typing.py +++ b/sphinx/util/typing.py @@ -27,7 +27,7 @@ NoneType = type(None) PathMatcher = Callable[[str], bool] # common role functions -RoleFunction = Callable[[str, str, str, int, Inliner, Dict, List[str]], +RoleFunction = Callable[[str, str, str, int, Inliner, Dict[str, Any], List[str]], Tuple[List[nodes.Node], List[nodes.system_message]]] # title getter functions for enumerable nodes (see sphinx.domains.std) diff --git a/tests/roots/test-ext-autodoc/target/__init__.py b/tests/roots/test-ext-autodoc/target/__init__.py index c60bab20b..f6970a36c 100644 --- a/tests/roots/test-ext-autodoc/target/__init__.py +++ b/tests/roots/test-ext-autodoc/target/__init__.py @@ -22,31 +22,6 @@ class CustomEx(Exception): """Exception method.""" -class CustomDataDescriptor(object): - """Descriptor class docstring.""" - - def __init__(self, doc): - self.__doc__ = doc - - def __get__(self, obj, type=None): - if obj is None: - return self - return 42 - - def meth(self): - """Function.""" - return "The Answer" - - -class CustomDataDescriptorMeta(type): - """Descriptor metaclass docstring.""" - - -class CustomDataDescriptor2(CustomDataDescriptor): - """Descriptor class with custom metaclass docstring.""" - __metaclass__ = CustomDataDescriptorMeta - - def _funky_classmethod(name, b, c, d, docstring=None): """Generates a classmethod for a class from a template by filling out some arguments.""" @@ -59,30 +34,9 @@ def _funky_classmethod(name, b, c, d, docstring=None): return classmethod(function) -class Base(object): - def inheritedmeth(self): - """Inherited function.""" - - @classmethod - def inheritedclassmeth(cls): - """Inherited class method.""" - - @staticmethod - def inheritedstaticmeth(cls): - """Inherited static method.""" - - -class Derived(Base): - def inheritedmeth(self): - # no docstring here - pass - - -class Class(Base): +class Class(object): """Class to document.""" - descr = CustomDataDescriptor("Descriptor instance docstring.") - def meth(self): """Function.""" @@ -101,10 +55,6 @@ class Class(Base): #: should be documented -- süß attr = 'bar' - @property - def prop(self): - """Property.""" - docattr = 'baz' """should likewise be documented -- süß""" diff --git a/tests/roots/test-ext-autodoc/target/autoclass_content.py b/tests/roots/test-ext-autodoc/target/autoclass_content.py new file mode 100644 index 000000000..8924ab09b --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/autoclass_content.py @@ -0,0 +1,35 @@ +class A: + """A class having no __init__, no __new__""" + + +class B: + """A class having __init__(no docstring), no __new__""" + def __init__(self): + pass + + +class C: + """A class having __init__, no __new__""" + def __init__(self): + """__init__ docstring""" + + +class D: + """A class having no __init__, __new__(no docstring)""" + def __new__(cls): + pass + + +class E: + """A class having no __init__, __new__""" + def __new__(cls): + """__new__ docstring""" + + +class F: + """A class having both __init__ and __new__""" + def __init__(self): + """__init__ docstring""" + + def __new__(cls): + """__new__ docstring""" diff --git a/tests/roots/test-ext-autodoc/target/descriptor.py b/tests/roots/test-ext-autodoc/target/descriptor.py new file mode 100644 index 000000000..63d179b65 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/descriptor.py @@ -0,0 +1,31 @@ +class CustomDataDescriptor(object): + """Descriptor class docstring.""" + + def __init__(self, doc): + self.__doc__ = doc + + def __get__(self, obj, type=None): + if obj is None: + return self + return 42 + + def meth(self): + """Function.""" + return "The Answer" + + +class CustomDataDescriptorMeta(type): + """Descriptor metaclass docstring.""" + + +class CustomDataDescriptor2(CustomDataDescriptor): + """Descriptor class with custom metaclass docstring.""" + __metaclass__ = CustomDataDescriptorMeta + + +class Class: + descr = CustomDataDescriptor("Descriptor instance docstring.") + + @property + def prop(self): + """Property.""" diff --git a/tests/roots/test-ext-autodoc/target/docstring_signature.py b/tests/roots/test-ext-autodoc/target/docstring_signature.py new file mode 100644 index 000000000..2e5499770 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/docstring_signature.py @@ -0,0 +1,19 @@ +class A: + """A(foo, bar)""" + + +class B: + """B(foo, bar)""" + def __init__(self): + """B(foo, bar, baz)""" + + +class C: + """C(foo, bar)""" + def __new__(cls): + """C(foo, bar, baz)""" + + +class D: + def __init__(self): + """D(foo, bar, baz)""" diff --git a/tests/roots/test-ext-autodoc/target/inheritance.py b/tests/roots/test-ext-autodoc/target/inheritance.py new file mode 100644 index 000000000..3a5fc0711 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/inheritance.py @@ -0,0 +1,19 @@ +class Base(object): + def inheritedmeth(self): + """Inherited function.""" + + @classmethod + def inheritedclassmeth(cls): + """Inherited class method.""" + + @staticmethod + def inheritedstaticmeth(cls): + """Inherited static method.""" + + +class Derived(Base): + def inheritedmeth(self): + # no docstring here + pass + + diff --git a/tests/roots/test-ext-autodoc/target/module.py b/tests/roots/test-ext-autodoc/target/module.py deleted file mode 100644 index d5b557d94..000000000 --- a/tests/roots/test-ext-autodoc/target/module.py +++ /dev/null @@ -1,4 +0,0 @@ -#: docstring for CONSTANT1 -CONSTANT1 = "" - -CONSTANT2 = "" diff --git a/tests/roots/test-ext-autodoc/target/process_docstring.py b/tests/roots/test-ext-autodoc/target/process_docstring.py new file mode 100644 index 000000000..6005943b6 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/process_docstring.py @@ -0,0 +1,8 @@ +def func(): + """ + first line + --- + second line + --- + third line + """ diff --git a/tests/roots/test-roles-download/another/dummy.dat b/tests/roots/test-roles-download/another/dummy.dat new file mode 100644 index 000000000..f6d9fed11 --- /dev/null +++ b/tests/roots/test-roles-download/another/dummy.dat @@ -0,0 +1 @@ +this one will have some content diff --git a/tests/roots/test-roles-download/index.rst b/tests/roots/test-roles-download/index.rst index 41cda621a..cdb075ef3 100644 --- a/tests/roots/test-roles-download/index.rst +++ b/tests/roots/test-roles-download/index.rst @@ -2,5 +2,6 @@ test-roles-download =================== * :download:`dummy.dat` +* :download:`another/dummy.dat` * :download:`not_found.dat` * :download:`Sphinx logo <http://www.sphinx-doc.org/en/master/_static/sphinxheader.png>` diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index ad6a56d33..5cad89cdf 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -9,7 +9,6 @@ :license: BSD, see LICENSE for details. """ -import platform import sys from unittest.mock import Mock from warnings import catch_warnings @@ -17,10 +16,7 @@ from warnings import catch_warnings import pytest from docutils.statemachine import ViewList -from sphinx.ext.autodoc import ( - ModuleLevelDocumenter, cut_lines, between, ALL, - merge_autodoc_default_flags, Options -) +from sphinx.ext.autodoc import ModuleLevelDocumenter, ALL, Options from sphinx.ext.autodoc.directive import DocumenterBridge, process_documenter_options from sphinx.testing.util import SphinxTestApp, Struct # NOQA from sphinx.util import logging @@ -28,8 +24,6 @@ from sphinx.util.docutils import LoggingReporter app = None -IS_PYPY = platform.python_implementation() == 'PyPy' - def do_autodoc(app, objtype, name, options=None): if options is None: @@ -58,7 +52,6 @@ def setup_module(rootdir, sphinx_test_tempdir): app = SphinxTestApp(srcdir=srcdir) app.builder.env.app = app app.builder.env.temp_data['docname'] = 'dummy' - app.connect('autodoc-process-docstring', process_docstring) app.connect('autodoc-process-signature', process_signature) app.connect('autodoc-skip-member', skip_member) yield @@ -73,7 +66,7 @@ directive = options = None @pytest.fixture def setup_test(): global options, directive - global processed_docstrings, processed_signatures + global processed_signatures options = Options( inherited_members = False, @@ -102,7 +95,6 @@ def setup_test(): ) directive.state.document.settings.tab_width = 8 - processed_docstrings = [] processed_signatures = [] app._status.truncate(0) @@ -113,16 +105,9 @@ def setup_test(): app.registry.autodoc_attrgettrs.clear() -processed_docstrings = [] processed_signatures = [] -def process_docstring(app, what, name, obj, options, lines): - processed_docstrings.append((what, name)) - if name == 'bar': - lines.extend(['42', '']) - - def process_signature(app, what, name, obj, options, args, retann): processed_signatures.append((what, name)) if name == 'bar': @@ -340,127 +325,6 @@ def test_get_doc(): """Döcstring""" assert getdocl('function', f) == ['Döcstring'] - # class docstring: depends on config value which one is taken - class C: - """Class docstring""" - def __init__(self): - """Init docstring""" - - def __new__(cls): - """New docstring""" - directive.env.config.autoclass_content = 'class' - assert getdocl('class', C) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', C) == ['Init docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', C) == ['Class docstring', '', 'Init docstring'] - - class D: - """Class docstring""" - def __init__(self): - """Init docstring - - Other - lines - """ - - # Indentation is normalized for 'both' - assert getdocl('class', D) == ['Class docstring', '', 'Init docstring', - '', 'Other', ' lines'] - - # __init__ have signature at first line of docstring - class E: - """Class docstring""" - def __init__(self, *args, **kw): - """ - __init__(a1, a2, kw1=True, kw2=False) - - Init docstring - """ - - # signature line in the docstring will be kept when - # autodoc_docstring_signature == False - directive.env.config.autodoc_docstring_signature = False - directive.env.config.autoclass_content = 'class' - assert getdocl('class', E) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', E) == ['__init__(a1, a2, kw1=True, kw2=False)', - '', 'Init docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', E) == ['Class docstring', '', - '__init__(a1, a2, kw1=True, kw2=False)', - '', 'Init docstring'] - - # signature line in the docstring will be removed when - # autodoc_docstring_signature == True - directive.env.config.autodoc_docstring_signature = True # default - directive.env.config.autoclass_content = 'class' - assert getdocl('class', E) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', E) == ['Init docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', E) == ['Class docstring', '', 'Init docstring'] - - # class does not have __init__ method - class F: - """Class docstring""" - - # docstring in the __init__ method of base class will be discard - for f in (False, True): - directive.env.config.autodoc_docstring_signature = f - directive.env.config.autoclass_content = 'class' - assert getdocl('class', F) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', F) == ['Class docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', F) == ['Class docstring'] - - # class has __init__ method with no docstring - class G: - """Class docstring""" - def __init__(self): - pass - - # docstring in the __init__ method of base class will not be used - for f in (False, True): - directive.env.config.autodoc_docstring_signature = f - directive.env.config.autoclass_content = 'class' - assert getdocl('class', G) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', G) == ['Class docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', G) == ['Class docstring'] - - # class has __new__ method with docstring - # class docstring: depends on config value which one is taken - class H: - """Class docstring""" - def __init__(self): - pass - - def __new__(cls): - """New docstring""" - directive.env.config.autoclass_content = 'class' - assert getdocl('class', H) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', H) == ['New docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', H) == ['Class docstring', '', 'New docstring'] - - # class has __init__ method without docstring and - # __new__ method with docstring - # class docstring: depends on config value which one is taken - class I: # NOQA - """Class docstring""" - def __new__(cls): - """New docstring""" - directive.env.config.autoclass_content = 'class' - assert getdocl('class', I) == ['Class docstring'] - directive.env.config.autoclass_content = 'init' - assert getdocl('class', I) == ['New docstring'] - directive.env.config.autoclass_content = 'both' - assert getdocl('class', I) == ['Class docstring', '', 'New docstring'] - # verify that method docstrings get extracted in both normal case # and in case of bound method posing as a function class J: # NOQA @@ -469,70 +333,6 @@ def test_get_doc(): assert getdocl('method', J.foo) == ['Method docstring'] assert getdocl('function', J().foo) == ['Method docstring'] - from target import Base, Derived - - # NOTE: inspect.getdoc seems not to work with locally defined classes - directive.env.config.autodoc_inherit_docstrings = False - assert getdocl('method', Base.inheritedmeth) == ['Inherited function.'] - assert getdocl('method', Derived.inheritedmeth) == [] - directive.env.config.autodoc_inherit_docstrings = True - assert getdocl('method', Derived.inheritedmeth) == ['Inherited function.'] - - -@pytest.mark.usefixtures('setup_test') -def test_docstring_processing(): - def process(objtype, name, obj): - inst = app.registry.documenters[objtype](directive, name) - inst.object = obj - inst.fullname = name - return list(inst.process_doc(inst.get_doc())) - - class E: - def __init__(self): - """Init docstring""" - - # docstring processing by event handler - assert process('class', 'bar', E) == ['Init docstring', '', '42', ''] - - lid = app.connect('autodoc-process-docstring', - cut_lines(1, 1, ['function'])) - - def f(): - """ - first line - second line - third line - """ - assert process('function', 'f', f) == ['second line', ''] - app.disconnect(lid) - - lid = app.connect('autodoc-process-docstring', between('---', ['function'])) - - def g(): - """ - first line - --- - second line - --- - third line - """ - assert process('function', 'g', g) == ['second line', ''] - app.disconnect(lid) - - lid = app.connect('autodoc-process-docstring', - between('---', ['function'], exclude=True)) - - def h(): - """ - first line - --- - second line - --- - third line - """ - assert process('function', 'h', h) == ['first line', 'third line', ''] - app.disconnect(lid) - @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_new_documenter(app): @@ -568,6 +368,7 @@ def test_new_documenter(app): @pytest.mark.usefixtures('setup_test') def test_attrgetter_using(): from target import Class + from target.inheritance import Derived def assert_getter_works(objtype, name, obj, attrs=[], **kw): getattr_spy = [] @@ -597,7 +398,7 @@ def test_attrgetter_using(): assert_getter_works('class', 'target.Class', Class, ['meth']) options.inherited_members = True - assert_getter_works('class', 'target.Class', Class, ['meth', 'inheritedmeth']) + assert_getter_works('class', 'target.inheritance.Derived', Derived, ['inheritedmeth']) @pytest.mark.sphinx('html', testroot='ext-autodoc') @@ -700,14 +501,14 @@ def test_autodoc_attributes(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_members(app): # default (no-members) - actual = do_autodoc(app, 'class', 'target.Base') + actual = do_autodoc(app, 'class', 'target.inheritance.Base') assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Base', ] # default ALL-members options = {"members": None} - actual = do_autodoc(app, 'class', 'target.Base', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Base', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Base', ' .. py:method:: Base.inheritedclassmeth()', @@ -717,7 +518,7 @@ def test_autodoc_members(app): # default specific-members options = {"members": "inheritedmeth,inheritedstaticmeth"} - actual = do_autodoc(app, 'class', 'target.Base', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Base', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Base', ' .. py:method:: Base.inheritedmeth()', @@ -729,7 +530,7 @@ def test_autodoc_members(app): def test_autodoc_exclude_members(app): options = {"members": None, "exclude-members": "inheritedmeth,inheritedstaticmeth"} - actual = do_autodoc(app, 'class', 'target.Base', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Base', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Base', ' .. py:method:: Base.inheritedclassmeth()' @@ -738,7 +539,7 @@ def test_autodoc_exclude_members(app): # members vs exclude-members options = {"members": "inheritedmeth", "exclude-members": "inheritedmeth"} - actual = do_autodoc(app, 'class', 'target.Base', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Base', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Base', ] @@ -752,7 +553,6 @@ def test_autodoc_undoc_members(app): assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Class(arg)', ' .. py:attribute:: Class.attr', - ' .. py:attribute:: Class.descr', ' .. py:attribute:: Class.docattr', ' .. py:method:: Class.excludemeth()', ' .. py:attribute:: Class.inst_attr_comment', @@ -761,7 +561,6 @@ def test_autodoc_undoc_members(app): ' .. py:attribute:: Class.mdocattr', ' .. py:method:: Class.meth()', ' .. py:method:: Class.moore(a, e, f) -> happiness', - ' .. py:method:: Class.prop', ' .. py:method:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)', ' .. py:attribute:: Class.skipattr', ' .. py:method:: Class.skipmeth()', @@ -774,16 +573,11 @@ def test_autodoc_undoc_members(app): def test_autodoc_inherited_members(app): options = {"members": None, "inherited-members": None} - actual = do_autodoc(app, 'class', 'target.Class', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Derived', options) assert list(filter(lambda l: 'method::' in l, actual)) == [ - ' .. py:method:: Class.excludemeth()', - ' .. py:method:: Class.inheritedclassmeth()', - ' .. py:method:: Class.inheritedmeth()', - ' .. py:method:: Class.inheritedstaticmeth(cls)', - ' .. py:method:: Class.meth()', - ' .. py:method:: Class.moore(a, e, f) -> happiness', - ' .. py:method:: Class.prop', - ' .. py:method:: Class.skipmeth()' + ' .. py:method:: Derived.inheritedclassmeth()', + ' .. py:method:: Derived.inheritedmeth()', + ' .. py:method:: Derived.inheritedstaticmeth(cls)', ] @@ -828,12 +622,13 @@ def test_autodoc_special_members(app): actual = do_autodoc(app, 'class', 'target.Class', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Class(arg)', + ' .. py:attribute:: Class.__dict__', ' .. py:method:: Class.__init__(arg)', ' .. py:attribute:: Class.__module__', ' .. py:method:: Class.__special1__()', ' .. py:method:: Class.__special2__()', + ' .. py:attribute:: Class.__weakref__', ' .. py:attribute:: Class.attr', - ' .. py:attribute:: Class.descr', ' .. py:attribute:: Class.docattr', ' .. py:method:: Class.excludemeth()', ' .. py:attribute:: Class.inst_attr_comment', @@ -842,7 +637,6 @@ def test_autodoc_special_members(app): ' .. py:attribute:: Class.mdocattr', ' .. py:method:: Class.meth()', ' .. py:method:: Class.moore(a, e, f) -> happiness', - ' .. py:method:: Class.prop', ' .. py:method:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)', ' .. py:attribute:: Class.skipattr', ' .. py:method:: Class.skipmeth()', @@ -866,9 +660,6 @@ def test_autodoc_ignore_module_all(app): actual = do_autodoc(app, 'module', 'target', options) assert list(filter(lambda l: 'class::' in l, actual)) == [ '.. py:class:: Class(arg)', - '.. py:class:: CustomDataDescriptor(doc)', - '.. py:class:: CustomDataDescriptor2(doc)', - '.. py:class:: CustomDataDescriptorMeta', '.. py:class:: CustomDict', '.. py:class:: InstAttCls()', '.. py:class:: Outer', @@ -890,12 +681,12 @@ def test_autodoc_noindex(app): # TODO: :noindex: should be propagated to children of target item. - actual = do_autodoc(app, 'class', 'target.Base', options) + actual = do_autodoc(app, 'class', 'target.inheritance.Base', options) assert list(actual) == [ '', '.. py:class:: Base', ' :noindex:', - ' :module: target', + ' :module: target.inheritance', '' ] @@ -963,11 +754,11 @@ def test_autodoc_inner_class(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_classmethod(app): - actual = do_autodoc(app, 'method', 'target.Base.inheritedclassmeth') + actual = do_autodoc(app, 'method', 'target.inheritance.Base.inheritedclassmeth') assert list(actual) == [ '', '.. py:method:: Base.inheritedclassmeth()', - ' :module: target', + ' :module: target.inheritance', ' :classmethod:', '', ' Inherited class method.', @@ -977,11 +768,11 @@ def test_autodoc_classmethod(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_staticmethod(app): - actual = do_autodoc(app, 'method', 'target.Base.inheritedstaticmeth') + actual = do_autodoc(app, 'method', 'target.inheritance.Base.inheritedstaticmeth') assert list(actual) == [ '', '.. py:method:: Base.inheritedstaticmeth(cls)', - ' :module: target', + ' :module: target.inheritance', ' :staticmethod:', '', ' Inherited static method.', @@ -991,14 +782,27 @@ def test_autodoc_staticmethod(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_descriptor(app): - actual = do_autodoc(app, 'attribute', 'target.Class.descr') + options = {"members": None, + "undoc-members": True} + actual = do_autodoc(app, 'class', 'target.descriptor.Class', options) assert list(actual) == [ '', - '.. py:attribute:: Class.descr', - ' :module: target', + '.. py:class:: Class', + ' :module: target.descriptor', '', - ' Descriptor instance docstring.', - ' ' + ' ', + ' .. py:attribute:: Class.descr', + ' :module: target.descriptor', + ' ', + ' Descriptor instance docstring.', + ' ', + ' ', + ' .. py:method:: Class.prop', + ' :module: target.descriptor', + ' :property:', + ' ', + ' Property.', + ' ' ] @@ -1027,14 +831,12 @@ def test_autodoc_member_order(app): actual = do_autodoc(app, 'class', 'target.Class', options) assert list(filter(lambda l: '::' in l, actual)) == [ '.. py:class:: Class(arg)', - ' .. py:attribute:: Class.descr', ' .. py:method:: Class.meth()', ' .. py:method:: Class.undocmeth()', ' .. py:method:: Class.skipmeth()', ' .. py:method:: Class.excludemeth()', ' .. py:attribute:: Class.skipattr', ' .. py:attribute:: Class.attr', - ' .. py:method:: Class.prop', ' .. py:attribute:: Class.docattr', ' .. py:attribute:: Class.udocattr', ' .. py:attribute:: Class.mdocattr', @@ -1062,13 +864,11 @@ def test_autodoc_member_order(app): ' .. py:method:: Class.undocmeth()', ' .. py:attribute:: Class._private_inst_attr', ' .. py:attribute:: Class.attr', - ' .. py:attribute:: Class.descr', ' .. py:attribute:: Class.docattr', ' .. py:attribute:: Class.inst_attr_comment', ' .. py:attribute:: Class.inst_attr_inline', ' .. py:attribute:: Class.inst_attr_string', ' .. py:attribute:: Class.mdocattr', - ' .. py:method:: Class.prop', ' .. py:attribute:: Class.skipattr', ' .. py:attribute:: Class.udocattr' ] @@ -1082,7 +882,6 @@ def test_autodoc_member_order(app): '.. py:class:: Class(arg)', ' .. py:attribute:: Class._private_inst_attr', ' .. py:attribute:: Class.attr', - ' .. py:attribute:: Class.descr', ' .. py:attribute:: Class.docattr', ' .. py:method:: Class.excludemeth()', ' .. py:attribute:: Class.inst_attr_comment', @@ -1091,7 +890,6 @@ def test_autodoc_member_order(app): ' .. py:attribute:: Class.mdocattr', ' .. py:method:: Class.meth()', ' .. py:method:: Class.moore(a, e, f) -> happiness', - ' .. py:method:: Class.prop', ' .. py:method:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)', ' .. py:attribute:: Class.skipattr', ' .. py:method:: Class.skipmeth()', @@ -1132,95 +930,6 @@ def test_autodoc_class_scope(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_docstring_signature(app): - options = {"members": None} - actual = do_autodoc(app, 'class', 'target.DocstringSig', options) - assert list(actual) == [ - '', - '.. py:class:: DocstringSig', - ' :module: target', - '', - ' ', - ' .. py:method:: DocstringSig.meth(FOO, BAR=1) -> BAZ', - ' :module: target', - ' ', - ' First line of docstring', - ' ', - ' rest of docstring', - ' ', - ' ', - ' .. py:method:: DocstringSig.meth2()', - ' :module: target', - ' ', - ' First line, no signature', - ' Second line followed by indentation::', - ' ', - ' indented line', - ' ', - ' ', - ' .. py:method:: DocstringSig.prop1', - ' :module: target', - ' :property:', - ' ', - ' First line of docstring', - ' ', - ' ', - ' .. py:method:: DocstringSig.prop2', - ' :module: target', - ' :property:', - ' ', - ' First line of docstring', - ' Second line of docstring', - ' ' - ] - - # disable autodoc_docstring_signature - app.config.autodoc_docstring_signature = False - actual = do_autodoc(app, 'class', 'target.DocstringSig', options) - assert list(actual) == [ - '', - '.. py:class:: DocstringSig', - ' :module: target', - '', - ' ', - ' .. py:method:: DocstringSig.meth()', - ' :module: target', - ' ', - ' meth(FOO, BAR=1) -> BAZ', - ' First line of docstring', - ' ', - ' rest of docstring', - ' ', - ' ', - ' ', - ' .. py:method:: DocstringSig.meth2()', - ' :module: target', - ' ', - ' First line, no signature', - ' Second line followed by indentation::', - ' ', - ' indented line', - ' ', - ' ', - ' .. py:method:: DocstringSig.prop1', - ' :module: target', - ' :property:', - ' ', - ' DocstringSig.prop1(self)', - ' First line of docstring', - ' ', - ' ', - ' .. py:method:: DocstringSig.prop2', - ' :module: target', - ' :property:', - ' ', - ' First line of docstring', - ' Second line of docstring', - ' ' - ] - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') def test_class_attributes(app): options = {"members": None, "undoc-members": True} @@ -1422,26 +1131,26 @@ def test_enum_class(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_descriptor_class(app): options = {"members": 'CustomDataDescriptor,CustomDataDescriptor2'} - actual = do_autodoc(app, 'module', 'target', options) + actual = do_autodoc(app, 'module', 'target.descriptor', options) assert list(actual) == [ '', - '.. py:module:: target', + '.. py:module:: target.descriptor', '', '', '.. py:class:: CustomDataDescriptor(doc)', - ' :module: target', + ' :module: target.descriptor', '', ' Descriptor class docstring.', ' ', ' ', ' .. py:method:: CustomDataDescriptor.meth()', - ' :module: target', + ' :module: target.descriptor', ' ', ' Function.', ' ', '', '.. py:class:: CustomDataDescriptor2(doc)', - ' :module: target', + ' :module: target.descriptor', '', ' Descriptor class with custom metaclass docstring.', ' ' @@ -1474,57 +1183,6 @@ def test_autofunction_for_method(app): ] -@pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_mocked_module_imports(app, warning): - # no autodoc_mock_imports - options = {"members": 'TestAutodoc,decoratedFunction,func'} - actual = do_autodoc(app, 'module', 'target.need_mocks', options) - assert list(actual) == [] - assert "autodoc: failed to import module 'need_mocks'" in warning.getvalue() - - # with autodoc_mock_imports - app.config.autodoc_mock_imports = [ - 'missing_module', - 'missing_package1', - 'missing_package2', - 'missing_package3', - 'sphinx.missing_module4', - ] - - warning.truncate(0) - actual = do_autodoc(app, 'module', 'target.need_mocks', options) - assert list(actual) == [ - '', - '.. py:module:: target.need_mocks', - '', - '', - '.. py:class:: TestAutodoc', - ' :module: target.need_mocks', - '', - ' TestAutodoc docstring.', - ' ', - ' ', - ' .. py:method:: TestAutodoc.decoratedMethod()', - ' :module: target.need_mocks', - ' ', - ' TestAutodoc::decoratedMethod docstring', - ' ', - '', - '.. py:function:: decoratedFunction()', - ' :module: target.need_mocks', - '', - ' decoratedFunction docstring', - ' ', - '', - '.. py:function:: func(arg: missing_module.Class)', - ' :module: target.need_mocks', - '', - ' a function takes mocked object as an argument', - ' ' - ] - assert warning.getvalue() == '' - - @pytest.mark.usefixtures('setup_test') def test_abstractmethods(): options = {"members": None, @@ -1689,260 +1347,6 @@ def test_partialmethod(app): assert list(actual) == expected -@pytest.mark.usefixtures('setup_test') -def test_module_variables(): - options = {"members": None, - "undoc-members": True} - actual = do_autodoc(app, 'module', 'target.module', options) - assert list(actual) == [ - '', - '.. py:module:: target.module', - '', - '', - '.. py:data:: CONSTANT1', - ' :module: target.module', - " :annotation: = ''", - '', - ' docstring for CONSTANT1', - ' ', - '', - '.. py:data:: CONSTANT2', - ' :module: target.module', - " :annotation: = ''", - '', - ] - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_typehints_signature(app): - app.config.autodoc_typehints = "signature" - - options = {"members": None, - "undoc-members": True} - actual = do_autodoc(app, 'module', 'target.typehints', options) - assert list(actual) == [ - '', - '.. py:module:: target.typehints', - '', - '', - '.. py:class:: Math(s: str, o: object = None)', - ' :module: target.typehints', - '', - ' ', - ' .. py:method:: Math.incr(a: int, b: int = 1) -> int', - ' :module: target.typehints', - ' ', - '', - '.. py:function:: incr(a: int, b: int = 1) -> int', - ' :module: target.typehints', - '' - ] - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_typehints_none(app): - app.config.autodoc_typehints = "none" - - options = {"members": None, - "undoc-members": True} - actual = do_autodoc(app, 'module', 'target.typehints', options) - assert list(actual) == [ - '', - '.. py:module:: target.typehints', - '', - '', - '.. py:class:: Math(s, o = None)', - ' :module: target.typehints', - '', - ' ', - ' .. py:method:: Math.incr(a, b = 1) -> int', - ' :module: target.typehints', - ' ', - '', - '.. py:function:: incr(a, b = 1) -> int', - ' :module: target.typehints', - '' - ] - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -@pytest.mark.filterwarnings('ignore:autodoc_default_flags is now deprecated.') -def test_merge_autodoc_default_flags1(app): - app.config.autodoc_default_flags = ['members', 'undoc-members'] - merge_autodoc_default_flags(app, app.config) - assert app.config.autodoc_default_options == {'members': None, - 'undoc-members': None} - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -@pytest.mark.filterwarnings('ignore:autodoc_default_flags is now deprecated.') -def test_merge_autodoc_default_flags2(app): - app.config.autodoc_default_flags = ['members', 'undoc-members'] - app.config.autodoc_default_options = {'members': 'this,that,order', - 'inherited-members': 'this'} - merge_autodoc_default_flags(app, app.config) - assert app.config.autodoc_default_options == {'members': None, - 'undoc-members': None, - 'inherited-members': 'this'} - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_options(app): - # no settings - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' not in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - actual = do_autodoc(app, 'class', 'target.CustomIter') - assert ' .. py:method:: target.CustomIter' not in actual - actual = do_autodoc(app, 'module', 'target') - assert '.. py:function:: save_traceback(app: Sphinx) -> str' not in actual - - # with :members: - app.config.autodoc_default_options = {'members': None} - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - - # with :members: = True - app.config.autodoc_default_options = {'members': True} - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - - # with :members: and :undoc-members: - app.config.autodoc_default_options = { - 'members': None, - 'undoc-members': None, - } - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' in actual - assert ' .. py:attribute:: EnumCls.val4' in actual - - # with :special-members: - # Note that :members: must be *on* for :special-members: to work. - app.config.autodoc_default_options = { - 'members': None, - 'special-members': None - } - actual = do_autodoc(app, 'class', 'target.CustomIter') - assert ' .. py:method:: CustomIter.__init__()' in actual - assert ' Create a new `CustomIter`.' in actual - assert ' .. py:method:: CustomIter.__iter__()' in actual - assert ' Iterate squares of each value.' in actual - if not IS_PYPY: - assert ' .. py:attribute:: CustomIter.__weakref__' in actual - assert ' list of weak references to the object (if defined)' in actual - - # :exclude-members: None - has no effect. Unlike :members:, - # :special-members:, etc. where None == "include all", here None means - # "no/false/off". - app.config.autodoc_default_options = { - 'members': None, - 'exclude-members': None, - } - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - app.config.autodoc_default_options = { - 'members': None, - 'special-members': None, - 'exclude-members': None, - } - actual = do_autodoc(app, 'class', 'target.CustomIter') - assert ' .. py:method:: CustomIter.__init__()' in actual - assert ' Create a new `CustomIter`.' in actual - assert ' .. py:method:: CustomIter.__iter__()' in actual - assert ' Iterate squares of each value.' in actual - if not IS_PYPY: - assert ' .. py:attribute:: CustomIter.__weakref__' in actual - assert ' list of weak references to the object (if defined)' in actual - assert ' .. py:method:: CustomIter.snafucate()' in actual - assert ' Makes this snafucated.' in actual - - # with :imported-members: - app.config.autodoc_default_options = { - 'members': None, - 'imported-members': None, - 'ignore-module-all': None, - } - actual = do_autodoc(app, 'module', 'target') - print('\n'.join(actual)) - assert '.. py:function:: save_traceback(app: Sphinx) -> str' in actual - - -@pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_options_with_values(app): - # with :members: - app.config.autodoc_default_options = {'members': 'val1,val2'} - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' in actual - assert ' .. py:attribute:: EnumCls.val2' in actual - assert ' .. py:attribute:: EnumCls.val3' not in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - - # with :member-order: - app.config.autodoc_default_options = { - 'members': None, - 'member-order': 'bysource', - } - actual = do_autodoc(app, 'class', 'target.Class') - assert list(filter(lambda l: '::' in l, actual)) == [ - '.. py:class:: Class(arg)', - ' .. py:attribute:: Class.descr', - ' .. py:method:: Class.meth()', - ' .. py:method:: Class.skipmeth()', - ' .. py:method:: Class.excludemeth()', - ' .. py:attribute:: Class.attr', - ' .. py:method:: Class.prop', - ' .. py:attribute:: Class.docattr', - ' .. py:attribute:: Class.udocattr', - ' .. py:attribute:: Class.mdocattr', - ' .. py:method:: Class.moore(a, e, f) -> happiness', - ' .. py:attribute:: Class.inst_attr_inline', - ' .. py:attribute:: Class.inst_attr_comment', - ' .. py:attribute:: Class.inst_attr_string', - ] - - # with :special-members: - app.config.autodoc_default_options = { - 'special-members': '__init__,__iter__', - } - actual = do_autodoc(app, 'class', 'target.CustomIter') - assert ' .. py:method:: CustomIter.__init__()' in actual - assert ' Create a new `CustomIter`.' in actual - assert ' .. py:method:: CustomIter.__iter__()' in actual - assert ' Iterate squares of each value.' in actual - if not IS_PYPY: - assert ' .. py:attribute:: CustomIter.__weakref__' not in actual - assert ' list of weak references to the object (if defined)' not in actual - - # with :exclude-members: - app.config.autodoc_default_options = { - 'members': None, - 'exclude-members': 'val1' - } - actual = do_autodoc(app, 'class', 'target.enum.EnumCls') - assert ' .. py:attribute:: EnumCls.val1' not in actual - assert ' .. py:attribute:: EnumCls.val2' in actual - assert ' .. py:attribute:: EnumCls.val3' in actual - assert ' .. py:attribute:: EnumCls.val4' not in actual - app.config.autodoc_default_options = { - 'members': None, - 'special-members': None, - 'exclude-members': '__weakref__,snafucate', - } - actual = do_autodoc(app, 'class', 'target.CustomIter') - assert ' .. py:method:: CustomIter.__init__()' in actual - assert ' Create a new `CustomIter`.' in actual - assert ' .. py:method:: CustomIter.__iter__()' in actual - assert ' Iterate squares of each value.' in actual - if not IS_PYPY: - assert ' .. py:attribute:: CustomIter.__weakref__' not in actual - assert ' list of weak references to the object (if defined)' not in actual - assert ' .. py:method:: CustomIter.snafucate()' not in actual - assert ' Makes this snafucated.' not in actual - - @pytest.mark.sphinx('html', testroot='pycode-egg') def test_autodoc_for_egged_code(app): options = {"members": None, diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 2df1f8412..677ca9de0 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -451,8 +451,10 @@ def test_html_download(app): @pytest.mark.sphinx('html', testroot='roles-download') def test_html_download_role(app, status, warning): app.build() - digest = md5((app.srcdir / 'dummy.dat').encode()).hexdigest() + digest = md5(b'dummy.dat').hexdigest() assert (app.outdir / '_downloads' / digest / 'dummy.dat').exists() + digest_another = md5(b'another/dummy.dat').hexdigest() + assert (app.outdir / '_downloads' / digest_another / 'dummy.dat').exists() content = (app.outdir / 'index.html').text() assert (('<li><p><a class="reference download internal" download="" ' @@ -460,6 +462,11 @@ def test_html_download_role(app, status, warning): '<code class="xref download docutils literal notranslate">' '<span class="pre">dummy.dat</span></code></a></p></li>' % digest) in content) + assert (('<li><p><a class="reference download internal" download="" ' + 'href="_downloads/%s/dummy.dat">' + '<code class="xref download docutils literal notranslate">' + '<span class="pre">another/dummy.dat</span></code></a></p></li>' % + digest_another) in content) assert ('<li><p><code class="xref download docutils literal notranslate">' '<span class="pre">not_found.dat</span></code></p></li>' in content) assert ('<li><p><a class="reference download external" download="" ' diff --git a/tests/test_ext_apidoc.py b/tests/test_ext_apidoc.py index c6cf43c7e..34c6ec824 100644 --- a/tests/test_ext_apidoc.py +++ b/tests/test_ext_apidoc.py @@ -467,7 +467,8 @@ def test_package_file(tempdir): outdir = path(tempdir) (outdir / 'testpkg').makedirs() (outdir / 'testpkg' / '__init__.py').write_text('') - (outdir / 'testpkg' / 'example.py').write_text('') + (outdir / 'testpkg' / 'hello.py').write_text('') + (outdir / 'testpkg' / 'world.py').write_text('') (outdir / 'testpkg' / 'subpkg').makedirs() (outdir / 'testpkg' / 'subpkg' / '__init__.py').write_text('') apidoc_main(['-o', tempdir, tempdir / 'testpkg']) @@ -488,10 +489,18 @@ def test_package_file(tempdir): "Submodules\n" "----------\n" "\n" - "testpkg.example module\n" - "----------------------\n" + "testpkg.hello module\n" + "--------------------\n" "\n" - ".. automodule:: testpkg.example\n" + ".. automodule:: testpkg.hello\n" + " :members:\n" + " :undoc-members:\n" + " :show-inheritance:\n" + "\n" + "testpkg.world module\n" + "--------------------\n" + "\n" + ".. automodule:: testpkg.world\n" " :members:\n" " :undoc-members:\n" " :show-inheritance:\n" diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py new file mode 100644 index 000000000..bbf3debaa --- /dev/null +++ b/tests/test_ext_autodoc_configs.py @@ -0,0 +1,651 @@ +""" + test_ext_autodoc_configs + ~~~~~~~~~~~~~~~~~~~~~~~~ + + Test the autodoc extension. This tests mainly for config variables + + :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import platform + +import pytest + +from sphinx.ext.autodoc import merge_autodoc_default_flags +from test_autodoc import do_autodoc + +IS_PYPY = platform.python_implementation() == 'PyPy' + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_class(app): + app.config.autoclass_content = 'class' + options = {"members": None} + actual = do_autodoc(app, 'module', 'target.autoclass_content', options) + assert list(actual) == [ + '', + '.. py:module:: target.autoclass_content', + '', + '', + '.. py:class:: A', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, no __new__', + ' ', + '', + '.. py:class:: B()', + ' :module: target.autoclass_content', + '', + ' A class having __init__(no docstring), no __new__', + ' ', + '', + '.. py:class:: C()', + ' :module: target.autoclass_content', + '', + ' A class having __init__, no __new__', + ' ', + '', + '.. py:class:: D', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, __new__(no docstring)', + ' ', + '', + '.. py:class:: E', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, __new__', + ' ', + '', + '.. py:class:: F()', + ' :module: target.autoclass_content', + '', + ' A class having both __init__ and __new__', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_init(app): + app.config.autoclass_content = 'init' + options = {"members": None} + actual = do_autodoc(app, 'module', 'target.autoclass_content', options) + assert list(actual) == [ + '', + '.. py:module:: target.autoclass_content', + '', + '', + '.. py:class:: A', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, no __new__', + ' ', + '', + '.. py:class:: B()', + ' :module: target.autoclass_content', + '', + ' A class having __init__(no docstring), no __new__', + ' ', + '', + '.. py:class:: C()', + ' :module: target.autoclass_content', + '', + ' __init__ docstring', + ' ', + '', + '.. py:class:: D', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, __new__(no docstring)', + ' ', + '', + '.. py:class:: E', + ' :module: target.autoclass_content', + '', + ' __new__ docstring', + ' ', + '', + '.. py:class:: F()', + ' :module: target.autoclass_content', + '', + ' __init__ docstring', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_both(app): + app.config.autoclass_content = 'both' + options = {"members": None} + actual = do_autodoc(app, 'module', 'target.autoclass_content', options) + assert list(actual) == [ + '', + '.. py:module:: target.autoclass_content', + '', + '', + '.. py:class:: A', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, no __new__', + ' ', + '', + '.. py:class:: B()', + ' :module: target.autoclass_content', + '', + ' A class having __init__(no docstring), no __new__', + ' ', + '', + '.. py:class:: C()', + ' :module: target.autoclass_content', + '', + ' A class having __init__, no __new__', + ' ', + ' __init__ docstring', + ' ', + '', + '.. py:class:: D', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, __new__(no docstring)', + ' ', + '', + '.. py:class:: E', + ' :module: target.autoclass_content', + '', + ' A class having no __init__, __new__', + ' ', + ' __new__ docstring', + ' ', + '', + '.. py:class:: F()', + ' :module: target.autoclass_content', + '', + ' A class having both __init__ and __new__', + ' ', + ' __init__ docstring', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_inherit_docstrings(app): + assert app.config.autodoc_inherit_docstrings is True # default + actual = do_autodoc(app, 'method', 'target.inheritance.Derived.inheritedmeth') + assert list(actual) == [ + '', + '.. py:method:: Derived.inheritedmeth()', + ' :module: target.inheritance', + '', + ' Inherited function.', + ' ' + ] + + # disable autodoc_inherit_docstrings + app.config.autodoc_inherit_docstrings = False + actual = do_autodoc(app, 'method', 'target.inheritance.Derived.inheritedmeth') + assert list(actual) == [ + '', + '.. py:method:: Derived.inheritedmeth()', + ' :module: target.inheritance', + '' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_docstring_signature(app): + options = {"members": None} + actual = do_autodoc(app, 'class', 'target.DocstringSig', options) + assert list(actual) == [ + '', + '.. py:class:: DocstringSig', + ' :module: target', + '', + ' ', + ' .. py:method:: DocstringSig.meth(FOO, BAR=1) -> BAZ', + ' :module: target', + ' ', + ' First line of docstring', + ' ', + ' rest of docstring', + ' ', + ' ', + ' .. py:method:: DocstringSig.meth2()', + ' :module: target', + ' ', + ' First line, no signature', + ' Second line followed by indentation::', + ' ', + ' indented line', + ' ', + ' ', + ' .. py:method:: DocstringSig.prop1', + ' :module: target', + ' :property:', + ' ', + ' First line of docstring', + ' ', + ' ', + ' .. py:method:: DocstringSig.prop2', + ' :module: target', + ' :property:', + ' ', + ' First line of docstring', + ' Second line of docstring', + ' ' + ] + + # disable autodoc_docstring_signature + app.config.autodoc_docstring_signature = False + actual = do_autodoc(app, 'class', 'target.DocstringSig', options) + assert list(actual) == [ + '', + '.. py:class:: DocstringSig', + ' :module: target', + '', + ' ', + ' .. py:method:: DocstringSig.meth()', + ' :module: target', + ' ', + ' meth(FOO, BAR=1) -> BAZ', + ' First line of docstring', + ' ', + ' rest of docstring', + ' ', + ' ', + ' ', + ' .. py:method:: DocstringSig.meth2()', + ' :module: target', + ' ', + ' First line, no signature', + ' Second line followed by indentation::', + ' ', + ' indented line', + ' ', + ' ', + ' .. py:method:: DocstringSig.prop1', + ' :module: target', + ' :property:', + ' ', + ' DocstringSig.prop1(self)', + ' First line of docstring', + ' ', + ' ', + ' .. py:method:: DocstringSig.prop2', + ' :module: target', + ' :property:', + ' ', + ' First line of docstring', + ' Second line of docstring', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_and_docstring_signature_class(app): + app.config.autoclass_content = 'class' + options = {"members": None, + "undoc-members": None} + actual = do_autodoc(app, 'module', 'target.docstring_signature', options) + assert list(actual) == [ + '', + '.. py:module:: target.docstring_signature', + '', + '', + '.. py:class:: A(foo, bar)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: B(foo, bar)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: C(foo, bar)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: D()', + ' :module: target.docstring_signature', + '' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_and_docstring_signature_init(app): + app.config.autoclass_content = 'init' + options = {"members": None, + "undoc-members": None} + actual = do_autodoc(app, 'module', 'target.docstring_signature', options) + assert list(actual) == [ + '', + '.. py:module:: target.docstring_signature', + '', + '', + '.. py:class:: A(foo, bar)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: B(foo, bar, baz)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: C(foo, bar, baz)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: D(foo, bar, baz)', + ' :module: target.docstring_signature', + '' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoclass_content_and_docstring_signature_both(app): + app.config.autoclass_content = 'both' + options = {"members": None, + "undoc-members": None} + actual = do_autodoc(app, 'module', 'target.docstring_signature', options) + assert list(actual) == [ + '', + '.. py:module:: target.docstring_signature', + '', + '', + '.. py:class:: A(foo, bar)', + ' :module: target.docstring_signature', + '', + '', + '.. py:class:: B(foo, bar)', + ' :module: target.docstring_signature', + '', + ' B(foo, bar, baz)', + ' ', + '', + '.. py:class:: C(foo, bar)', + ' :module: target.docstring_signature', + '', + ' C(foo, bar, baz)', + ' ', + '', + '.. py:class:: D(foo, bar, baz)', + ' :module: target.docstring_signature', + '', + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_mocked_module_imports(app, warning): + # no autodoc_mock_imports + options = {"members": 'TestAutodoc,decoratedFunction,func'} + actual = do_autodoc(app, 'module', 'target.need_mocks', options) + assert list(actual) == [] + assert "autodoc: failed to import module 'need_mocks'" in warning.getvalue() + + # with autodoc_mock_imports + app.config.autodoc_mock_imports = [ + 'missing_module', + 'missing_package1', + 'missing_package2', + 'missing_package3', + 'sphinx.missing_module4', + ] + + warning.truncate(0) + actual = do_autodoc(app, 'module', 'target.need_mocks', options) + assert list(actual) == [ + '', + '.. py:module:: target.need_mocks', + '', + '', + '.. py:class:: TestAutodoc', + ' :module: target.need_mocks', + '', + ' TestAutodoc docstring.', + ' ', + ' ', + ' .. py:method:: TestAutodoc.decoratedMethod()', + ' :module: target.need_mocks', + ' ', + ' TestAutodoc::decoratedMethod docstring', + ' ', + '', + '.. py:function:: decoratedFunction()', + ' :module: target.need_mocks', + '', + ' decoratedFunction docstring', + ' ', + '', + '.. py:function:: func(arg: missing_module.Class)', + ' :module: target.need_mocks', + '', + ' a function takes mocked object as an argument', + ' ' + ] + assert warning.getvalue() == '' + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_typehints_signature(app): + app.config.autodoc_typehints = "signature" + + options = {"members": None, + "undoc-members": True} + actual = do_autodoc(app, 'module', 'target.typehints', options) + assert list(actual) == [ + '', + '.. py:module:: target.typehints', + '', + '', + '.. py:class:: Math(s: str, o: object = None)', + ' :module: target.typehints', + '', + ' ', + ' .. py:method:: Math.incr(a: int, b: int = 1) -> int', + ' :module: target.typehints', + ' ', + '', + '.. py:function:: incr(a: int, b: int = 1) -> int', + ' :module: target.typehints', + '' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_typehints_none(app): + app.config.autodoc_typehints = "none" + + options = {"members": None, + "undoc-members": True} + actual = do_autodoc(app, 'module', 'target.typehints', options) + assert list(actual) == [ + '', + '.. py:module:: target.typehints', + '', + '', + '.. py:class:: Math(s, o = None)', + ' :module: target.typehints', + '', + ' ', + ' .. py:method:: Math.incr(a, b = 1) -> int', + ' :module: target.typehints', + ' ', + '', + '.. py:function:: incr(a, b = 1) -> int', + ' :module: target.typehints', + '' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +@pytest.mark.filterwarnings('ignore:autodoc_default_flags is now deprecated.') +def test_merge_autodoc_default_flags1(app): + app.config.autodoc_default_flags = ['members', 'undoc-members'] + merge_autodoc_default_flags(app, app.config) + assert app.config.autodoc_default_options == {'members': None, + 'undoc-members': None} + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +@pytest.mark.filterwarnings('ignore:autodoc_default_flags is now deprecated.') +def test_merge_autodoc_default_flags2(app): + app.config.autodoc_default_flags = ['members', 'undoc-members'] + app.config.autodoc_default_options = {'members': 'this,that,order', + 'inherited-members': 'this'} + merge_autodoc_default_flags(app, app.config) + assert app.config.autodoc_default_options == {'members': None, + 'undoc-members': None, + 'inherited-members': 'this'} + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_default_options(app): + # no settings + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' not in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: target.CustomIter' not in actual + actual = do_autodoc(app, 'module', 'target') + assert '.. py:function:: save_traceback(app: Sphinx) -> str' not in actual + + # with :members: + app.config.autodoc_default_options = {'members': None} + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + + # with :members: = True + app.config.autodoc_default_options = {'members': True} + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + + # with :members: and :undoc-members: + app.config.autodoc_default_options = { + 'members': None, + 'undoc-members': None, + } + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val4' in actual + + # with :special-members: + # Note that :members: must be *on* for :special-members: to work. + app.config.autodoc_default_options = { + 'members': None, + 'special-members': None + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' in actual + assert ' list of weak references to the object (if defined)' in actual + + # :exclude-members: None - has no effect. Unlike :members:, + # :special-members:, etc. where None == "include all", here None means + # "no/false/off". + app.config.autodoc_default_options = { + 'members': None, + 'exclude-members': None, + } + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + app.config.autodoc_default_options = { + 'members': None, + 'special-members': None, + 'exclude-members': None, + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' in actual + assert ' list of weak references to the object (if defined)' in actual + assert ' .. py:method:: CustomIter.snafucate()' in actual + assert ' Makes this snafucated.' in actual + + # with :imported-members: + app.config.autodoc_default_options = { + 'members': None, + 'imported-members': None, + 'ignore-module-all': None, + } + actual = do_autodoc(app, 'module', 'target') + print('\n'.join(actual)) + assert '.. py:function:: save_traceback(app: Sphinx) -> str' in actual + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodoc_default_options_with_values(app): + # with :members: + app.config.autodoc_default_options = {'members': 'val1,val2'} + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val2' in actual + assert ' .. py:attribute:: EnumCls.val3' not in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + + # with :member-order: + app.config.autodoc_default_options = { + 'members': None, + 'member-order': 'bysource', + } + actual = do_autodoc(app, 'class', 'target.Class') + assert list(filter(lambda l: '::' in l, actual)) == [ + '.. py:class:: Class(arg)', + ' .. py:method:: Class.meth()', + ' .. py:method:: Class.skipmeth()', + ' .. py:method:: Class.excludemeth()', + ' .. py:attribute:: Class.attr', + ' .. py:attribute:: Class.docattr', + ' .. py:attribute:: Class.udocattr', + ' .. py:attribute:: Class.mdocattr', + ' .. py:method:: Class.moore(a, e, f) -> happiness', + ' .. py:attribute:: Class.inst_attr_inline', + ' .. py:attribute:: Class.inst_attr_comment', + ' .. py:attribute:: Class.inst_attr_string', + ] + + # with :special-members: + app.config.autodoc_default_options = { + 'special-members': '__init__,__iter__', + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' not in actual + assert ' list of weak references to the object (if defined)' not in actual + + # with :exclude-members: + app.config.autodoc_default_options = { + 'members': None, + 'exclude-members': 'val1' + } + actual = do_autodoc(app, 'class', 'target.enum.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' not in actual + assert ' .. py:attribute:: EnumCls.val2' in actual + assert ' .. py:attribute:: EnumCls.val3' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + app.config.autodoc_default_options = { + 'members': None, + 'special-members': None, + 'exclude-members': '__weakref__,snafucate', + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' not in actual + assert ' list of weak references to the object (if defined)' not in actual + assert ' .. py:method:: CustomIter.snafucate()' not in actual + assert ' Makes this snafucated.' not in actual diff --git a/tests/test_ext_autodoc_events.py b/tests/test_ext_autodoc_events.py new file mode 100644 index 000000000..647def3d7 --- /dev/null +++ b/tests/test_ext_autodoc_events.py @@ -0,0 +1,81 @@ +""" + test_ext_autodoc_events + ~~~~~~~~~~~~~~~~~~~~~~~ + + Test the autodoc extension. This tests mainly for autodoc events + + :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import pytest + +from sphinx.ext.autodoc import between, cut_lines +from test_autodoc import do_autodoc + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_process_docstring(app): + def on_process_docstring(app, what, name, obj, options, lines): + lines.clear() + lines.append('my docstring') + + app.connect('autodoc-process-docstring', on_process_docstring) + + actual = do_autodoc(app, 'function', 'target.process_docstring.func') + assert list(actual) == [ + '', + '.. py:function:: func()', + ' :module: target.process_docstring', + '', + ' my docstring' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_cut_lines(app): + app.connect('autodoc-process-docstring', + cut_lines(2, 2, ['function'])) + + actual = do_autodoc(app, 'function', 'target.process_docstring.func') + assert list(actual) == [ + '', + '.. py:function:: func()', + ' :module: target.process_docstring', + '', + ' second line', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_between(app): + app.connect('autodoc-process-docstring', + between('---', ['function'])) + + actual = do_autodoc(app, 'function', 'target.process_docstring.func') + assert list(actual) == [ + '', + '.. py:function:: func()', + ' :module: target.process_docstring', + '', + ' second line', + ' ' + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_between_exclude(app): + app.connect('autodoc-process-docstring', + between('---', ['function'], exclude=True)) + + actual = do_autodoc(app, 'function', 'target.process_docstring.func') + assert list(actual) == [ + '', + '.. py:function:: func()', + ' :module: target.process_docstring', + '', + ' first line', + ' third line', + ' ' + ] diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 04af9ed85..ae97d3b57 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -10,7 +10,7 @@ import sys from io import StringIO -from unittest.mock import Mock +from unittest.mock import Mock, patch import pytest from docutils import nodes @@ -19,6 +19,7 @@ from sphinx import addnodes from sphinx.ext.autosummary import ( autosummary_table, autosummary_toc, mangle_signature, import_by_name, extract_summary ) +from sphinx.ext.autosummary.generate import generate_autosummary_docs from sphinx.testing.util import assert_node, etree_parse from sphinx.util.docutils import new_document @@ -286,3 +287,18 @@ def test_autosummary_imported_members(app, status, warning): ' \n' in module) finally: sys.modules.pop('autosummary_dummy_package', None) + + +@pytest.mark.sphinx(testroot='ext-autodoc') +def test_generate_autosummary_docs_property(app): + with patch('sphinx.ext.autosummary.generate.find_autosummary_in_files') as mock: + mock.return_value = [('target.methods.Base.prop', 'prop', None)] + generate_autosummary_docs([], output_dir=app.srcdir, builder=app.builder, app=app) + + content = (app.srcdir / 'target.methods.Base.prop.rst').text() + assert content == ("target.methods.Base.prop\n" + "========================\n" + "\n" + ".. currentmodule:: target.methods\n" + "\n" + ".. autoproperty:: Base.prop") diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index a333dc47b..f1714bd62 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -1351,8 +1351,8 @@ arg_ : type """ expected = """ -:ivar arg_: some description -:vartype arg_: type +:ivar arg\\_: some description +:vartype arg\\_: type """ config = Config(napoleon_use_ivar=True) diff --git a/tests/test_pycode_parser.py b/tests/test_pycode_parser.py index ba9778b80..8f8c6cbab 100644 --- a/tests/test_pycode_parser.py +++ b/tests/test_pycode_parser.py @@ -149,6 +149,21 @@ def test_complex_assignment_py3(): assert parser.definitions == {} +def test_assignment_in_try_clause(): + source = ('try:\n' + ' a = None #: comment\n' + 'except:\n' + ' b = None #: ignored\n' + 'else:\n' + ' c = None #: comment\n') + parser = Parser(source) + parser.parse() + assert parser.comments == {('', 'a'): 'comment', + ('', 'c'): 'comment'} + assert parser.deforders == {'a': 0, + 'c': 1} + + def test_obj_assignment(): source = ('obj = SomeObject() #: some object\n' 'obj.attr = 1 #: attr1\n' |