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

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

@@ -0,0 +1,192 @@
+"""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/venv0/Lib/site-packages/sphinx/testing/__init__.py

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

@@ -0,0 +1,97 @@
+"""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/venv0/Lib/site-packages/sphinx/testing/fixtures.py

@@ -0,0 +1,250 @@
+"""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)