py2docfx 0.1.10.dev1859594__py3-none-any.whl → 0.1.10.dev1870645__py3-none-any.whl

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

@@ -0,0 +1,120 @@
+"""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/venv0/Lib/site-packages/sphinx/ext/githubpages.py

@@ -0,0 +1,31 @@
+"""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/venv0/Lib/site-packages/sphinx/ext/graphviz.py

@@ -0,0 +1,416 @@
+"""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/venv0/Lib/site-packages/sphinx/ext/ifconfig.py

@@ -0,0 +1,78 @@
+"""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}