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

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

@@ -1,192 +0,0 @@
-"""Setuptools/distutils commands to assist the building of sphinx documentation.
-
-:author: Sebastian Wiesner <basti.wiesner@gmx.net>
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-import warnings
-from io import StringIO
-from typing import Any
-
-from sphinx.application import Sphinx
-from sphinx.cmd.build import handle_exception
-from sphinx.deprecation import RemovedInSphinx70Warning
-from sphinx.util.console import color_terminal, nocolor
-from sphinx.util.docutils import docutils_namespace, patch_docutils
-from sphinx.util.osutil import abspath
-
-try:
-    from setuptools import Command
-    from setuptools.errors import ExecError
-except ImportError:
-    from distutils.cmd import Command
-    from distutils.errors import DistutilsExecError as ExecError
-
-
-class BuildDoc(Command):
-    """
-    Distutils command to build Sphinx documentation.
-
-    The Sphinx build can then be triggered from distutils, and some Sphinx
-    options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's
-    own configuration file.
-
-    For instance, from `setup.py`::
-
-       # this is only necessary when not using setuptools/distribute
-       from sphinx.setup_command import BuildDoc
-       cmdclass = {'build_sphinx': BuildDoc}
-
-       name = 'My project'
-       version = '1.2'
-       release = '1.2.0'
-       setup(
-           name=name,
-           author='Bernard Montgomery',
-           version=release,
-           cmdclass=cmdclass,
-           # these are optional and override conf.py settings
-           command_options={
-               'build_sphinx': {
-                   'project': ('setup.py', name),
-                   'version': ('setup.py', version),
-                   'release': ('setup.py', release)}},
-       )
-
-    Or add this section in ``setup.cfg``::
-
-       [build_sphinx]
-       project = 'My project'
-       version = 1.2
-       release = 1.2.0
-    """
-
-    description = 'Build Sphinx documentation'
-    user_options = [
-        ('fresh-env', 'E', 'discard saved environment'),
-        ('all-files', 'a', 'build all files'),
-        ('source-dir=', 's', 'Source directory'),
-        ('build-dir=', None, 'Build directory'),
-        ('config-dir=', 'c', 'Location of the configuration directory'),
-        ('builder=', 'b', 'The builder (or builders) to use. Can be a comma- '
-         'or space-separated list. Defaults to "html"'),
-        ('warning-is-error', 'W', 'Turn warning into errors'),
-        ('project=', None, 'The documented project\'s name'),
-        ('version=', None, 'The short X.Y version'),
-        ('release=', None, 'The full version, including alpha/beta/rc tags'),
-        ('today=', None, 'How to format the current date, used as the '
-         'replacement for |today|'),
-        ('link-index', 'i', 'Link index.html to the master doc'),
-        ('copyright', None, 'The copyright string'),
-        ('pdb', None, 'Start pdb on exception'),
-        ('verbosity', 'v', 'increase verbosity (can be repeated)'),
-        ('nitpicky', 'n', 'nit-picky mode, warn about all missing references'),
-        ('keep-going', None, 'With -W, keep going when getting warnings'),
-    ]
-    boolean_options = ['fresh-env', 'all-files', 'warning-is-error',
-                       'link-index', 'nitpicky']
-
-    def initialize_options(self) -> None:
-        self.fresh_env = self.all_files = False
-        self.pdb = False
-        self.source_dir: str | None = None
-        self.build_dir: str | None = None
-        self.builder = 'html'
-        self.warning_is_error = False
-        self.project = ''
-        self.version = ''
-        self.release = ''
-        self.today = ''
-        self.config_dir: str | None = None
-        self.link_index = False
-        self.copyright = ''
-        # Link verbosity to distutils' (which uses 1 by default).
-        self.verbosity = self.distribution.verbose - 1
-        self.traceback = False
-        self.nitpicky = False
-        self.keep_going = False
-
-    def _guess_source_dir(self) -> str:
-        for guess in ('doc', 'docs'):
-            if not os.path.isdir(guess):
-                continue
-            for root, _dirnames, filenames in os.walk(guess):
-                if 'conf.py' in filenames:
-                    return root
-        return os.curdir
-
-    def finalize_options(self) -> None:
-        self.ensure_string_list('builder')
-
-        if self.source_dir is None:
-            self.source_dir = self._guess_source_dir()
-            self.announce('Using source directory %s' % self.source_dir)
-
-        self.ensure_dirname('source_dir')
-
-        if self.config_dir is None:
-            self.config_dir = self.source_dir
-
-        if self.build_dir is None:
-            build = self.get_finalized_command('build')
-            self.build_dir = os.path.join(abspath(build.build_base), 'sphinx')
-
-        self.doctree_dir = os.path.join(self.build_dir, 'doctrees')
-
-        self.builder_target_dirs = [
-            (builder, os.path.join(self.build_dir, builder))
-            for builder in self.builder]
-
-    def run(self) -> None:
-        warnings.warn('setup.py build_sphinx is deprecated.',
-                      RemovedInSphinx70Warning, stacklevel=2)
-
-        if not color_terminal():
-            nocolor()
-        if not self.verbose:
-            status_stream = StringIO()
-        else:
-            status_stream = sys.stdout  # type: ignore
-        confoverrides: dict[str, Any] = {}
-        if self.project:
-            confoverrides['project'] = self.project
-        if self.version:
-            confoverrides['version'] = self.version
-        if self.release:
-            confoverrides['release'] = self.release
-        if self.today:
-            confoverrides['today'] = self.today
-        if self.copyright:
-            confoverrides['copyright'] = self.copyright
-        if self.nitpicky:
-            confoverrides['nitpicky'] = self.nitpicky
-
-        for builder, builder_target_dir in self.builder_target_dirs:
-            app = None
-
-            try:
-                confdir = self.config_dir or self.source_dir
-                with patch_docutils(confdir), docutils_namespace():
-                    app = Sphinx(self.source_dir, self.config_dir,
-                                 builder_target_dir, self.doctree_dir,
-                                 builder, confoverrides, status_stream,
-                                 freshenv=self.fresh_env,
-                                 warningiserror=self.warning_is_error,
-                                 verbosity=self.verbosity, keep_going=self.keep_going)
-                    app.build(force_all=self.all_files)
-                    if app.statuscode:
-                        raise ExecError('caused by %s builder.' % app.builder.name)
-            except Exception as exc:
-                handle_exception(app, self, exc, sys.stderr)
-                if not self.pdb:
-                    raise SystemExit(1) from exc
-
-            if not self.link_index:
-                continue
-
-            src = app.config.root_doc + app.builder.out_suffix  # type: ignore
-            dst = app.builder.get_outfilename('index')  # type: ignore
-            os.symlink(src, dst)

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

@@ -1,7 +0,0 @@
-"""Sphinx test utilities
-
-You can require sphinx.testing pytest fixtures in a test module or a conftest
-file like this:
-
-   pytest_plugins = 'sphinx.testing.fixtures'
-"""

py2docfx/venv/template/Lib/site-packages/sphinx/testing/comparer.py

@@ -1,97 +0,0 @@
-"""Sphinx test comparer for pytest"""
-from __future__ import annotations
-
-import difflib
-import pathlib
-from typing import Any
-
-
-class PathComparer:
-    """
-    OS-independent path comparison.
-
-    Windows path sep and posix path sep:
-
-    >>> '\\to\\index' == PathComparer('/to/index')
-    True
-    >>> '\\to\\index' == PathComparer('/to/index2')
-    False
-
-    Windows path with drive letters
-
-    >>> 'C:\\to\\index' == PathComparer('/to/index')
-    True
-    >>> 'C:\\to\\index' == PathComparer('C:/to/index')
-    True
-    >>> 'C:\\to\\index' == PathComparer('D:/to/index')
-    False
-    """
-    def __init__(self, path: str | pathlib.Path):
-        """
-        :param str path: path string, it will be cast as pathlib.Path.
-        """
-        self.path = pathlib.Path(path)
-
-    def __str__(self) -> str:
-        return self.path.as_posix()
-
-    def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}: '{self}'>"
-
-    def __eq__(self, other: str | pathlib.Path) -> bool:  # type: ignore
-        return not bool(self.ldiff(other))
-
-    def diff(self, other: str | pathlib.Path) -> list[str]:
-        """compare self and other.
-
-        When different is not exist, return empty list.
-
-        >>> PathComparer('/to/index').diff('C:\\to\\index')
-        []
-
-        When different is exist, return unified diff style list as:
-
-        >>> PathComparer('/to/index').diff('C:\\to\\index2')
-        [
-           '- C:/to/index'
-           '+ C:/to/index2'
-           '?            +'
-        ]
-        """
-        return self.ldiff(other)
-
-    def ldiff(self, other: str | pathlib.Path) -> list[str]:
-        return self._diff(
-            self.path,
-            pathlib.Path(other),
-        )
-
-    def rdiff(self, other: str | pathlib.Path) -> list[str]:
-        return self._diff(
-            pathlib.Path(other),
-            self.path,
-        )
-
-    def _diff(self, lhs: pathlib.Path, rhs: pathlib.Path) -> list[str]:
-        if lhs == rhs:
-            return []
-
-        if lhs.drive or rhs.drive:
-            # If either has a drive letter compare by absolute path
-            s_path, o_path = lhs.absolute().as_posix(), rhs.absolute().as_posix()
-        else:
-            s_path, o_path = lhs.as_posix(), rhs.as_posix()
-
-        if s_path == o_path:
-            return []
-
-        return [line.strip() for line in difflib.Differ().compare([s_path], [o_path])]
-
-
-def pytest_assertrepr_compare(op: str, left: Any, right: Any) -> list[str]:
-    if isinstance(left, PathComparer) and op == "==":
-        return ['Comparing path:'] + left.ldiff(right)
-    elif isinstance(right, PathComparer) and op == "==":
-        return ['Comparing path:'] + right.rdiff(left)
-    else:
-        return []

py2docfx/venv/template/Lib/site-packages/sphinx/testing/fixtures.py

@@ -1,250 +0,0 @@
-"""Sphinx test fixtures for pytest"""
-
-from __future__ import annotations
-
-import subprocess
-import sys
-from collections import namedtuple
-from io import StringIO
-from typing import Any, Callable, Generator
-
-import pytest
-
-from sphinx.testing import util
-from sphinx.testing.util import SphinxTestApp, SphinxTestAppWrapperForSkipBuilding
-
-DEFAULT_ENABLED_MARKERS = [
-    (
-        'sphinx(builder, testroot=None, freshenv=False, confoverrides=None, tags=None,'
-        ' docutilsconf=None, parallel=0): arguments to initialize the sphinx test application.'
-    ),
-    'test_params(shared_result=...): test parameters.',
-]
-
-
-def pytest_configure(config):
-    """Register custom markers"""
-    for marker in DEFAULT_ENABLED_MARKERS:
-        config.addinivalue_line('markers', marker)
-
-
-@pytest.fixture(scope='session')
-def rootdir() -> str | None:
-    return None
-
-
-class SharedResult:
-    cache: dict[str, dict[str, str]] = {}
-
-    def store(self, key: str, app_: SphinxTestApp) -> Any:
-        if key in self.cache:
-            return
-        data = {
-            'status': app_._status.getvalue(),
-            'warning': app_._warning.getvalue(),
-        }
-        self.cache[key] = data
-
-    def restore(self, key: str) -> dict[str, StringIO]:
-        if key not in self.cache:
-            return {}
-        data = self.cache[key]
-        return {
-            'status': StringIO(data['status']),
-            'warning': StringIO(data['warning']),
-        }
-
-
-@pytest.fixture
-def app_params(request: Any, test_params: dict, shared_result: SharedResult,
-               sphinx_test_tempdir: str, rootdir: str) -> tuple[dict, dict]:
-    """
-    Parameters that are specified by 'pytest.mark.sphinx' for
-    sphinx.application.Sphinx initialization
-    """
-
-    # ##### process pytest.mark.sphinx
-
-    pargs = {}
-    kwargs: dict[str, Any] = {}
-
-    # to avoid stacking positional args
-    for info in reversed(list(request.node.iter_markers("sphinx"))):
-        for i, a in enumerate(info.args):
-            pargs[i] = a
-        kwargs.update(info.kwargs)
-
-    args = [pargs[i] for i in sorted(pargs.keys())]
-
-    # ##### process pytest.mark.test_params
-    if test_params['shared_result']:
-        if 'srcdir' in kwargs:
-            raise pytest.Exception('You can not specify shared_result and '
-                                   'srcdir in same time.')
-        kwargs['srcdir'] = test_params['shared_result']
-        restore = shared_result.restore(test_params['shared_result'])
-        kwargs.update(restore)
-
-    # ##### prepare Application params
-
-    testroot = kwargs.pop('testroot', 'root')
-    kwargs['srcdir'] = srcdir = sphinx_test_tempdir / kwargs.get('srcdir', testroot)
-
-    # special support for sphinx/tests
-    if rootdir and not srcdir.exists():
-        testroot_path = rootdir / ('test-' + testroot)
-        testroot_path.copytree(srcdir)
-
-    return namedtuple('app_params', 'args,kwargs')(args, kwargs)  # type: ignore
-
-
-@pytest.fixture
-def test_params(request: Any) -> dict:
-    """
-    Test parameters that are specified by 'pytest.mark.test_params'
-
-    :param Union[str] shared_result:
-       If the value is provided, app._status and app._warning objects will be
-       shared in the parametrized test functions and/or test functions that
-       have same 'shared_result' value.
-       **NOTE**: You can not specify both shared_result and srcdir.
-    """
-    env = request.node.get_closest_marker('test_params')
-    kwargs = env.kwargs if env else {}
-    result = {
-        'shared_result': None,
-    }
-    result.update(kwargs)
-
-    if (result['shared_result'] and not isinstance(result['shared_result'], str)):
-        raise pytest.Exception('You can only provide a string type of value '
-                               'for "shared_result" ')
-    return result
-
-
-@pytest.fixture(scope='function')
-def app(test_params: dict, app_params: tuple[dict, dict], make_app: Callable,
-        shared_result: SharedResult) -> Generator[SphinxTestApp, None, None]:
-    """
-    Provides the 'sphinx.application.Sphinx' object
-    """
-    args, kwargs = app_params
-    app_ = make_app(*args, **kwargs)
-    yield app_
-
-    print('# testroot:', kwargs.get('testroot', 'root'))
-    print('# builder:', app_.builder.name)
-    print('# srcdir:', app_.srcdir)
-    print('# outdir:', app_.outdir)
-    print('# status:', '\n' + app_._status.getvalue())
-    print('# warning:', '\n' + app_._warning.getvalue())
-
-    if test_params['shared_result']:
-        shared_result.store(test_params['shared_result'], app_)
-
-
-@pytest.fixture(scope='function')
-def status(app: SphinxTestApp) -> StringIO:
-    """
-    Back-compatibility for testing with previous @with_app decorator
-    """
-    return app._status
-
-
-@pytest.fixture(scope='function')
-def warning(app: SphinxTestApp) -> StringIO:
-    """
-    Back-compatibility for testing with previous @with_app decorator
-    """
-    return app._warning
-
-
-@pytest.fixture()
-def make_app(test_params: dict, monkeypatch: Any) -> Generator[Callable, None, None]:
-    """
-    Provides make_app function to initialize SphinxTestApp instance.
-    if you want to initialize 'app' in your test function. please use this
-    instead of using SphinxTestApp class directory.
-    """
-    monkeypatch.setattr('sphinx.application.abspath', lambda x: x)
-
-    apps = []
-    syspath = sys.path[:]
-
-    def make(*args, **kwargs):
-        status, warning = StringIO(), StringIO()
-        kwargs.setdefault('status', status)
-        kwargs.setdefault('warning', warning)
-        app_: Any = SphinxTestApp(*args, **kwargs)
-        apps.append(app_)
-        if test_params['shared_result']:
-            app_ = SphinxTestAppWrapperForSkipBuilding(app_)
-        return app_
-    yield make
-
-    sys.path[:] = syspath
-    for app_ in reversed(apps):  # clean up applications from the new ones
-        app_.cleanup()
-
-
-@pytest.fixture
-def shared_result() -> SharedResult:
-    return SharedResult()
-
-
-@pytest.fixture(scope='module', autouse=True)
-def _shared_result_cache() -> None:
-    SharedResult.cache.clear()
-
-
-@pytest.fixture
-def if_graphviz_found(app: SphinxTestApp) -> None:
-    """
-    The test will be skipped when using 'if_graphviz_found' fixture and graphviz
-    dot command is not found.
-    """
-    graphviz_dot = getattr(app.config, 'graphviz_dot', '')
-    try:
-        if graphviz_dot:
-            subprocess.run([graphviz_dot, '-V'], capture_output=True)  # show version
-            return
-    except OSError:  # No such file or directory
-        pass
-
-    pytest.skip('graphviz "dot" is not available')
-
-
-@pytest.fixture(scope='session')
-def sphinx_test_tempdir(tmpdir_factory: Any) -> util.path:
-    """
-    Temporary directory wrapped with `path` class.
-    """
-    tmpdir = tmpdir_factory.getbasetemp()
-    return util.path(tmpdir).abspath()
-
-
-@pytest.fixture
-def tempdir(tmpdir: str) -> util.path:
-    """
-    Temporary directory wrapped with `path` class.
-    This fixture is for back-compatibility with old test implementation.
-    """
-    return util.path(tmpdir)
-
-
-@pytest.fixture
-def rollback_sysmodules():
-    """
-    Rollback sys.modules to its value before testing to unload modules
-    during tests.
-
-    For example, used in test_ext_autosummary.py to permit unloading the
-    target module to clear its cache.
-    """
-    try:
-        sysmodules = list(sys.modules)
-        yield
-    finally:
-        for modname in list(sys.modules):
-            if modname not in sysmodules:
-                sys.modules.pop(modname)