py2docfx 0.1.11.dev1869610__py3-none-any.whl → 0.1.11.dev1872322__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/builders/changes.py

@@ -0,0 +1,159 @@
+"""Changelog builder."""
+
+from __future__ import annotations
+
+import html
+from os import path
+from typing import Any, cast
+
+from sphinx import package_dir
+from sphinx.application import Sphinx
+from sphinx.builders import Builder
+from sphinx.domains.changeset import ChangeSetDomain
+from sphinx.locale import _, __
+from sphinx.theming import HTMLThemeFactory
+from sphinx.util import logging
+from sphinx.util.console import bold  # type: ignore
+from sphinx.util.fileutil import copy_asset_file
+from sphinx.util.osutil import ensuredir, os_path
+
+logger = logging.getLogger(__name__)
+
+
+class ChangesBuilder(Builder):
+    """
+    Write a summary with all versionadded/changed directives.
+    """
+    name = 'changes'
+    epilog = __('The overview file is in %(outdir)s.')
+
+    def init(self) -> None:
+        self.create_template_bridge()
+        theme_factory = HTMLThemeFactory(self.app)
+        self.theme = theme_factory.create('default')
+        self.templates.init(self, self.theme)
+
+    def get_outdated_docs(self) -> str:
+        return self.outdir
+
+    typemap = {
+        'versionadded': 'added',
+        'versionchanged': 'changed',
+        'deprecated': 'deprecated',
+    }
+
+    def write(self, *ignored: Any) -> None:
+        version = self.config.version
+        domain = cast(ChangeSetDomain, self.env.get_domain('changeset'))
+        libchanges: dict[str, list[tuple[str, str, int]]] = {}
+        apichanges: list[tuple[str, str, int]] = []
+        otherchanges: dict[tuple[str, str], list[tuple[str, str, int]]] = {}
+
+        changesets = domain.get_changesets_for(version)
+        if not changesets:
+            logger.info(bold(__('no changes in version %s.') % version))
+            return
+        logger.info(bold(__('writing summary file...')))
+        for changeset in changesets:
+            if isinstance(changeset.descname, tuple):
+                descname = changeset.descname[0]
+            else:
+                descname = changeset.descname
+            ttext = self.typemap[changeset.type]
+            context = changeset.content.replace('\n', ' ')
+            if descname and changeset.docname.startswith('c-api'):
+                if context:
+                    entry = f'<b>{descname}</b>: <i>{ttext}:</i> {context}'
+                else:
+                    entry = f'<b>{descname}</b>: <i>{ttext}</i>.'
+                apichanges.append((entry, changeset.docname, changeset.lineno))
+            elif descname or changeset.module:
+                module = changeset.module or _('Builtins')
+                if not descname:
+                    descname = _('Module level')
+                if context:
+                    entry = f'<b>{descname}</b>: <i>{ttext}:</i> {context}'
+                else:
+                    entry = f'<b>{descname}</b>: <i>{ttext}</i>.'
+                libchanges.setdefault(module, []).append((entry, changeset.docname,
+                                                          changeset.lineno))
+            else:
+                if not context:
+                    continue
+                entry = f'<i>{ttext.capitalize()}:</i> {context}'
+                title = self.env.titles[changeset.docname].astext()
+                otherchanges.setdefault((changeset.docname, title), []).append(
+                    (entry, changeset.docname, changeset.lineno))
+
+        ctx = {
+            'project': self.config.project,
+            'version': version,
+            'docstitle': self.config.html_title,
+            'shorttitle': self.config.html_short_title,
+            'libchanges': sorted(libchanges.items()),
+            'apichanges': sorted(apichanges),
+            'otherchanges': sorted(otherchanges.items()),
+            'show_copyright': self.config.html_show_copyright,
+            'show_sphinx': self.config.html_show_sphinx,
+        }
+        with open(path.join(self.outdir, 'index.html'), 'w', encoding='utf8') as f:
+            f.write(self.templates.render('changes/frameset.html', ctx))
+        with open(path.join(self.outdir, 'changes.html'), 'w', encoding='utf8') as f:
+            f.write(self.templates.render('changes/versionchanges.html', ctx))
+
+        hltext = ['.. versionadded:: %s' % version,
+                  '.. versionchanged:: %s' % version,
+                  '.. deprecated:: %s' % version]
+
+        def hl(no: int, line: str) -> str:
+            line = '<a name="L%s"> </a>' % no + html.escape(line)
+            for x in hltext:
+                if x in line:
+                    line = '<span class="hl">%s</span>' % line
+                    break
+            return line
+
+        logger.info(bold(__('copying source files...')))
+        for docname in self.env.all_docs:
+            with open(self.env.doc2path(docname),
+                      encoding=self.env.config.source_encoding) as f:
+                try:
+                    lines = f.readlines()
+                except UnicodeDecodeError:
+                    logger.warning(__('could not read %r for changelog creation'), docname)
+                    continue
+            targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html'
+            ensuredir(path.dirname(targetfn))
+            with open(targetfn, 'w', encoding='utf-8') as f:
+                text = ''.join(hl(i + 1, line) for (i, line) in enumerate(lines))
+                ctx = {
+                    'filename': self.env.doc2path(docname, False),
+                    'text': text
+                }
+                f.write(self.templates.render('changes/rstsource.html', ctx))
+        themectx = {'theme_' + key: val for (key, val) in
+                    self.theme.get_options({}).items()}
+        copy_asset_file(path.join(package_dir, 'themes', 'default', 'static', 'default.css_t'),
+                        self.outdir, context=themectx, renderer=self.templates)
+        copy_asset_file(path.join(package_dir, 'themes', 'basic', 'static', 'basic.css'),
+                        self.outdir)
+
+    def hl(self, text: str, version: str) -> str:
+        text = html.escape(text)
+        for directive in ('versionchanged', 'versionadded', 'deprecated'):
+            text = text.replace(f'.. {directive}:: {version}',
+                                f'<b>.. {directive}:: {version}</b>')
+        return text
+
+    def finish(self) -> None:
+        pass
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_builder(ChangesBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

py2docfx/venv/template/Lib/site-packages/sphinx/builders/dirhtml.py

@@ -0,0 +1,51 @@
+"""Directory HTML builders."""
+
+from __future__ import annotations
+
+from os import path
+from typing import Any
+
+from sphinx.application import Sphinx
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.util import logging
+from sphinx.util.osutil import SEP, os_path
+
+logger = logging.getLogger(__name__)
+
+
+class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
+    """
+    A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in
+    a directory given by their pagename, so that generated URLs don't have
+    ``.html`` in them.
+    """
+    name = 'dirhtml'
+
+    def get_target_uri(self, docname: str, typ: str | None = None) -> str:
+        if docname == 'index':
+            return ''
+        if docname.endswith(SEP + 'index'):
+            return docname[:-5]  # up to sep
+        return docname + SEP
+
+    def get_outfilename(self, pagename: str) -> str:
+        if pagename == 'index' or pagename.endswith(SEP + 'index'):
+            outfilename = path.join(self.outdir, os_path(pagename) +
+                                    self.out_suffix)
+        else:
+            outfilename = path.join(self.outdir, os_path(pagename),
+                                    'index' + self.out_suffix)
+
+        return outfilename
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.setup_extension('sphinx.builders.html')
+
+    app.add_builder(DirectoryHTMLBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

py2docfx/venv/template/Lib/site-packages/sphinx/builders/dummy.py

@@ -0,0 +1,46 @@
+"""Do syntax checks, but no writing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from docutils.nodes import Node
+
+from sphinx.application import Sphinx
+from sphinx.builders import Builder
+from sphinx.locale import __
+
+
+class DummyBuilder(Builder):
+    name = 'dummy'
+    epilog = __('The dummy builder generates no files.')
+
+    allow_parallel = True
+
+    def init(self) -> None:
+        pass
+
+    def get_outdated_docs(self) -> set[str]:
+        return self.env.found_docs
+
+    def get_target_uri(self, docname: str, typ: str | None = None) -> str:
+        return ''
+
+    def prepare_writing(self, docnames: set[str]) -> None:
+        pass
+
+    def write_doc(self, docname: str, doctree: Node) -> None:
+        pass
+
+    def finish(self) -> None:
+        pass
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_builder(DummyBuilder)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

py2docfx/venv/template/Lib/site-packages/sphinx/builders/epub3.py

@@ -0,0 +1,293 @@
+"""Build epub3 files.
+
+Originally derived from epub.py.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+from os import path
+from typing import Any, NamedTuple
+
+from sphinx import package_dir
+from sphinx.application import Sphinx
+from sphinx.builders import _epub_base
+from sphinx.config import ENUM, Config
+from sphinx.locale import __
+from sphinx.util import logging
+from sphinx.util.fileutil import copy_asset_file
+from sphinx.util.i18n import format_date
+from sphinx.util.osutil import make_filename
+
+logger = logging.getLogger(__name__)
+
+
+class NavPoint(NamedTuple):
+    text: str
+    refuri: str
+    children: list[Any]     # mypy does not support recursive types
+                            # https://github.com/python/mypy/issues/7069
+
+
+# writing modes
+PAGE_PROGRESSION_DIRECTIONS = {
+    'horizontal': 'ltr',
+    'vertical': 'rtl',
+}
+IBOOK_SCROLL_AXIS = {
+    'horizontal': 'vertical',
+    'vertical': 'horizontal',
+}
+THEME_WRITING_MODES = {
+    'vertical': 'vertical-rl',
+    'horizontal': 'horizontal-tb',
+}
+
+DOCTYPE = '''<!DOCTYPE html>'''
+
+HTML_TAG = (
+    '<html xmlns="http://www.w3.org/1999/xhtml" '
+    'xmlns:epub="http://www.idpf.org/2007/ops">'
+)
+
+# https://www.w3.org/TR/REC-xml/#NT-Name
+_xml_name_start_char = (
+    ':|[A-Z]|_|[a-z]|[\u00C0-\u00D6]'
+    '|[\u00D8-\u00F6]|[\u00F8-\u02FF]|[\u0370-\u037D]'
+    '|[\u037F-\u1FFF]|[\u200C-\u200D]|[\u2070-\u218F]'
+    '|[\u2C00-\u2FEF]|[\u3001-\uD7FF]|[\uF900-\uFDCF]'
+    '|[\uFDF0-\uFFFD]|[\U00010000-\U000EFFFF]'
+)
+_xml_name_char = (
+    _xml_name_start_char + r'\-|\.' '|[0-9]|\u00B7|[\u0300-\u036F]|[\u203F-\u2040]'
+)
+_XML_NAME_PATTERN = re.compile(f'({_xml_name_start_char})({_xml_name_char})*')
+
+
+class Epub3Builder(_epub_base.EpubBuilder):
+    """
+    Builder that outputs epub3 files.
+
+    It creates the metainfo files content.opf, nav.xhtml, toc.ncx, mimetype,
+    and META-INF/container.xml. Afterwards, all necessary files are zipped to
+    an epub file.
+    """
+    name = 'epub'
+    epilog = __('The ePub file is in %(outdir)s.')
+
+    supported_remote_images = False
+    template_dir = path.join(package_dir, 'templates', 'epub3')
+    doctype = DOCTYPE
+    html_tag = HTML_TAG
+    use_meta_charset = True
+
+    # Finish by building the epub file
+    def handle_finish(self) -> None:
+        """Create the metainfo files and finally the epub."""
+        self.get_toc()
+        self.build_mimetype()
+        self.build_container()
+        self.build_content()
+        self.build_navigation_doc()
+        self.build_toc()
+        self.build_epub()
+
+    def content_metadata(self) -> dict[str, Any]:
+        """Create a dictionary with all metadata for the content.opf
+        file properly escaped.
+        """
+        writing_mode = self.config.epub_writing_mode
+
+        metadata = super().content_metadata()
+        metadata['description'] = html.escape(self.config.epub_description)
+        metadata['contributor'] = html.escape(self.config.epub_contributor)
+        metadata['page_progression_direction'] = PAGE_PROGRESSION_DIRECTIONS.get(writing_mode)
+        metadata['ibook_scroll_axis'] = IBOOK_SCROLL_AXIS.get(writing_mode)
+        metadata['date'] = html.escape(format_date("%Y-%m-%dT%H:%M:%SZ", language='en'))
+        metadata['version'] = html.escape(self.config.version)
+        metadata['epub_version'] = self.config.epub_version
+        return metadata
+
+    def prepare_writing(self, docnames: set[str]) -> None:
+        super().prepare_writing(docnames)
+
+        writing_mode = self.config.epub_writing_mode
+        self.globalcontext['theme_writing_mode'] = THEME_WRITING_MODES.get(writing_mode)
+        self.globalcontext['html_tag'] = self.html_tag
+        self.globalcontext['use_meta_charset'] = self.use_meta_charset
+        self.globalcontext['skip_ua_compatible'] = True
+
+    def build_navlist(self, navnodes: list[dict[str, Any]]) -> list[NavPoint]:
+        """Create the toc navigation structure.
+
+        This method is almost same as build_navpoints method in epub.py.
+        This is because the logical navigation structure of epub3 is not
+        different from one of epub2.
+
+        The difference from build_navpoints method is templates which are used
+        when generating navigation documents.
+        """
+        navstack: list[NavPoint] = []
+        navstack.append(NavPoint('', '', []))
+        level = 0
+        for node in navnodes:
+            if not node['text']:
+                continue
+            file = node['refuri'].split('#')[0]
+            if file in self.ignored_files:
+                continue
+            if node['level'] > self.config.epub_tocdepth:
+                continue
+
+            navpoint = NavPoint(node['text'], node['refuri'], [])
+            if node['level'] == level:
+                navstack.pop()
+                navstack[-1].children.append(navpoint)
+                navstack.append(navpoint)
+            elif node['level'] == level + 1:
+                level += 1
+                navstack[-1].children.append(navpoint)
+                navstack.append(navpoint)
+            elif node['level'] < level:
+                while node['level'] < len(navstack):
+                    navstack.pop()
+                level = node['level']
+                navstack[-1].children.append(navpoint)
+                navstack.append(navpoint)
+            else:
+                raise RuntimeError('Should never reach here. It might be a bug.')
+
+        return navstack[0].children
+
+    def navigation_doc_metadata(self, navlist: list[NavPoint]) -> dict[str, Any]:
+        """Create a dictionary with all metadata for the nav.xhtml file
+        properly escaped.
+        """
+        return {
+            'lang': html.escape(self.config.epub_language),
+            'toc_locale': html.escape(self.guide_titles['toc']),
+            'navlist': navlist
+        }
+
+    def build_navigation_doc(self) -> None:
+        """Write the metainfo file nav.xhtml."""
+        logger.info(__('writing nav.xhtml file...'))
+
+        if self.config.epub_tocscope == 'default':
+            doctree = self.env.get_and_resolve_doctree(
+                self.config.root_doc, self,
+                prune_toctrees=False, includehidden=False)
+            refnodes = self.get_refnodes(doctree, [])
+            self.toc_add_files(refnodes)
+        else:
+            # 'includehidden'
+            refnodes = self.refnodes
+        navlist = self.build_navlist(refnodes)
+        copy_asset_file(path.join(self.template_dir, 'nav.xhtml_t'), self.outdir,
+                        self.navigation_doc_metadata(navlist))
+
+        # Add nav.xhtml to epub file
+        if 'nav.xhtml' not in self.files:
+            self.files.append('nav.xhtml')
+
+
+def validate_config_values(app: Sphinx) -> None:
+    if app.builder.name != 'epub':
+        return
+
+    # <package> lang attribute, dc:language
+    if not app.config.epub_language:
+        logger.warning(__('conf value "epub_language" (or "language") '
+                          'should not be empty for EPUB3'))
+    # <package> unique-identifier attribute
+    if not _XML_NAME_PATTERN.match(app.config.epub_uid):
+        logger.warning(__('conf value "epub_uid" should be XML NAME for EPUB3'))
+    # dc:title
+    if not app.config.epub_title:
+        logger.warning(__('conf value "epub_title" (or "html_title") '
+                          'should not be empty for EPUB3'))
+    # dc:creator
+    if not app.config.epub_author:
+        logger.warning(__('conf value "epub_author" should not be empty for EPUB3'))
+    # dc:contributor
+    if not app.config.epub_contributor:
+        logger.warning(__('conf value "epub_contributor" should not be empty for EPUB3'))
+    # dc:description
+    if not app.config.epub_description:
+        logger.warning(__('conf value "epub_description" should not be empty for EPUB3'))
+    # dc:publisher
+    if not app.config.epub_publisher:
+        logger.warning(__('conf value "epub_publisher" should not be empty for EPUB3'))
+    # dc:rights
+    if not app.config.epub_copyright:
+        logger.warning(__('conf value "epub_copyright" (or "copyright")'
+                          'should not be empty for EPUB3'))
+    # dc:identifier
+    if not app.config.epub_identifier:
+        logger.warning(__('conf value "epub_identifier" should not be empty for EPUB3'))
+    # meta ibooks:version
+    if not app.config.version:
+        logger.warning(__('conf value "version" should not be empty for EPUB3'))
+
+
+def convert_epub_css_files(app: Sphinx, config: Config) -> None:
+    """This converts string styled epub_css_files to tuple styled one."""
+    epub_css_files: list[tuple[str, dict[str, Any]]] = []
+    for entry in config.epub_css_files:
+        if isinstance(entry, str):
+            epub_css_files.append((entry, {}))
+        else:
+            try:
+                filename, attrs = entry
+                epub_css_files.append((filename, attrs))
+            except Exception:
+                logger.warning(__('invalid css_file: %r, ignored'), entry)
+                continue
+
+    config.epub_css_files = epub_css_files  # type: ignore
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_builder(Epub3Builder)
+
+    # config values
+    app.add_config_value('epub_basename', lambda self: make_filename(self.project), False)
+    app.add_config_value('epub_version', 3.0, 'epub')  # experimental
+    app.add_config_value('epub_theme', 'epub', 'epub')
+    app.add_config_value('epub_theme_options', {}, 'epub')
+    app.add_config_value('epub_title', lambda self: self.project, 'epub')
+    app.add_config_value('epub_author', lambda self: self.author, 'epub')
+    app.add_config_value('epub_language', lambda self: self.language or 'en', 'epub')
+    app.add_config_value('epub_publisher', lambda self: self.author, 'epub')
+    app.add_config_value('epub_copyright', lambda self: self.copyright, 'epub')
+    app.add_config_value('epub_identifier', 'unknown', 'epub')
+    app.add_config_value('epub_scheme', 'unknown', 'epub')
+    app.add_config_value('epub_uid', 'unknown', 'env')
+    app.add_config_value('epub_cover', (), 'env')
+    app.add_config_value('epub_guide', (), 'env')
+    app.add_config_value('epub_pre_files', [], 'env')
+    app.add_config_value('epub_post_files', [], 'env')
+    app.add_config_value('epub_css_files', lambda config: config.html_css_files, 'epub')
+    app.add_config_value('epub_exclude_files', [], 'env')
+    app.add_config_value('epub_tocdepth', 3, 'env')
+    app.add_config_value('epub_tocdup', True, 'env')
+    app.add_config_value('epub_tocscope', 'default', 'env')
+    app.add_config_value('epub_fix_images', False, 'env')
+    app.add_config_value('epub_max_image_width', 0, 'env')
+    app.add_config_value('epub_show_urls', 'inline', 'epub')
+    app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'epub')
+    app.add_config_value('epub_description', 'unknown', 'epub')
+    app.add_config_value('epub_contributor', 'unknown', 'epub')
+    app.add_config_value('epub_writing_mode', 'horizontal', 'epub',
+                         ENUM('horizontal', 'vertical'))
+
+    # event handlers
+    app.connect('config-inited', convert_epub_css_files, priority=800)
+    app.connect('builder-inited', validate_config_values)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }