py2docfx 0.1.11.dev1830301__py3-none-any.whl → 0.1.11.dev1860114__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/roles.py

@@ -1,428 +0,0 @@
-"""Handlers for additional ReST roles."""
-
-from __future__ import annotations
-
-import re
-from typing import TYPE_CHECKING, Any
-
-import docutils.parsers.rst.directives
-import docutils.parsers.rst.roles
-import docutils.parsers.rst.states
-from docutils import nodes, utils
-from docutils.nodes import Element, Node, TextElement, system_message
-
-from sphinx import addnodes
-from sphinx.locale import _, __
-from sphinx.util import ws_re
-from sphinx.util.docutils import ReferenceRole, SphinxRole
-from sphinx.util.typing import RoleFunction
-
-if TYPE_CHECKING:
-    from sphinx.application import Sphinx
-    from sphinx.environment import BuildEnvironment
-
-
-generic_docroles = {
-    'command': addnodes.literal_strong,
-    'dfn': nodes.emphasis,
-    'kbd': nodes.literal,
-    'mailheader': addnodes.literal_emphasis,
-    'makevar': addnodes.literal_strong,
-    'manpage': addnodes.manpage,
-    'mimetype': addnodes.literal_emphasis,
-    'newsgroup': addnodes.literal_emphasis,
-    'program': addnodes.literal_strong,  # XXX should be an x-ref
-    'regexp': nodes.literal,
-}
-
-
-# -- generic cross-reference role ----------------------------------------------
-
-class XRefRole(ReferenceRole):
-    """
-    A generic cross-referencing role.  To create a callable that can be used as
-    a role function, create an instance of this class.
-
-    The general features of this role are:
-
-    * Automatic creation of a reference and a content node.
-    * Optional separation of title and target with `title <target>`.
-    * The implementation is a class rather than a function to make
-      customization easier.
-
-    Customization can be done in two ways:
-
-    * Supplying constructor parameters:
-      * `fix_parens` to normalize parentheses (strip from target, and add to
-        title if configured)
-      * `lowercase` to lowercase the target
-      * `nodeclass` and `innernodeclass` select the node classes for
-        the reference and the content node
-
-    * Subclassing and overwriting `process_link()` and/or `result_nodes()`.
-    """
-
-    nodeclass: type[Element] = addnodes.pending_xref
-    innernodeclass: type[TextElement] = nodes.literal
-
-    def __init__(self, fix_parens: bool = False, lowercase: bool = False,
-                 nodeclass: type[Element] | None = None,
-                 innernodeclass: type[TextElement] | None = None,
-                 warn_dangling: bool = False) -> None:
-        self.fix_parens = fix_parens
-        self.lowercase = lowercase
-        self.warn_dangling = warn_dangling
-        if nodeclass is not None:
-            self.nodeclass = nodeclass
-        if innernodeclass is not None:
-            self.innernodeclass = innernodeclass
-
-        super().__init__()
-
-    def update_title_and_target(self, title: str, target: str) -> tuple[str, str]:
-        if not self.has_explicit_title:
-            if title.endswith('()'):
-                # remove parentheses
-                title = title[:-2]
-            if self.config.add_function_parentheses:
-                # add them back to all occurrences if configured
-                title += '()'
-        # remove parentheses from the target too
-        if target.endswith('()'):
-            target = target[:-2]
-        return title, target
-
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        if ':' not in self.name:
-            self.refdomain, self.reftype = '', self.name
-            self.classes = ['xref', self.reftype]
-        else:
-            self.refdomain, self.reftype = self.name.split(':', 1)
-            self.classes = ['xref', self.refdomain, f'{self.refdomain}-{self.reftype}']
-
-        if self.disabled:
-            return self.create_non_xref_node()
-        else:
-            return self.create_xref_node()
-
-    def create_non_xref_node(self) -> tuple[list[Node], list[system_message]]:
-        text = utils.unescape(self.text[1:])
-        if self.fix_parens:
-            self.has_explicit_title = False  # treat as implicit
-            text, target = self.update_title_and_target(text, "")
-
-        node = self.innernodeclass(self.rawtext, text, classes=self.classes)
-        return self.result_nodes(self.inliner.document, self.env, node, is_ref=False)
-
-    def create_xref_node(self) -> tuple[list[Node], list[system_message]]:
-        target = self.target
-        title = self.title
-        if self.lowercase:
-            target = target.lower()
-        if self.fix_parens:
-            title, target = self.update_title_and_target(title, target)
-
-        # create the reference node
-        options = {'refdoc': self.env.docname,
-                   'refdomain': self.refdomain,
-                   'reftype': self.reftype,
-                   'refexplicit': self.has_explicit_title,
-                   'refwarn': self.warn_dangling}
-        refnode = self.nodeclass(self.rawtext, **options)
-        self.set_source_info(refnode)
-
-        # determine the target and title for the class
-        title, target = self.process_link(self.env, refnode, self.has_explicit_title,
-                                          title, target)
-        refnode['reftarget'] = target
-        refnode += self.innernodeclass(self.rawtext, title, classes=self.classes)
-
-        return self.result_nodes(self.inliner.document, self.env, refnode, is_ref=True)
-
-    # methods that can be overwritten
-
-    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool,
-                     title: str, target: str) -> tuple[str, str]:
-        """Called after parsing title and target text, and creating the
-        reference node (given in *refnode*).  This method can alter the
-        reference node and must return a new (or the same) ``(title, target)``
-        tuple.
-        """
-        return title, ws_re.sub(' ', target)
-
-    def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: Element,
-                     is_ref: bool) -> tuple[list[Node], list[system_message]]:
-        """Called before returning the finished nodes.  *node* is the reference
-        node if one was created (*is_ref* is then true), else the content node.
-        This method can add other nodes and must return a ``(nodes, messages)``
-        tuple (the usual return value of a role function).
-        """
-        return [node], []
-
-
-class AnyXRefRole(XRefRole):
-    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool,
-                     title: str, target: str) -> tuple[str, str]:
-        result = super().process_link(env, refnode, has_explicit_title, title, target)
-        # add all possible context info (i.e. std:program, py:module etc.)
-        refnode.attributes.update(env.ref_context)
-        return result
-
-
-class PEP(ReferenceRole):
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = 'index-%s' % self.env.new_serialno('index')
-        entries = [('single', _('Python Enhancement Proposals; PEP %s') % self.target,
-                    target_id, '', None)]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
-
-        try:
-            refuri = self.build_uri()
-            reference = nodes.reference('', '', internal=False, refuri=refuri, classes=['pep'])
-            if self.has_explicit_title:
-                reference += nodes.strong(self.title, self.title)
-            else:
-                title = "PEP " + self.title
-                reference += nodes.strong(title, title)
-        except ValueError:
-            msg = self.inliner.reporter.error(__('invalid PEP number %s') % self.target,
-                                              line=self.lineno)
-            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
-            return [prb], [msg]
-
-        return [index, target, reference], []
-
-    def build_uri(self) -> str:
-        base_url = self.inliner.document.settings.pep_base_url
-        ret = self.target.split('#', 1)
-        if len(ret) == 2:
-            return base_url + 'pep-%04d/#%s' % (int(ret[0]), ret[1])
-        else:
-            return base_url + 'pep-%04d/' % int(ret[0])
-
-
-class RFC(ReferenceRole):
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        target_id = 'index-%s' % self.env.new_serialno('index')
-        entries = [('single', 'RFC; RFC %s' % self.target, target_id, '', None)]
-
-        index = addnodes.index(entries=entries)
-        target = nodes.target('', '', ids=[target_id])
-        self.inliner.document.note_explicit_target(target)
-
-        try:
-            refuri = self.build_uri()
-            reference = nodes.reference('', '', internal=False, refuri=refuri, classes=['rfc'])
-            if self.has_explicit_title:
-                reference += nodes.strong(self.title, self.title)
-            else:
-                title = "RFC " + self.title
-                reference += nodes.strong(title, title)
-        except ValueError:
-            msg = self.inliner.reporter.error(__('invalid RFC number %s') % self.target,
-                                              line=self.lineno)
-            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
-            return [prb], [msg]
-
-        return [index, target, reference], []
-
-    def build_uri(self) -> str:
-        base_url = self.inliner.document.settings.rfc_base_url
-        ret = self.target.split('#', 1)
-        if len(ret) == 2:
-            return base_url + self.inliner.rfc_url % int(ret[0]) + '#' + ret[1]
-        else:
-            return base_url + self.inliner.rfc_url % int(ret[0])
-
-
-_amp_re = re.compile(r'(?<!&)&(?![&\s])')
-
-
-class GUILabel(SphinxRole):
-    amp_re = re.compile(r'(?<!&)&(?![&\s])')
-
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        node = nodes.inline(rawtext=self.rawtext, classes=[self.name])
-        spans = self.amp_re.split(self.text)
-        node += nodes.Text(spans.pop(0))
-        for span in spans:
-            span = span.replace('&&', '&')
-
-            letter = nodes.Text(span[0])
-            accelerator = nodes.inline('', '', letter, classes=['accelerator'])
-            node += accelerator
-            node += nodes.Text(span[1:])
-
-        return [node], []
-
-
-class MenuSelection(GUILabel):
-    BULLET_CHARACTER = '\N{TRIANGULAR BULLET}'
-
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        self.text = self.text.replace('-->', self.BULLET_CHARACTER)
-        return super().run()
-
-
-_litvar_re = re.compile('{([^}]+)}')
-parens_re = re.compile(r'(\\*{|\\*})')
-
-
-class EmphasizedLiteral(SphinxRole):
-    parens_re = re.compile(r'(\\\\|\\{|\\}|{|})')
-
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        children = self.parse(self.text)
-        node = nodes.literal(self.rawtext, '', *children,
-                             role=self.name.lower(), classes=[self.name])
-
-        return [node], []
-
-    def parse(self, text: str) -> list[Node]:
-        result: list[Node] = []
-
-        stack = ['']
-        for part in self.parens_re.split(text):
-            if part == '\\\\':  # escaped backslash
-                stack[-1] += '\\'
-            elif part == '{':
-                if len(stack) >= 2 and stack[-2] == "{":  # nested
-                    stack[-1] += "{"
-                else:
-                    # start emphasis
-                    stack.append('{')
-                    stack.append('')
-            elif part == '}':
-                if len(stack) == 3 and stack[1] == "{" and len(stack[2]) > 0:
-                    # emphasized word found
-                    if stack[0]:
-                        result.append(nodes.Text(stack[0]))
-                    result.append(nodes.emphasis(stack[2], stack[2]))
-                    stack = ['']
-                else:
-                    # emphasized word not found; the rparen is not a special symbol
-                    stack.append('}')
-                    stack = [''.join(stack)]
-            elif part == '\\{':  # escaped left-brace
-                stack[-1] += '{'
-            elif part == '\\}':  # escaped right-brace
-                stack[-1] += '}'
-            else:  # others (containing escaped braces)
-                stack[-1] += part
-
-        if ''.join(stack):
-            # remaining is treated as Text
-            text = ''.join(stack)
-            result.append(nodes.Text(text))
-
-        return result
-
-
-_abbr_re = re.compile(r'\((.*)\)$', re.S)
-
-
-class Abbreviation(SphinxRole):
-    abbr_re = re.compile(r'\((.*)\)$', re.S)
-
-    def run(self) -> tuple[list[Node], list[system_message]]:
-        options = self.options.copy()
-        matched = self.abbr_re.search(self.text)
-        if matched:
-            text = self.text[:matched.start()].strip()
-            options['explanation'] = matched.group(1)
-        else:
-            text = self.text
-
-        return [nodes.abbreviation(self.rawtext, text, **options)], []
-
-
-# Sphinx provides the `code-block` directive for highlighting code blocks.
-# Docutils provides the `code` role which in theory can be used similarly by
-# defining a custom role for a given programming language:
-#
-#     .. .. role:: python(code)
-#          :language: python
-#          :class: highlight
-#
-# In practice this does not produce correct highlighting because it uses a
-# separate highlighting mechanism that results in the "long" pygments class
-# names rather than "short" pygments class names produced by the Sphinx
-# `code-block` directive and for which this extension contains CSS rules.
-#
-# In addition, even if that issue is fixed, because the highlighting
-# implementation in docutils, despite being based on pygments, differs from that
-# used by Sphinx, the output does not exactly match that produced by the Sphinx
-# `code-block` directive.
-#
-# This issue is noted here: //github.com/sphinx-doc/sphinx/issues/5157
-#
-# This overrides the docutils `code` role to perform highlighting in the same
-# way as the Sphinx `code-block` directive.
-#
-# TODO: Change to use `SphinxRole` once SphinxRole is fixed to support options.
-def code_role(name: str, rawtext: str, text: str, lineno: int,
-              inliner: docutils.parsers.rst.states.Inliner,
-              options: dict = {}, content: list[str] = []
-              ) -> tuple[list[Node], list[system_message]]:
-    options = options.copy()
-    docutils.parsers.rst.roles.set_classes(options)
-    language = options.get('language', '')
-    classes = ['code']
-    if language:
-        classes.append('highlight')
-    if 'classes' in options:
-        classes.extend(options['classes'])
-
-    if language and language not in classes:
-        classes.append(language)
-
-    node = nodes.literal(rawtext, text, classes=classes, language=language)
-
-    return [node], []
-
-
-code_role.options = {  # type: ignore
-    'class': docutils.parsers.rst.directives.class_option,
-    'language': docutils.parsers.rst.directives.unchanged,
-}
-
-
-specific_docroles: dict[str, RoleFunction] = {
-    # links to download references
-    'download': XRefRole(nodeclass=addnodes.download_reference),
-    # links to anything
-    'any': AnyXRefRole(warn_dangling=True),
-
-    'pep': PEP(),
-    'rfc': RFC(),
-    'guilabel': GUILabel(),
-    'menuselection': MenuSelection(),
-    'file': EmphasizedLiteral(),
-    'samp': EmphasizedLiteral(),
-    'abbr': Abbreviation(),
-}
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    from docutils.parsers.rst import roles
-
-    for rolename, nodeclass in generic_docroles.items():
-        generic = roles.GenericRole(rolename, nodeclass)
-        role = roles.CustomRole(rolename, generic, {'classes': [rolename]})
-        roles.register_local_role(rolename, role)
-
-    for rolename, func in specific_docroles.items():
-        roles.register_local_role(rolename, func)
-
-    # Since docutils registers it as a canonical role, override it as a
-    # canonical role as well.
-    roles.register_canonical_role('code', code_role)
-
-    return {
-        'version': 'builtin',
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
-    }