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

py2docfx/venv/template/Lib/site-packages/sphinx/ext/extlinks.py

@@ -1,120 +0,0 @@
-"""Extension to save typing and prevent hard-coding of base URLs in reST files.
-
-This adds a new config value called ``extlinks`` that is created like this::
-
-   extlinks = {'exmpl': ('https://example.invalid/%s.html', caption), ...}
-
-Now you can use e.g. :exmpl:`foo` in your documents.  This will create a
-link to ``https://example.invalid/foo.html``.  The link caption depends on
-the *caption* value given:
-
-- If it is ``None``, the caption will be the full URL.
-- If it is a string, it must contain ``%s`` exactly once.  In this case the
-  caption will be *caption* with the role content substituted for ``%s``.
-
-You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
-
-Both, the url string and the caption string must escape ``%`` as ``%%``.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Any
-
-from docutils import nodes, utils
-from docutils.nodes import Node, system_message
-from docutils.parsers.rst.states import Inliner
-
-import sphinx
-from sphinx.application import Sphinx
-from sphinx.locale import __
-from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import logging, rst
-from sphinx.util.nodes import split_explicit_title
-from sphinx.util.typing import RoleFunction
-
-logger = logging.getLogger(__name__)
-
-
-class ExternalLinksChecker(SphinxPostTransform):
-    """
-    For each external link, check if it can be replaced by an extlink.
-
-    We treat each ``reference`` node without ``internal`` attribute as an external link.
-    """
-
-    default_priority = 500
-
-    def run(self, **kwargs: Any) -> None:
-        if not self.config.extlinks_detect_hardcoded_links:
-            return
-
-        for refnode in self.document.findall(nodes.reference):
-            self.check_uri(refnode)
-
-    def check_uri(self, refnode: nodes.reference) -> None:
-        """
-        If the URI in ``refnode`` has a replacement in ``extlinks``,
-        emit a warning with a replacement suggestion.
-        """
-        if 'internal' in refnode or 'refuri' not in refnode:
-            return
-
-        uri = refnode['refuri']
-        title = refnode.astext()
-
-        for alias, (base_uri, _caption) in self.app.config.extlinks.items():
-            uri_pattern = re.compile(re.escape(base_uri).replace('%s', '(?P<value>.+)'))
-
-            match = uri_pattern.match(uri)
-            if (
-                match and
-                match.groupdict().get('value') and
-                '/' not in match.groupdict()['value']
-            ):
-                # build a replacement suggestion
-                msg = __('hardcoded link %r could be replaced by an extlink '
-                         '(try using %r instead)')
-                value = match.groupdict().get('value')
-                if uri != title:
-                    replacement = f":{alias}:`{rst.escape(title)} <{value}>`"
-                else:
-                    replacement = f":{alias}:`{value}`"
-                logger.warning(msg, uri, replacement, location=refnode)
-
-
-def make_link_role(name: str, base_url: str, caption: str) -> RoleFunction:
-    # Check whether we have base_url and caption strings have an '%s' for
-    # expansion.  If not, fall back the the old behaviour and use the string as
-    # a prefix.
-    # Remark: It is an implementation detail that we use Pythons %-formatting.
-    # So far we only expose ``%s`` and require quoting of ``%`` using ``%%``.
-    def role(typ: str, rawtext: str, text: str, lineno: int,
-             inliner: Inliner, options: dict = {}, content: list[str] = []
-             ) -> tuple[list[Node], list[system_message]]:
-        text = utils.unescape(text)
-        has_explicit_title, title, part = split_explicit_title(text)
-        full_url = base_url % part
-        if not has_explicit_title:
-            if caption is None:
-                title = full_url
-            else:
-                title = caption % part
-        pnode = nodes.reference(title, title, internal=False, refuri=full_url)
-        return [pnode], []
-    return role
-
-
-def setup_link_roles(app: Sphinx) -> None:
-    for name, (base_url, caption) in app.config.extlinks.items():
-        app.add_role(name, make_link_role(name, base_url, caption))
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_config_value('extlinks', {}, 'env')
-    app.add_config_value('extlinks_detect_hardcoded_links', False, 'env')
-
-    app.connect('builder-inited', setup_link_roles)
-    app.add_post_transform(ExternalLinksChecker)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

py2docfx/venv/template/Lib/site-packages/sphinx/ext/githubpages.py

@@ -1,31 +0,0 @@
-"""To publish HTML docs at GitHub Pages, create .nojekyll file."""
-
-from __future__ import annotations
-
-import os
-import urllib
-from typing import Any
-
-import sphinx
-from sphinx.application import Sphinx
-from sphinx.environment import BuildEnvironment
-
-
-def create_nojekyll_and_cname(app: Sphinx, env: BuildEnvironment) -> None:
-    if app.builder.format == 'html':
-        open(os.path.join(app.builder.outdir, '.nojekyll'), 'wb').close()
-
-        html_baseurl = app.config.html_baseurl
-        if html_baseurl:
-            domain = urllib.parse.urlparse(html_baseurl).hostname
-            if domain and not domain.endswith(".github.io"):
-                with open(os.path.join(app.builder.outdir, 'CNAME'), 'w',
-                          encoding="utf-8") as f:
-                    # NOTE: don't write a trailing newline. The `CNAME` file that's
-                    # auto-generated by the Github UI doesn't have one.
-                    f.write(domain)
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.connect('env-updated', create_nojekyll_and_cname)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

py2docfx/venv/template/Lib/site-packages/sphinx/ext/graphviz.py

@@ -1,416 +0,0 @@
-"""Allow graphviz-formatted graphs to be included inline in generated documents.
-"""
-
-from __future__ import annotations
-
-import posixpath
-import re
-import subprocess
-from os import path
-from subprocess import CalledProcessError
-from typing import Any
-
-from docutils import nodes
-from docutils.nodes import Node
-from docutils.parsers.rst import Directive, directives
-
-import sphinx
-from sphinx.application import Sphinx
-from sphinx.errors import SphinxError
-from sphinx.locale import _, __
-from sphinx.util import logging, sha1
-from sphinx.util.docutils import SphinxDirective, SphinxTranslator
-from sphinx.util.fileutil import copy_asset
-from sphinx.util.i18n import search_image_for_language
-from sphinx.util.nodes import set_source_info
-from sphinx.util.osutil import ensuredir
-from sphinx.util.typing import OptionSpec
-from sphinx.writers.html import HTML5Translator
-from sphinx.writers.latex import LaTeXTranslator
-from sphinx.writers.manpage import ManualPageTranslator
-from sphinx.writers.texinfo import TexinfoTranslator
-from sphinx.writers.text import TextTranslator
-
-logger = logging.getLogger(__name__)
-
-
-class GraphvizError(SphinxError):
-    category = 'Graphviz error'
-
-
-class ClickableMapDefinition:
-    """A manipulator for clickable map file of graphviz."""
-    maptag_re = re.compile('<map id="(.*?)"')
-    href_re = re.compile('href=".*?"')
-
-    def __init__(self, filename: str, content: str, dot: str = '') -> None:
-        self.id: str | None = None
-        self.filename = filename
-        self.content = content.splitlines()
-        self.clickable: list[str] = []
-
-        self.parse(dot=dot)
-
-    def parse(self, dot: str) -> None:
-        matched = self.maptag_re.match(self.content[0])
-        if not matched:
-            raise GraphvizError('Invalid clickable map file found: %s' % self.filename)
-
-        self.id = matched.group(1)
-        if self.id == '%3':
-            # graphviz generates wrong ID if graph name not specified
-            # https://gitlab.com/graphviz/graphviz/issues/1327
-            hashed = sha1(dot.encode()).hexdigest()
-            self.id = 'grapviz%s' % hashed[-10:]
-            self.content[0] = self.content[0].replace('%3', self.id)
-
-        for line in self.content:
-            if self.href_re.search(line):
-                self.clickable.append(line)
-
-    def generate_clickable_map(self) -> str:
-        """Generate clickable map tags if clickable item exists.
-
-        If not exists, this only returns empty string.
-        """
-        if self.clickable:
-            return '\n'.join([self.content[0]] + self.clickable + [self.content[-1]])
-        else:
-            return ''
-
-
-class graphviz(nodes.General, nodes.Inline, nodes.Element):
-    pass
-
-
-def figure_wrapper(directive: Directive, node: graphviz, caption: str) -> nodes.figure:
-    figure_node = nodes.figure('', node)
-    if 'align' in node:
-        figure_node['align'] = node.attributes.pop('align')
-
-    inodes, messages = directive.state.inline_text(caption, directive.lineno)
-    caption_node = nodes.caption(caption, '', *inodes)
-    caption_node.extend(messages)
-    set_source_info(directive, caption_node)
-    figure_node += caption_node
-    return figure_node
-
-
-def align_spec(argument: Any) -> str:
-    return directives.choice(argument, ('left', 'center', 'right'))
-
-
-class Graphviz(SphinxDirective):
-    """
-    Directive to insert arbitrary dot markup.
-    """
-    has_content = True
-    required_arguments = 0
-    optional_arguments = 1
-    final_argument_whitespace = False
-    option_spec: OptionSpec = {
-        'alt': directives.unchanged,
-        'align': align_spec,
-        'caption': directives.unchanged,
-        'layout': directives.unchanged,
-        'graphviz_dot': directives.unchanged,  # an old alias of `layout` option
-        'name': directives.unchanged,
-        'class': directives.class_option,
-    }
-
-    def run(self) -> list[Node]:
-        if self.arguments:
-            document = self.state.document
-            if self.content:
-                return [document.reporter.warning(
-                    __('Graphviz directive cannot have both content and '
-                       'a filename argument'), line=self.lineno)]
-            argument = search_image_for_language(self.arguments[0], self.env)
-            rel_filename, filename = self.env.relfn2path(argument)
-            self.env.note_dependency(rel_filename)
-            try:
-                with open(filename, encoding='utf-8') as fp:
-                    dotcode = fp.read()
-            except OSError:
-                return [document.reporter.warning(
-                    __('External Graphviz file %r not found or reading '
-                       'it failed') % filename, line=self.lineno)]
-        else:
-            dotcode = '\n'.join(self.content)
-            rel_filename = None
-            if not dotcode.strip():
-                return [self.state_machine.reporter.warning(
-                    __('Ignoring "graphviz" directive without content.'),
-                    line=self.lineno)]
-        node = graphviz()
-        node['code'] = dotcode
-        node['options'] = {'docname': self.env.docname}
-
-        if 'graphviz_dot' in self.options:
-            node['options']['graphviz_dot'] = self.options['graphviz_dot']
-        if 'layout' in self.options:
-            node['options']['graphviz_dot'] = self.options['layout']
-        if 'alt' in self.options:
-            node['alt'] = self.options['alt']
-        if 'align' in self.options:
-            node['align'] = self.options['align']
-        if 'class' in self.options:
-            node['classes'] = self.options['class']
-        if rel_filename:
-            node['filename'] = rel_filename
-
-        if 'caption' not in self.options:
-            self.add_name(node)
-            return [node]
-        else:
-            figure = figure_wrapper(self, node, self.options['caption'])
-            self.add_name(figure)
-            return [figure]
-
-
-class GraphvizSimple(SphinxDirective):
-    """
-    Directive to insert arbitrary dot markup.
-    """
-    has_content = True
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = False
-    option_spec: OptionSpec = {
-        'alt': directives.unchanged,
-        'align': align_spec,
-        'caption': directives.unchanged,
-        'layout': directives.unchanged,
-        'graphviz_dot': directives.unchanged,  # an old alias of `layout` option
-        'name': directives.unchanged,
-        'class': directives.class_option,
-    }
-
-    def run(self) -> list[Node]:
-        node = graphviz()
-        node['code'] = '%s %s {\n%s\n}\n' % \
-                       (self.name, self.arguments[0], '\n'.join(self.content))
-        node['options'] = {'docname': self.env.docname}
-        if 'graphviz_dot' in self.options:
-            node['options']['graphviz_dot'] = self.options['graphviz_dot']
-        if 'layout' in self.options:
-            node['options']['graphviz_dot'] = self.options['layout']
-        if 'alt' in self.options:
-            node['alt'] = self.options['alt']
-        if 'align' in self.options:
-            node['align'] = self.options['align']
-        if 'class' in self.options:
-            node['classes'] = self.options['class']
-
-        if 'caption' not in self.options:
-            self.add_name(node)
-            return [node]
-        else:
-            figure = figure_wrapper(self, node, self.options['caption'])
-            self.add_name(figure)
-            return [figure]
-
-
-def render_dot(self: SphinxTranslator, code: str, options: dict, format: str,
-               prefix: str = 'graphviz', filename: str | None = None
-               ) -> tuple[str | None, str | None]:
-    """Render graphviz code into a PNG or PDF output file."""
-    graphviz_dot = options.get('graphviz_dot', self.builder.config.graphviz_dot)
-    hashkey = (code + str(options) + str(graphviz_dot) +
-               str(self.builder.config.graphviz_dot_args)).encode()
-
-    fname = f'{prefix}-{sha1(hashkey).hexdigest()}.{format}'
-    relfn = posixpath.join(self.builder.imgpath, fname)
-    outfn = path.join(self.builder.outdir, self.builder.imagedir, fname)
-
-    if path.isfile(outfn):
-        return relfn, outfn
-
-    if (hasattr(self.builder, '_graphviz_warned_dot') and
-       self.builder._graphviz_warned_dot.get(graphviz_dot)):
-        return None, None
-
-    ensuredir(path.dirname(outfn))
-
-    dot_args = [graphviz_dot]
-    dot_args.extend(self.builder.config.graphviz_dot_args)
-    dot_args.extend(['-T' + format, '-o' + outfn])
-
-    docname = options.get('docname', 'index')
-    if filename:
-        cwd = path.dirname(path.join(self.builder.srcdir, filename))
-    else:
-        cwd = path.dirname(path.join(self.builder.srcdir, docname))
-
-    if format == 'png':
-        dot_args.extend(['-Tcmapx', '-o%s.map' % outfn])
-
-    try:
-        ret = subprocess.run(dot_args, input=code.encode(), capture_output=True,
-                             cwd=cwd, check=True)
-        if not path.isfile(outfn):
-            raise GraphvizError(__('dot did not produce an output file:\n[stderr]\n%r\n'
-                                   '[stdout]\n%r') % (ret.stderr, ret.stdout))
-        return relfn, outfn
-    except OSError:
-        logger.warning(__('dot command %r cannot be run (needed for graphviz '
-                          'output), check the graphviz_dot setting'), graphviz_dot)
-        if not hasattr(self.builder, '_graphviz_warned_dot'):
-            self.builder._graphviz_warned_dot = {}  # type: ignore
-        self.builder._graphviz_warned_dot[graphviz_dot] = True  # type: ignore
-        return None, None
-    except CalledProcessError as exc:
-        raise GraphvizError(__('dot exited with error:\n[stderr]\n%r\n'
-                               '[stdout]\n%r') % (exc.stderr, exc.stdout)) from exc
-
-
-def render_dot_html(self: HTML5Translator, node: graphviz, code: str, options: dict,
-                    prefix: str = 'graphviz', imgcls: str | None = None,
-                    alt: str | None = None, filename: str | None = None
-                    ) -> tuple[str, str]:
-    format = self.builder.config.graphviz_output_format
-    try:
-        if format not in ('png', 'svg'):
-            raise GraphvizError(__("graphviz_output_format must be one of 'png', "
-                                   "'svg', but is %r") % format)
-        fname, outfn = render_dot(self, code, options, format, prefix, filename)
-    except GraphvizError as exc:
-        logger.warning(__('dot code %r: %s'), code, exc)
-        raise nodes.SkipNode from exc
-
-    classes = [imgcls, 'graphviz'] + node.get('classes', [])
-    imgcls = ' '.join(filter(None, classes))
-
-    if fname is None:
-        self.body.append(self.encode(code))
-    else:
-        if alt is None:
-            alt = node.get('alt', self.encode(code).strip())
-        if 'align' in node:
-            self.body.append('<div align="%s" class="align-%s">' %
-                             (node['align'], node['align']))
-        if format == 'svg':
-            self.body.append('<div class="graphviz">')
-            self.body.append('<object data="%s" type="image/svg+xml" class="%s">\n' %
-                             (fname, imgcls))
-            self.body.append('<p class="warning">%s</p>' % alt)
-            self.body.append('</object></div>\n')
-        else:
-            with open(outfn + '.map', encoding='utf-8') as mapfile:
-                imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code)
-                if imgmap.clickable:
-                    # has a map
-                    self.body.append('<div class="graphviz">')
-                    self.body.append('<img src="%s" alt="%s" usemap="#%s" class="%s" />' %
-                                     (fname, alt, imgmap.id, imgcls))
-                    self.body.append('</div>\n')
-                    self.body.append(imgmap.generate_clickable_map())
-                else:
-                    # nothing in image map
-                    self.body.append('<div class="graphviz">')
-                    self.body.append('<img src="%s" alt="%s" class="%s" />' %
-                                     (fname, alt, imgcls))
-                    self.body.append('</div>\n')
-        if 'align' in node:
-            self.body.append('</div>\n')
-
-    raise nodes.SkipNode
-
-
-def html_visit_graphviz(self: HTML5Translator, node: graphviz) -> None:
-    render_dot_html(self, node, node['code'], node['options'], filename=node.get('filename'))
-
-
-def render_dot_latex(self: LaTeXTranslator, node: graphviz, code: str,
-                     options: dict, prefix: str = 'graphviz', filename: str | None = None
-                     ) -> None:
-    try:
-        fname, outfn = render_dot(self, code, options, 'pdf', prefix, filename)
-    except GraphvizError as exc:
-        logger.warning(__('dot code %r: %s'), code, exc)
-        raise nodes.SkipNode from exc
-
-    is_inline = self.is_inline(node)
-
-    if not is_inline:
-        pre = ''
-        post = ''
-        if 'align' in node:
-            if node['align'] == 'left':
-                pre = '{'
-                post = r'\hspace*{\fill}}'
-            elif node['align'] == 'right':
-                pre = r'{\hspace*{\fill}'
-                post = '}'
-            elif node['align'] == 'center':
-                pre = r'{\hfill'
-                post = r'\hspace*{\fill}}'
-        self.body.append('\n%s' % pre)
-
-    self.body.append(r'\sphinxincludegraphics[]{%s}' % fname)
-
-    if not is_inline:
-        self.body.append('%s\n' % post)
-
-    raise nodes.SkipNode
-
-
-def latex_visit_graphviz(self: LaTeXTranslator, node: graphviz) -> None:
-    render_dot_latex(self, node, node['code'], node['options'], filename=node.get('filename'))
-
-
-def render_dot_texinfo(self: TexinfoTranslator, node: graphviz, code: str,
-                       options: dict, prefix: str = 'graphviz') -> None:
-    try:
-        fname, outfn = render_dot(self, code, options, 'png', prefix)
-    except GraphvizError as exc:
-        logger.warning(__('dot code %r: %s'), code, exc)
-        raise nodes.SkipNode from exc
-    if fname is not None:
-        self.body.append('@image{%s,,,[graphviz],png}\n' % fname[:-4])
-    raise nodes.SkipNode
-
-
-def texinfo_visit_graphviz(self: TexinfoTranslator, node: graphviz) -> None:
-    render_dot_texinfo(self, node, node['code'], node['options'])
-
-
-def text_visit_graphviz(self: TextTranslator, node: graphviz) -> None:
-    if 'alt' in node.attributes:
-        self.add_text(_('[graph: %s]') % node['alt'])
-    else:
-        self.add_text(_('[graph]'))
-    raise nodes.SkipNode
-
-
-def man_visit_graphviz(self: ManualPageTranslator, node: graphviz) -> None:
-    if 'alt' in node.attributes:
-        self.body.append(_('[graph: %s]') % node['alt'])
-    else:
-        self.body.append(_('[graph]'))
-    raise nodes.SkipNode
-
-
-def on_build_finished(app: Sphinx, exc: Exception) -> None:
-    if exc is None and app.builder.format == 'html':
-        src = path.join(sphinx.package_dir, 'templates', 'graphviz', 'graphviz.css')
-        dst = path.join(app.outdir, '_static')
-        copy_asset(src, dst)
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_node(graphviz,
-                 html=(html_visit_graphviz, None),
-                 latex=(latex_visit_graphviz, None),
-                 texinfo=(texinfo_visit_graphviz, None),
-                 text=(text_visit_graphviz, None),
-                 man=(man_visit_graphviz, None))
-    app.add_directive('graphviz', Graphviz)
-    app.add_directive('graph', GraphvizSimple)
-    app.add_directive('digraph', GraphvizSimple)
-    app.add_config_value('graphviz_dot', 'dot', 'html')
-    app.add_config_value('graphviz_dot_args', [], 'html')
-    app.add_config_value('graphviz_output_format', 'png', 'html')
-    app.add_css_file('graphviz.css')
-    app.connect('build-finished', on_build_finished)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

py2docfx/venv/template/Lib/site-packages/sphinx/ext/ifconfig.py

@@ -1,78 +0,0 @@
-"""Provides the ``ifconfig`` directive.
-
-The ``ifconfig`` directive enables writing documentation
-that is included depending on configuration variables.
-
-Usage::
-
-    .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
-
-       This stuff is only included in the built docs for unstable versions.
-
-The argument for ``ifconfig`` is a plain Python expression, evaluated in the
-namespace of the project configuration (that is, all variables from
-``conf.py`` are available.)
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from docutils import nodes
-from docutils.nodes import Node
-
-import sphinx
-from sphinx.application import Sphinx
-from sphinx.util.docutils import SphinxDirective
-from sphinx.util.nodes import nested_parse_with_titles
-from sphinx.util.typing import OptionSpec
-
-
-class ifconfig(nodes.Element):
-    pass
-
-
-class IfConfig(SphinxDirective):
-
-    has_content = True
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = True
-    option_spec: OptionSpec = {}
-
-    def run(self) -> list[Node]:
-        node = ifconfig()
-        node.document = self.state.document
-        self.set_source_info(node)
-        node['expr'] = self.arguments[0]
-        nested_parse_with_titles(self.state, self.content, node)
-        return [node]
-
-
-def process_ifconfig_nodes(app: Sphinx, doctree: nodes.document, docname: str) -> None:
-    ns = {confval.name: confval.value for confval in app.config}
-    ns.update(app.config.__dict__.copy())
-    ns['builder'] = app.builder.name
-    for node in list(doctree.findall(ifconfig)):
-        try:
-            res = eval(node['expr'], ns)  # NoQA: PGH001
-        except Exception as err:
-            # handle exceptions in a clean fashion
-            from traceback import format_exception_only
-            msg = ''.join(format_exception_only(err.__class__, err))
-            newnode = doctree.reporter.error('Exception occurred in '
-                                             'ifconfig expression: \n%s' %
-                                             msg, base_node=node)
-            node.replace_self(newnode)
-        else:
-            if not res:
-                node.replace_self([])
-            else:
-                node.replace_self(node.children)
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_node(ifconfig)
-    app.add_directive('ifconfig', IfConfig)
-    app.connect('doctree-resolved', process_ifconfig_nodes)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}