summaryrefslogtreecommitdiff
path: root/sphinx/util/docutils.py
diff options
context:
space:
mode:
Diffstat (limited to 'sphinx/util/docutils.py')
-rw-r--r--sphinx/util/docutils.py61
1 files changed, 31 insertions, 30 deletions
diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py
index ce50c7ab1..44483bdd8 100644
--- a/sphinx/util/docutils.py
+++ b/sphinx/util/docutils.py
@@ -15,7 +15,8 @@ from copy import copy
from distutils.version import LooseVersion
from os import path
from types import ModuleType
-from typing import IO, Any, Callable, Dict, Generator, List, Optional, Set, Tuple, cast
+from typing import (IO, TYPE_CHECKING, Any, Callable, Dict, Generator, List, Optional, Set,
+ Tuple, Type, cast)
import docutils
from docutils import nodes
@@ -27,23 +28,21 @@ from docutils.statemachine import State, StateMachine, StringList
from docutils.utils import Reporter, unescape
from sphinx.errors import 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 typing import Type # for python3.5.1
-
+if TYPE_CHECKING:
from sphinx.builders import Builder
from sphinx.config import Config
from sphinx.environment import BuildEnvironment
__version_info__ = tuple(LooseVersion(docutils.__version__).version)
-additional_nodes = set() # type: Set[Type[nodes.Element]]
+additional_nodes: Set[Type[Element]] = set()
@contextmanager
@@ -68,7 +67,7 @@ def is_directive_registered(name: str) -> bool:
return name in directives._directives # type: ignore
-def register_directive(name: str, directive: "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
@@ -96,12 +95,12 @@ def unregister_role(name: str) -> None:
roles._roles.pop(name, None) # type: ignore
-def is_node_registered(node: "Type[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[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
@@ -112,7 +111,7 @@ def register_node(node: "Type[Element]") -> None:
additional_nodes.add(node)
-def unregister_node(node: "Type[Element]") -> None:
+def unregister_node(node: Type[Element]) -> None:
"""Unregister a node from docutils.
This is inverse of ``nodes._add_nodes_class_names()``.
@@ -145,7 +144,7 @@ def patched_get_language() -> Generator[None, None, None]:
@contextmanager
-def using_user_docutils_conf(confdir: str) -> Generator[None, None, None]:
+def using_user_docutils_conf(confdir: Optional[str]) -> Generator[None, None, None]:
"""Let docutils know the location of ``docutils.conf`` for Sphinx."""
try:
docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
@@ -161,7 +160,7 @@ def using_user_docutils_conf(confdir: str) -> Generator[None, None, None]:
@contextmanager
-def patch_docutils(confdir: str = None) -> Generator[None, None, None]:
+def patch_docutils(confdir: Optional[str] = None) -> Generator[None, None, None]:
"""Patch to docutils temporarily."""
with patched_get_language(), using_user_docutils_conf(confdir):
yield
@@ -177,13 +176,13 @@ class sphinx_domains:
"""
def __init__(self, env: "BuildEnvironment") -> None:
self.env = env
- self.directive_func = None # type: Callable
- self.roles_func = None # type: Callable
+ self.directive_func: Callable = None
+ self.roles_func: Callable = None
def __enter__(self) -> None:
self.enable()
- def __exit__(self, exc_type: "Type[Exception]", exc_value: Exception, traceback: Any) -> None: # NOQA
+ def __exit__(self, exc_type: Type[Exception], exc_value: Exception, traceback: Any) -> None: # NOQA
self.disable()
def enable(self) -> None:
@@ -210,6 +209,8 @@ class sphinx_domains:
element = getattr(domain, type)(name)
if element is not None:
return element, []
+ else:
+ logger.warning(_('unknown directive or role name: %s:%s'), domain_name, name)
# else look in the default domain
else:
def_domain = self.env.temp_data.get('default_domain')
@@ -225,7 +226,7 @@ class sphinx_domains:
raise ElementLookupError
- def lookup_directive(self, directive_name: str, language_module: ModuleType, document: nodes.document) -> Tuple[Optional["Type[Directive]"], List[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', directive_name)
except ElementLookupError:
@@ -347,15 +348,15 @@ class SphinxRole:
.. note:: The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
"""
- name = None #: The role name actually used in the document.
- rawtext = None #: A string containing the entire interpreted text input.
- text = None #: The interpreted text content.
- lineno = None #: The line number where the interpreted text begins.
- inliner = None #: The ``docutils.parsers.rst.states.Inliner`` object.
- options = None #: A dictionary of directive options for customization
- #: (from the "role" directive).
- content = None #: A list of strings, the directive content for customization
- #: (from the "role" directive).
+ name: str #: The role name actually used in the document.
+ rawtext: str #: A string containing the entire interpreted text input.
+ text: str #: The interpreted text content.
+ lineno: int #: The line number where the interpreted text begins.
+ inliner: Inliner #: The ``docutils.parsers.rst.states.Inliner`` object.
+ options: Dict #: A dictionary of directive options for customization
+ #: (from the "role" directive).
+ content: List[str] #: A list of strings, the directive content for customization
+ #: (from the "role" directive).
def __call__(self, name: str, rawtext: str, text: str, lineno: int,
inliner: Inliner, options: Dict = {}, content: List[str] = []
@@ -408,10 +409,10 @@ class ReferenceRole(SphinxRole):
the role. The parsed result; link title and target will be stored to
``self.title`` and ``self.target``.
"""
- has_explicit_title = None #: A boolean indicates the role has explicit title or not.
- disabled = False #: A boolean indicates the reference is disabled.
- title = None #: The link title for the interpreted text.
- target = None #: The link target for the interpreted text.
+ has_explicit_title: bool #: A boolean indicates the role has explicit title or not.
+ disabled: bool #: A boolean indicates the reference is disabled.
+ title: str #: The link title for the interpreted text.
+ target: str #: The link target for the interpreted text.
# \x00 means the "<" was backslash-escaped
explicit_title_re = re.compile(r'^(.+?)\s*(?<!\x00)<(.*?)>$', re.DOTALL)
@@ -490,7 +491,7 @@ class SphinxTranslator(nodes.NodeVisitor):
# cache a vanilla instance of nodes.document
# Used in new_document() function
-__document_cache__ = None # type: nodes.document
+__document_cache__: nodes.document = None
def new_document(source_path: str, settings: Any = None) -> nodes.document:
View Lorry Controller Status