py2docfx 0.1.10.dev1811995__py3-none-any.whl → 0.1.10.dev1817528__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/environment/adapters/__init__.py

@@ -0,0 +1 @@
+"""Sphinx environment adapters"""

py2docfx/venv/template/Lib/site-packages/sphinx/environment/adapters/asset.py

@@ -0,0 +1,15 @@
+"""Assets adapter for sphinx.environment."""
+
+from sphinx.environment import BuildEnvironment
+
+
+class ImageAdapter:
+    def __init__(self, env: BuildEnvironment) -> None:
+        self.env = env
+
+    def get_original_image_uri(self, name: str) -> str:
+        """Get the original image URI."""
+        while name in self.env.original_image_uri:
+            name = self.env.original_image_uri[name]
+
+        return name

py2docfx/venv/template/Lib/site-packages/sphinx/environment/adapters/indexentries.py

@@ -0,0 +1,172 @@
+"""Index entries adapters for sphinx.environment."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from itertools import groupby
+from typing import Any, cast
+
+from sphinx.builders import Builder
+from sphinx.domains.index import IndexDomain
+from sphinx.environment import BuildEnvironment
+from sphinx.errors import NoUri
+from sphinx.locale import _, __
+from sphinx.util import logging, split_into
+
+logger = logging.getLogger(__name__)
+
+
+class IndexEntries:
+    def __init__(self, env: BuildEnvironment) -> None:
+        self.env = env
+
+    def create_index(self, builder: Builder, group_entries: bool = True,
+                     _fixre: re.Pattern = re.compile(r'(.*) ([(][^()]*[)])')
+                     ) -> list[tuple[str, list[tuple[str, Any]]]]:
+        """Create the real index from the collected index entries."""
+        new: dict[str, list] = {}
+
+        def add_entry(word: str, subword: str, main: str | None, link: bool = True,
+                      dic: dict[str, list] = new, key: str | None = None) -> None:
+            # Force the word to be unicode if it's a ASCII bytestring.
+            # This will solve problems with unicode normalization later.
+            # For instance the RFC role will add bytestrings at the moment
+            word = str(word)
+            entry = dic.get(word)
+            if not entry:
+                dic[word] = entry = [[], {}, key]
+            if subword:
+                add_entry(subword, '', main, link=link, dic=entry[1], key=key)
+            elif link:
+                try:
+                    uri = builder.get_relative_uri('genindex', fn) + '#' + tid
+                except NoUri:
+                    pass
+                else:
+                    entry[0].append((main, uri))
+
+        domain = cast(IndexDomain, self.env.get_domain('index'))
+        for fn, entries in domain.entries.items():
+            # new entry types must be listed in directives/other.py!
+            for type, value, tid, main, index_key in entries:  # noqa: B007
+                try:
+                    if type == 'single':
+                        try:
+                            entry, subentry = split_into(2, 'single', value)
+                        except ValueError:
+                            entry, = split_into(1, 'single', value)
+                            subentry = ''
+                        add_entry(entry, subentry, main, key=index_key)
+                    elif type == 'pair':
+                        first, second = split_into(2, 'pair', value)
+                        add_entry(first, second, main, key=index_key)
+                        add_entry(second, first, main, key=index_key)
+                    elif type == 'triple':
+                        first, second, third = split_into(3, 'triple', value)
+                        add_entry(first, second + ' ' + third, main, key=index_key)
+                        add_entry(second, third + ', ' + first, main, key=index_key)
+                        add_entry(third, first + ' ' + second, main, key=index_key)
+                    elif type == 'see':
+                        first, second = split_into(2, 'see', value)
+                        add_entry(first, _('see %s') % second, None,
+                                  link=False, key=index_key)
+                    elif type == 'seealso':
+                        first, second = split_into(2, 'see', value)
+                        add_entry(first, _('see also %s') % second, None,
+                                  link=False, key=index_key)
+                    else:
+                        logger.warning(__('unknown index entry type %r'), type, location=fn)
+                except ValueError as err:
+                    logger.warning(str(err), location=fn)
+
+        # sort the index entries for same keyword.
+        def keyfunc0(entry: tuple[str, str]) -> tuple[bool, str]:
+            main, uri = entry
+            return (not main, uri)  # show main entries at first
+
+        for indexentry in new.values():
+            indexentry[0].sort(key=keyfunc0)
+            for subentry in indexentry[1].values():
+                subentry[0].sort(key=keyfunc0)  # type: ignore
+
+        # sort the index entries
+        def keyfunc(entry: tuple[str, list]) -> tuple[tuple[int, str], str]:
+            key, (void, void, category_key) = entry
+            if category_key:
+                # using specified category key to sort
+                key = category_key
+            lckey = unicodedata.normalize('NFD', key.lower())
+            if lckey.startswith('\N{RIGHT-TO-LEFT MARK}'):
+                lckey = lckey[1:]
+
+            if lckey[0:1].isalpha() or lckey.startswith('_'):
+                # put non-symbol characters at the following group (1)
+                sortkey = (1, lckey)
+            else:
+                # put symbols at the front of the index (0)
+                sortkey = (0, lckey)
+            # ensure a deterministic order *within* letters by also sorting on
+            # the entry itself
+            return (sortkey, entry[0])
+        newlist = sorted(new.items(), key=keyfunc)
+
+        if group_entries:
+            # fixup entries: transform
+            #   func() (in module foo)
+            #   func() (in module bar)
+            # into
+            #   func()
+            #     (in module foo)
+            #     (in module bar)
+            oldkey = ''
+            oldsubitems: dict[str, list] | None = None
+            i = 0
+            while i < len(newlist):
+                key, (targets, subitems, _key) = newlist[i]
+                # cannot move if it has subitems; structure gets too complex
+                if not subitems:
+                    m = _fixre.match(key)
+                    if m:
+                        if oldkey == m.group(1):
+                            # prefixes match: add entry as subitem of the
+                            # previous entry
+                            oldsubitems.setdefault(m.group(2), [[], {}, _key])[0].\
+                                extend(targets)
+                            del newlist[i]
+                            continue
+                        oldkey = m.group(1)
+                    else:
+                        oldkey = key
+                oldsubitems = subitems
+                i += 1
+
+        # sort the sub-index entries
+        def keyfunc2(entry: tuple[str, list]) -> str:
+            key = unicodedata.normalize('NFD', entry[0].lower())
+            if key.startswith('\N{RIGHT-TO-LEFT MARK}'):
+                key = key[1:]
+            if key[0:1].isalpha() or key.startswith('_'):
+                key = chr(127) + key
+            return key
+
+        # group the entries by letter
+        def keyfunc3(item: tuple[str, list]) -> str:
+            # hack: mutating the subitems dicts to a list in the keyfunc
+            k, v = item
+            v[1] = sorted(((si, se) for (si, (se, void, void)) in v[1].items()),
+                          key=keyfunc2)
+            if v[2] is None:
+                # now calculate the key
+                if k.startswith('\N{RIGHT-TO-LEFT MARK}'):
+                    k = k[1:]
+                letter = unicodedata.normalize('NFD', k[0])[0].upper()
+                if letter.isalpha() or letter == '_':
+                    return letter
+                else:
+                    # get all other symbols under one heading
+                    return _('Symbols')
+            else:
+                return v[2]
+        return [(key_, list(group))
+                for (key_, group) in groupby(newlist, keyfunc3)]

py2docfx/venv/template/Lib/site-packages/sphinx/environment/adapters/toctree.py

@@ -0,0 +1,340 @@
+"""Toctree adapter for sphinx.environment."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable, TypeVar, cast
+
+from docutils import nodes
+from docutils.nodes import Element, Node
+
+from sphinx import addnodes
+from sphinx.locale import __
+from sphinx.util import logging, url_re
+from sphinx.util.matching import Matcher
+from sphinx.util.nodes import clean_astext, process_only_nodes
+
+if TYPE_CHECKING:
+    from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
+
+
+logger = logging.getLogger(__name__)
+
+
+class TocTree:
+    def __init__(self, env: BuildEnvironment) -> None:
+        self.env = env
+
+    def note(self, docname: str, toctreenode: addnodes.toctree) -> None:
+        """Note a TOC tree directive in a document and gather information about
+        file relations from it.
+        """
+        if toctreenode['glob']:
+            self.env.glob_toctrees.add(docname)
+        if toctreenode.get('numbered'):
+            self.env.numbered_toctrees.add(docname)
+        includefiles = toctreenode['includefiles']
+        for includefile in includefiles:
+            # note that if the included file is rebuilt, this one must be
+            # too (since the TOC of the included file could have changed)
+            self.env.files_to_rebuild.setdefault(includefile, set()).add(docname)
+        self.env.toctree_includes.setdefault(docname, []).extend(includefiles)
+
+    def resolve(self, docname: str, builder: Builder, toctree: addnodes.toctree,
+                prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
+                collapse: bool = False, includehidden: bool = False) -> Element | None:
+        """Resolve a *toctree* node into individual bullet lists with titles
+        as items, returning None (if no containing titles are found) or
+        a new node.
+
+        If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
+        to the value of the *maxdepth* option on the *toctree* node.
+        If *titles_only* is True, only toplevel document titles will be in the
+        resulting tree.
+        If *collapse* is True, all branches not containing docname will
+        be collapsed.
+        """
+        if toctree.get('hidden', False) and not includehidden:
+            return None
+        generated_docnames: dict[str, tuple[str, str]] = self.env.domains['std']._virtual_doc_names.copy()  # NoQA: E501
+
+        # For reading the following two helper function, it is useful to keep
+        # in mind the node structure of a toctree (using HTML-like node names
+        # for brevity):
+        #
+        # <ul>
+        #   <li>
+        #     <p><a></p>
+        #     <p><a></p>
+        #     ...
+        #     <ul>
+        #       ...
+        #     </ul>
+        #   </li>
+        # </ul>
+        #
+        # The transformation is made in two passes in order to avoid
+        # interactions between marking and pruning the tree (see bug #1046).
+
+        toctree_ancestors = self.get_toctree_ancestors(docname)
+        included = Matcher(self.env.config.include_patterns)
+        excluded = Matcher(self.env.config.exclude_patterns)
+
+        def _toctree_add_classes(node: Element, depth: int) -> None:
+            """Add 'toctree-l%d' and 'current' classes to the toctree."""
+            for subnode in node.children:
+                if isinstance(subnode, (addnodes.compact_paragraph,
+                                        nodes.list_item)):
+                    # for <p> and <li>, indicate the depth level and recurse
+                    subnode['classes'].append(f'toctree-l{depth - 1}')
+                    _toctree_add_classes(subnode, depth)
+                elif isinstance(subnode, nodes.bullet_list):
+                    # for <ul>, just recurse
+                    _toctree_add_classes(subnode, depth + 1)
+                elif isinstance(subnode, nodes.reference):
+                    # for <a>, identify which entries point to the current
+                    # document and therefore may not be collapsed
+                    if subnode['refuri'] == docname:
+                        if not subnode['anchorname']:
+                            # give the whole branch a 'current' class
+                            # (useful for styling it differently)
+                            branchnode: Element = subnode
+                            while branchnode:
+                                branchnode['classes'].append('current')
+                                branchnode = branchnode.parent
+                        # mark the list_item as "on current page"
+                        if subnode.parent.parent.get('iscurrent'):
+                            # but only if it's not already done
+                            return
+                        while subnode:
+                            subnode['iscurrent'] = True
+                            subnode = subnode.parent
+
+        def _entries_from_toctree(toctreenode: addnodes.toctree, parents: list[str],
+                                  subtree: bool = False) -> list[Element]:
+            """Return TOC entries for a toctree node."""
+            refs = [(e[0], e[1]) for e in toctreenode['entries']]
+            entries: list[Element] = []
+            for (title, ref) in refs:
+                try:
+                    refdoc = None
+                    if url_re.match(ref):
+                        if title is None:
+                            title = ref
+                        reference = nodes.reference('', '', internal=False,
+                                                    refuri=ref, anchorname='',
+                                                    *[nodes.Text(title)])
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        toc = nodes.bullet_list('', item)
+                    elif ref == 'self':
+                        # 'self' refers to the document from which this
+                        # toctree originates
+                        ref = toctreenode['parent']
+                        if not title:
+                            title = clean_astext(self.env.titles[ref])
+                        reference = nodes.reference('', '', internal=True,
+                                                    refuri=ref,
+                                                    anchorname='',
+                                                    *[nodes.Text(title)])
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        # don't show subitems
+                        toc = nodes.bullet_list('', item)
+                    elif ref in generated_docnames:
+                        docname, sectionname = generated_docnames[ref]
+                        if not title:
+                            title = sectionname
+                        reference = nodes.reference('', title, internal=True,
+                                                    refuri=docname, anchorname='')
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        # don't show subitems
+                        toc = nodes.bullet_list('', item)
+                    else:
+                        if ref in parents:
+                            logger.warning(__('circular toctree references '
+                                              'detected, ignoring: %s <- %s'),
+                                           ref, ' <- '.join(parents),
+                                           location=ref, type='toc', subtype='circular')
+                            continue
+                        refdoc = ref
+                        maxdepth = self.env.metadata[ref].get('tocdepth', 0)
+                        toc = self.env.tocs[ref]
+                        if ref not in toctree_ancestors or (prune and maxdepth > 0):
+                            toc = self._toctree_copy(toc, 2, maxdepth, collapse)
+                        else:
+                            toc = toc.deepcopy()
+                        process_only_nodes(toc, builder.tags)
+                        if title and toc.children and len(toc.children) == 1:
+                            child = toc.children[0]
+                            for refnode in child.findall(nodes.reference):
+                                if refnode['refuri'] == ref and \
+                                   not refnode['anchorname']:
+                                    refnode.children = [nodes.Text(title)]
+                    if not toc.children:
+                        # empty toc means: no titles will show up in the toctree
+                        logger.warning(__('toctree contains reference to document %r that '
+                                          'doesn\'t have a title: no link will be generated'),
+                                       ref, location=toctreenode)
+                except KeyError:
+                    # this is raised if the included file does not exist
+                    if excluded(self.env.doc2path(ref, False)):
+                        message = __('toctree contains reference to excluded document %r')
+                    elif not included(self.env.doc2path(ref, False)):
+                        message = __('toctree contains reference to non-included document %r')
+                    else:
+                        message = __('toctree contains reference to nonexisting document %r')
+
+                    logger.warning(message, ref, location=toctreenode)
+                else:
+                    # children of toc are:
+                    # - list_item + compact_paragraph + (reference and subtoc)
+                    # - only + subtoc
+                    # - toctree
+                    children = cast(Iterable[nodes.Element], toc)
+
+                    # if titles_only is given, only keep the main title and
+                    # sub-toctrees
+                    if titles_only:
+                        # delete everything but the toplevel title(s)
+                        # and toctrees
+                        for toplevel in children:
+                            # nodes with length 1 don't have any children anyway
+                            if len(toplevel) > 1:
+                                subtrees = list(toplevel.findall(addnodes.toctree))
+                                if subtrees:
+                                    toplevel[1][:] = subtrees  # type: ignore
+                                else:
+                                    toplevel.pop(1)
+                    # resolve all sub-toctrees
+                    for sub_toc_node in list(toc.findall(addnodes.toctree)):
+                        if sub_toc_node.get('hidden', False) and not includehidden:
+                            continue
+                        for i, entry in enumerate(
+                            _entries_from_toctree(sub_toc_node, [refdoc] + parents,
+                                                  subtree=True),
+                            start=sub_toc_node.parent.index(sub_toc_node) + 1
+                        ):
+                            sub_toc_node.parent.insert(i, entry)
+                        sub_toc_node.parent.remove(sub_toc_node)
+
+                    entries.extend(children)
+            if not subtree:
+                ret = nodes.bullet_list()
+                ret += entries
+                return [ret]
+            return entries
+
+        maxdepth = maxdepth or toctree.get('maxdepth', -1)
+        if not titles_only and toctree.get('titlesonly', False):
+            titles_only = True
+        if not includehidden and toctree.get('includehidden', False):
+            includehidden = True
+
+        tocentries = _entries_from_toctree(toctree, [])
+        if not tocentries:
+            return None
+
+        newnode = addnodes.compact_paragraph('', '')
+        caption = toctree.attributes.get('caption')
+        if caption:
+            caption_node = nodes.title(caption, '', *[nodes.Text(caption)])
+            caption_node.line = toctree.line
+            caption_node.source = toctree.source
+            caption_node.rawsource = toctree['rawcaption']
+            if hasattr(toctree, 'uid'):
+                # move uid to caption_node to translate it
+                caption_node.uid = toctree.uid  # type: ignore
+                del toctree.uid
+            newnode += caption_node
+        newnode.extend(tocentries)
+        newnode['toctree'] = True
+
+        # prune the tree to maxdepth, also set toc depth and current classes
+        _toctree_add_classes(newnode, 1)
+        newnode = self._toctree_copy(newnode, 1, maxdepth if prune else 0, collapse)
+
+        if isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0:  # No titles found
+            return None
+
+        # set the target paths in the toctrees (they are not known at TOC
+        # generation time)
+        for refnode in newnode.findall(nodes.reference):
+            if not url_re.match(refnode['refuri']):
+                refnode['refuri'] = builder.get_relative_uri(
+                    docname, refnode['refuri']) + refnode['anchorname']
+        return newnode
+
+    def get_toctree_ancestors(self, docname: str) -> list[str]:
+        parent = {}
+        for p, children in self.env.toctree_includes.items():
+            for child in children:
+                parent[child] = p
+        ancestors: list[str] = []
+        d = docname
+        while d in parent and d not in ancestors:
+            ancestors.append(d)
+            d = parent[d]
+        return ancestors
+
+    ET = TypeVar('ET', bound=Element)
+
+    def _toctree_copy(self, node: ET, depth: int, maxdepth: int, collapse: bool) -> ET:
+        """Utility: Cut and deep-copy a TOC at a specified depth."""
+        keep_bullet_list_sub_nodes = (depth <= 1
+                                      or ((depth <= maxdepth or maxdepth <= 0)
+                                          and (not collapse or 'iscurrent' in node)))
+
+        copy = node.copy()
+        for subnode in node.children:
+            if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
+                # for <p> and <li>, just recurse
+                copy.append(self._toctree_copy(subnode, depth, maxdepth, collapse))
+            elif isinstance(subnode, nodes.bullet_list):
+                # for <ul>, copy if the entry is top-level
+                # or, copy if the depth is within bounds and;
+                # collapsing is disabled or the sub-entry's parent is 'current'.
+                # The boolean is constant so is calculated outwith the loop.
+                if keep_bullet_list_sub_nodes:
+                    copy.append(self._toctree_copy(subnode, depth + 1, maxdepth, collapse))
+            else:
+                copy.append(subnode.deepcopy())
+        return copy
+
+    def get_toc_for(self, docname: str, builder: Builder) -> Node:
+        """Return a TOC nodetree -- for use on the same page only!"""
+        tocdepth = self.env.metadata[docname].get('tocdepth', 0)
+        try:
+            toc = self._toctree_copy(self.env.tocs[docname], 2, tocdepth, False)
+        except KeyError:
+            # the document does not exist anymore: return a dummy node that
+            # renders to nothing
+            return nodes.paragraph()
+        process_only_nodes(toc, builder.tags)
+        for node in toc.findall(nodes.reference):
+            node['refuri'] = node['anchorname'] or '#'
+        return toc
+
+    def get_toctree_for(self, docname: str, builder: Builder, collapse: bool,
+                        **kwargs: Any) -> Element | None:
+        """Return the global TOC nodetree."""
+        doctree = self.env.master_doctree
+        toctrees: list[Element] = []
+        if 'includehidden' not in kwargs:
+            kwargs['includehidden'] = True
+        if 'maxdepth' not in kwargs or not kwargs['maxdepth']:
+            kwargs['maxdepth'] = 0
+        else:
+            kwargs['maxdepth'] = int(kwargs['maxdepth'])
+        kwargs['collapse'] = collapse
+        for toctreenode in doctree.findall(addnodes.toctree):
+            toctree = self.resolve(docname, builder, toctreenode, prune=True, **kwargs)
+            if toctree:
+                toctrees.append(toctree)
+        if not toctrees:
+            return None
+        result = toctrees[0]
+        for toctree in toctrees[1:]:
+            result.extend(toctree.children)
+        return result

py2docfx/venv/template/Lib/site-packages/sphinx/environment/collectors/__init__.py

@@ -0,0 +1,73 @@
+"""The data collector components for sphinx.environment."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+
+from sphinx.environment import BuildEnvironment
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+class EnvironmentCollector:
+    """An EnvironmentCollector is a specific data collector from each document.
+
+    It gathers data and stores :py:class:`BuildEnvironment
+    <sphinx.environment.BuildEnvironment>` as a database.  Examples of specific
+    data would be images, download files, section titles, metadatas, index
+    entries and toctrees, etc.
+    """
+
+    listener_ids: dict[str, int] | None = None
+
+    def enable(self, app: Sphinx) -> None:
+        assert self.listener_ids is None
+        self.listener_ids = {
+            'doctree-read':     app.connect('doctree-read', self.process_doc),
+            'env-merge-info':   app.connect('env-merge-info', self.merge_other),
+            'env-purge-doc':    app.connect('env-purge-doc', self.clear_doc),
+            'env-get-updated':  app.connect('env-get-updated', self.get_updated_docs),
+            'env-get-outdated': app.connect('env-get-outdated', self.get_outdated_docs),
+        }
+
+    def disable(self, app: Sphinx) -> None:
+        assert self.listener_ids is not None
+        for listener_id in self.listener_ids.values():
+            app.disconnect(listener_id)
+        self.listener_ids = None
+
+    def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
+        """Remove specified data of a document.
+
+        This method is called on the removal of the document."""
+        raise NotImplementedError
+
+    def merge_other(self, app: Sphinx, env: BuildEnvironment,
+                    docnames: set[str], other: BuildEnvironment) -> None:
+        """Merge in specified data regarding docnames from a different `BuildEnvironment`
+        object which coming from a subprocess in parallel builds."""
+        raise NotImplementedError
+
+    def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
+        """Process a document and gather specific data from it.
+
+        This method is called after the document is read."""
+        raise NotImplementedError
+
+    def get_updated_docs(self, app: Sphinx, env: BuildEnvironment) -> list[str]:
+        """Return a list of docnames to re-read.
+
+        This methods is called after reading the whole of documents (experimental).
+        """
+        return []
+
+    def get_outdated_docs(self, app: Sphinx, env: BuildEnvironment,
+                          added: set[str], changed: set[str], removed: set[str]) -> list[str]:
+        """Return a list of docnames to re-read.
+
+        This methods is called before reading the documents.
+        """
+        return []