sphinx-mounts 0.1.0__py3-none-any.whl

sphinx_mounts/__init__.py

@@ -0,0 +1,10 @@
+"""sphinx-mounts: mount external RST source trees into a Sphinx build."""
+
+__version__ = "0.1.0"
+
+from sphinx_mounts.extension import setup
+
+__all__ = [
+    "__version__",
+    "setup",
+]

sphinx_mounts/config.py

@@ -0,0 +1,513 @@
+"""Configuration models for sphinx-mounts.
+
+Validation is hand-rolled: a frozen :class:`dataclasses.dataclass` plus a
+``from_dict`` classmethod is enough for the small surface area of this
+extension, and avoids the runtime weight of a full schema library.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from pathlib import Path
+import tomllib
+from typing import Any
+
+
+class TomlConfigError(Exception):
+    """Raised when the TOML config file cannot be parsed or is malformed."""
+
+
+class MountConfigError(ValueError):
+    """Raised when a mount configuration entry is invalid."""
+
+
+@dataclass(frozen=True, slots=True)
+class MountConfig:
+    """One mounted external source tree, in one of two modes.
+
+    A mount is either a *directory* (``dir``) or an *explicit list of
+    files* (``files``). The two are mutually exclusive: exactly one
+    must be set. Both modes share the same ``mount_at`` semantics and
+    the same toctree-integration knobs.
+
+    Fields:
+        mount_at: The docname prefix at which the mount appears in the
+            host project. For example, ``_generated/api-foo`` makes a
+            mounted file ``index.rst`` available as docname
+            ``_generated/api-foo/index``. Stored without surrounding
+            slashes. ``None`` (the default) mounts the bundle at the
+            host project's root — a bundle file ``tutorial.rst``
+            becomes docname ``tutorial``.
+        dir: **Directory mode.** Absolute path (or path relative to
+            confdir) of an external directory holding source files.
+            Every file under it whose extension matches the project's
+            ``source_suffix`` is mounted; the relative-to-``dir`` path
+            (minus the suffix) becomes the docname tail. Mutually
+            exclusive with ``files``.
+        files: **File-list mode.** Tuple of absolute paths (or paths
+            relative to confdir) to individual source files. Each file's
+            *basename* (minus the matched ``source_suffix``) becomes the
+            docname tail under ``mount_at``. Subdirectories in the file
+            paths are ignored — the result is a flat namespace. May
+            contain a single file. Mutually exclusive with ``dir``.
+        include: Tuple of gitignore-style glob patterns evaluated
+            relative to ``dir``. If non-empty, *only* files matching
+            at least one pattern are walked; everything else is
+            filtered out. If empty (the default), no allowlist is
+            applied. Only meaningful in directory mode. Aligns with
+            sphinx-codelinks' ``source_discover.include``.
+        exclude: Tuple of gitignore-style glob patterns evaluated
+            relative to ``dir``. Matching files are skipped after
+            ``include`` allowlisting. Only meaningful in directory
+            mode (in file-list mode the list itself is the filter).
+            Aligns with sphinx-codelinks' ``source_discover.exclude``.
+        gitignore: Whether to honour ``.gitignore`` / ``.ignore``
+            files found *inside* the mounted tree during discovery.
+            Defaults to ``True``. Set to ``False`` when mounting a
+            sibling repository whose ``.gitignore`` excludes content
+            you nevertheless want to publish, or when the bundle is
+            served from a generated cache where ``.gitignore`` is not
+            meaningful. Aligns with sphinx-codelinks'
+            ``source_discover.gitignore``. Parent ``.gitignore``
+            files are never consulted regardless of this setting —
+            otherwise mounts inside host-gitignored directories like
+            ``bazel-bin/`` would silently produce zero files.
+        attach_to: Optional host docname whose toctree should receive the
+            mount entry. If ``None`` (default), no automatic toctree
+            wiring is performed and the host project is responsible for
+            referencing the mount.
+        toctree_index: 0-based index selecting *which* toctree inside the
+            ``attach_to`` document to extend, in document order. Defaults
+            to ``0`` (the first toctree). Ignored when ``attach_to`` is
+            ``None``. If the document contains no toctree, a new one is
+            created and the entry is appended; if the index exceeds the
+            number of toctrees present, the build fails loudly.
+        entry_doc: Mount-relative docname of the entry document to wire
+            into the host toctree. Defaults to ``"index"``. The resulting
+            docname is ``f"{mount_at}/{entry_doc}"`` — or just
+            ``entry_doc`` when ``mount_at`` is ``None``. This is the
+            *only* doc auto-attached; any other docs in the mount must
+            be reachable from the entry doc via its own toctree / refs.
+        strict_mount_at: When ``True``, fail the build if the host
+            project already has a directory at ``<srcdir>/<mount_at>/``.
+            Defaults to ``False`` — the existing per-docname collision
+            check is the only gate, which lets a mount slot under a
+            host-owned staging directory that holds non-source siblings
+            (assets, READMEs). Set to ``True`` to treat any host
+            directory at ``mount_at`` as a misconfiguration, catching
+            the mistake earlier than per-docname collisions would.
+            Incompatible with a root mount (``mount_at = None``), since
+            the host srcdir always exists; that combination is rejected
+            at config validation.
+    """
+
+    mount_at: str | None = None
+    dir: Path | None = None
+    files: tuple[Path, ...] | None = None
+    include: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = ()
+    gitignore: bool = True
+    attach_to: str | None = None
+    toctree_index: int = 0
+    entry_doc: str = "index"
+    strict_mount_at: bool = False
+
+    def __post_init__(self) -> None:
+        if self.mount_at is not None:
+            _validate_relative_docname("mount_at", self.mount_at)
+            normalized = self.mount_at.strip("/")
+            if normalized != self.mount_at:
+                object.__setattr__(self, "mount_at", normalized)
+
+        _validate_dir_or_files(self.dir, self.files)
+
+        # ``bool`` is a subclass of ``int``; here we accept only a true
+        # bool, not 1/0, to keep the config schema honest.
+        if not isinstance(self.gitignore, bool):
+            msg = f"gitignore must be a boolean; got {type(self.gitignore).__name__}."
+            raise MountConfigError(msg)
+
+        if self.attach_to is not None:
+            _validate_relative_docname("attach_to", self.attach_to)
+            normalized_attach = self.attach_to.strip("/")
+            if normalized_attach != self.attach_to:
+                object.__setattr__(self, "attach_to", normalized_attach)
+
+        # ``bool`` is a subclass of ``int`` — reject explicitly.
+        if isinstance(self.toctree_index, bool) or not isinstance(
+            self.toctree_index, int
+        ):
+            msg = (
+                f"toctree_index must be a non-negative integer; "
+                f"got {type(self.toctree_index).__name__}."
+            )
+            raise MountConfigError(msg)
+        if self.toctree_index < 0:
+            msg = f"toctree_index must be non-negative; got {self.toctree_index}."
+            raise MountConfigError(msg)
+
+        _validate_relative_docname("entry_doc", self.entry_doc)
+
+        if not isinstance(self.strict_mount_at, bool):
+            msg = (
+                f"strict_mount_at must be a boolean; "
+                f"got {type(self.strict_mount_at).__name__}."
+            )
+            raise MountConfigError(msg)
+        if self.strict_mount_at and self.mount_at is None:
+            msg = (
+                "strict_mount_at = true requires an explicit mount_at — "
+                "a root mount has no host-side directory whose existence "
+                "could meaningfully fail the check."
+            )
+            raise MountConfigError(msg)
+
+    @classmethod
+    def from_dict(cls, entry: Mapping[str, Any]) -> MountConfig:
+        """Construct a :class:`MountConfig` from a mapping (e.g. TOML table).
+
+        Unknown keys are rejected. Exactly one of ``dir`` / ``files``
+        must be present. ``mount_at`` is optional — when omitted, the
+        bundle mounts at the host project root. String paths are
+        coerced to :class:`pathlib.Path`; lists of patterns are
+        coerced to tuples.
+
+        :raises MountConfigError: If the mapping is malformed.
+        """
+        allowed = {f.name for f in fields(cls)}
+        unknown = set(entry) - allowed
+        if unknown:
+            msg = (
+                f"Unknown mount keys: {sorted(unknown)}. "
+                f"Allowed keys are {sorted(allowed)}."
+            )
+            raise MountConfigError(msg)
+        if "dir" not in entry and "files" not in entry:
+            msg = (
+                "Mount entry must declare either 'dir' (directory mode) "
+                "or 'files' (file-list mode)."
+            )
+            raise MountConfigError(msg)
+        if "dir" in entry and "files" in entry:
+            msg = "Mount entry must declare either 'dir' or 'files', not both."
+            raise MountConfigError(msg)
+
+        mount_dir = _coerce_path(entry["dir"]) if "dir" in entry else None
+        files = _coerce_files(entry["files"]) if "files" in entry else None
+        include = _coerce_pattern_list("include", entry.get("include", ()))
+        exclude = _coerce_pattern_list("exclude", entry.get("exclude", ()))
+        gitignore = entry.get("gitignore", True)
+
+        return cls(
+            mount_at=entry.get("mount_at"),
+            dir=mount_dir,
+            files=files,
+            include=include,
+            exclude=exclude,
+            gitignore=gitignore,
+            attach_to=entry.get("attach_to"),
+            toctree_index=entry.get("toctree_index", 0),
+            entry_doc=entry.get("entry_doc", "index"),
+            strict_mount_at=entry.get("strict_mount_at", False),
+        )
+
+
+def _coerce_path(raw: Any) -> Path:
+    """Accept Path or str; reject anything else."""
+    if isinstance(raw, Path):
+        return raw
+    if isinstance(raw, str):
+        return Path(raw)
+    msg = f"dir must be a string or Path; got {type(raw).__name__}."
+    raise MountConfigError(msg)
+
+
+def _coerce_files(raw: Any) -> tuple[Path, ...]:
+    """Accept a non-empty list/tuple of strings/Paths and return a tuple of Paths."""
+    if isinstance(raw, str) or not isinstance(raw, list | tuple):
+        msg = (
+            f"files must be a list or tuple of strings/Paths; got {type(raw).__name__}."
+        )
+        raise MountConfigError(msg)
+    if not raw:
+        msg = "files must contain at least one entry."
+        raise MountConfigError(msg)
+    collected: list[Path] = []
+    for item in raw:
+        if isinstance(item, Path):
+            collected.append(item)
+        elif isinstance(item, str):
+            collected.append(Path(item))
+        else:
+            msg = (
+                f"each entry in files must be a string or Path; "
+                f"got {type(item).__name__} for {item!r}."
+            )
+            raise MountConfigError(msg)
+    return tuple(collected)
+
+
+def _coerce_pattern_list(field_name: str, raw: Any) -> tuple[str, ...]:
+    """Accept a list/tuple of strings (possibly empty) and return a
+    tuple. Used for both ``include`` and ``exclude`` glob lists; the
+    ``field_name`` argument feeds the error messages."""
+    # ``str`` is technically a sequence but never what we want here.
+    if isinstance(raw, str) or not isinstance(raw, list | tuple):
+        msg = (
+            f"{field_name} must be a list or tuple of strings; "
+            f"got {type(raw).__name__}."
+        )
+        raise MountConfigError(msg)
+    for item in raw:
+        if not isinstance(item, str):
+            msg = (
+                f"{field_name} entries must be strings; "
+                f"got {type(item).__name__} for {item!r}."
+            )
+            raise MountConfigError(msg)
+    return tuple(raw)
+
+
+def _validate_dir_or_files(dir_: Path | None, files: tuple[Path, ...] | None) -> None:
+    """Enforce ``dir`` / ``files`` mutual exclusion and the shape of a
+    ``files`` list, raising :class:`MountConfigError` on violation.
+    Extracted from ``MountConfig.__post_init__`` to keep that method's
+    cyclomatic complexity inside ruff's threshold."""
+    if dir_ is None and files is None:
+        msg = (
+            "Mount must declare either `dir` (directory mode) or "
+            "`files` (file-list mode); got neither."
+        )
+        raise MountConfigError(msg)
+    if dir_ is not None and files is not None:
+        msg = (
+            "Mount must declare either `dir` (directory mode) or "
+            "`files` (file-list mode), not both."
+        )
+        raise MountConfigError(msg)
+    if files is None:
+        return
+    if not isinstance(files, tuple):
+        msg = f"files must be a tuple of paths; got {type(files).__name__}."
+        raise MountConfigError(msg)
+    if not files:
+        msg = "files must contain at least one entry."
+        raise MountConfigError(msg)
+    for f in files:
+        if not isinstance(f, Path):
+            msg = (
+                f"each entry in files must be a Path; got {type(f).__name__} for {f!r}."
+            )
+            raise MountConfigError(msg)
+
+
+def _validate_relative_docname(field_name: str, value: object) -> None:
+    """Validate a relative docname-shaped string field.
+
+    Used by :class:`MountConfig` for ``mount_at``, ``attach_to``, and
+    ``entry_doc``. Rejects non-strings, empty strings, leading slashes,
+    and ``..`` components. Does *not* normalize — that is the caller's
+    responsibility, since each field has a slightly different normalization
+    rule (mount_at strips slashes; entry_doc keeps its shape).
+    """
+    if not isinstance(value, str):
+        msg = f"{field_name} must be a string; got {type(value).__name__}."
+        raise MountConfigError(msg)
+    if not value:
+        msg = f"{field_name} must be a non-empty string."
+        raise MountConfigError(msg)
+    if value.startswith("/"):
+        msg = (
+            f"{field_name} must not start with '/'; got {value!r}. "
+            "Use a relative docname such as 'index' or '_generated/api-foo'."
+        )
+        raise MountConfigError(msg)
+    if ".." in Path(value).parts:
+        msg = f"{field_name} must not contain '..' components; got {value!r}."
+        raise MountConfigError(msg)
+
+
+def parse_mounts(raw: Any, confdir: Path) -> tuple[MountConfig, ...]:
+    """Validate and normalize the user-provided ``mounts`` config.
+
+    :param raw: Whatever the user set ``mounts`` to in ``conf.py``, or the
+        list extracted from the TOML config file. Expected to be a sequence
+        of mappings or :class:`MountConfig` instances.
+    :param confdir: Confdir path, used to resolve relative ``dir`` paths.
+    :return: Tuple of validated mount configs with absolute ``dir`` paths.
+    :raises TypeError: If ``raw`` is not a sequence of mappings.
+    :raises MountConfigError: If a mapping fails validation.
+    :raises FileNotFoundError: If a ``dir`` directory does not exist.
+    """
+    if raw is None:
+        return ()
+    if not isinstance(raw, list | tuple):
+        msg = f"`mounts` must be a list of mappings; got {type(raw).__name__}."
+        raise TypeError(msg)
+
+    resolved: list[MountConfig] = []
+    for index, entry in enumerate(raw):
+        mount = _entry_to_mount_config(entry, index)
+        resolved_dir = (
+            _resolve_dir(mount.dir, confdir, index) if mount.dir is not None else None
+        )
+        resolved_files = (
+            _resolve_files(mount.files, confdir, index)
+            if mount.files is not None
+            else None
+        )
+        resolved.append(
+            MountConfig(
+                mount_at=mount.mount_at,
+                dir=resolved_dir,
+                files=resolved_files,
+                include=mount.include,
+                exclude=mount.exclude,
+                gitignore=mount.gitignore,
+                attach_to=mount.attach_to,
+                toctree_index=mount.toctree_index,
+                entry_doc=mount.entry_doc,
+                strict_mount_at=mount.strict_mount_at,
+            )
+        )
+    return tuple(resolved)
+
+
+def _entry_to_mount_config(entry: Any, index: int) -> MountConfig:
+    if isinstance(entry, MountConfig):
+        return entry
+    if isinstance(entry, Mapping):
+        return MountConfig.from_dict(entry)
+    msg = (
+        f"`mounts[{index}]` must be a mapping or MountConfig; "
+        f"got {type(entry).__name__}."
+    )
+    raise TypeError(msg)
+
+
+def _resolve_dir(mount_dir: Path, confdir: Path, index: int) -> Path:
+    resolved = (
+        (confdir / mount_dir).resolve()
+        if not mount_dir.is_absolute()
+        else mount_dir.resolve()
+    )
+    if not resolved.is_dir():
+        msg = f"`mounts[{index}].dir` does not exist or is not a directory: {resolved}"
+        raise FileNotFoundError(msg)
+    return resolved
+
+
+def _resolve_files(
+    files: tuple[Path, ...], confdir: Path, index: int
+) -> tuple[Path, ...]:
+    file_list: list[Path] = []
+    for file_index, raw_file in enumerate(files):
+        f = (
+            (confdir / raw_file).resolve()
+            if not raw_file.is_absolute()
+            else raw_file.resolve()
+        )
+        if not f.is_file():
+            msg = (
+                f"`mounts[{index}].files[{file_index}]` does not exist or is "
+                f"not a file: {f}"
+            )
+            raise FileNotFoundError(msg)
+        file_list.append(f)
+    return tuple(file_list)
+
+
+def load_mounts_from_toml(toml_path: Path) -> list[dict[str, Any]] | None:
+    """Load the raw ``mounts`` list from a TOML configuration file.
+
+    The TOML file is expected to declare a top-level ``[[mounts]]`` array of
+    tables, one block per mount, with the same keys accepted by
+    :class:`MountConfig`:
+
+    .. code-block:: toml
+
+       [[mounts]]
+       dir = "/abs/path/to/bundle"
+       mount_at = "_generated/api-foo"
+
+       [[mounts]]
+       dir = "../other/docs"
+       mount_at = "guides/other"
+       include = ["**/*.rst"]       # optional allowlist
+       exclude = ["**/internal/**", "*.tmp"]
+       gitignore = false            # don't honour the sibling repo's .gitignore
+       attach_to = "index"          # extend a toctree in index.rst
+       toctree_index = 0            # which toctree (0-based)
+       entry_doc = "index"          # which file inside the mount
+
+    The TOML file is the *primary* config target so that non-Python tooling
+    (IDE extensions, language servers, build-system integrations) can read
+    the same configuration without evaluating ``conf.py``.
+
+    **Path anchoring.** Relative paths in ``dir`` and ``files`` are
+    resolved to absolute paths against the **directory containing
+    ``toml_path``**, not against the Sphinx ``confdir``. The TOML file
+    is self-describing: moving it as a unit keeps its relative paths
+    meaningful, and a TOML placed in a subdirectory of ``confdir`` does
+    not silently re-anchor. Absolute paths are left untouched.
+
+    :param toml_path: Absolute path to a TOML file. May or may not exist.
+    :return: The raw list of mount tables (each a ``dict``), or ``None`` if
+        ``toml_path`` does not exist or contains no top-level ``mounts``
+        array. Returning ``None`` is not an error — callers fall back to
+        the ``mounts`` value from ``conf.py``.
+    :raises TomlConfigError: If the file exists but is not valid TOML, or
+        if the top-level ``mounts`` key has the wrong shape.
+    """
+    if not toml_path.is_file():
+        return None
+    try:
+        with toml_path.open("rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        msg = f"sphinx-mounts: failed to parse TOML config {toml_path}: {e}"
+        raise TomlConfigError(msg) from e
+
+    raw_mounts = data.get("mounts")
+    if raw_mounts is None:
+        return None
+    if not isinstance(raw_mounts, list):
+        msg = (
+            f"sphinx-mounts: top-level `mounts` in {toml_path} must be an "
+            f"array of tables; got {type(raw_mounts).__name__}."
+        )
+        raise TomlConfigError(msg)
+    for index, entry in enumerate(raw_mounts):
+        if not isinstance(entry, dict):
+            msg = (
+                f"sphinx-mounts: `mounts[{index}]` in {toml_path} must be a "
+                f"table; got {type(entry).__name__}."
+            )
+            raise TomlConfigError(msg)
+
+    _anchor_toml_paths(raw_mounts, toml_path.parent)
+    return raw_mounts
+
+
+def _anchor_toml_paths(raw_mounts: list[dict[str, Any]], base_dir: Path) -> None:
+    """Make every relative ``dir`` / ``files`` path absolute against
+    ``base_dir``. Mutates ``raw_mounts`` in place. Non-string values and
+    already-absolute paths are left untouched; semantic validation of
+    types and shapes happens later in :meth:`MountConfig.from_dict`."""
+    for entry in raw_mounts:
+        if "dir" in entry:
+            entry["dir"] = _anchor_one_path(entry["dir"], base_dir)
+        if "files" in entry and isinstance(entry["files"], list):
+            entry["files"] = [_anchor_one_path(f, base_dir) for f in entry["files"]]
+
+
+def _anchor_one_path(value: Any, base_dir: Path) -> Any:
+    """Return ``value`` unchanged unless it is a relative path string,
+    in which case return its absolute form anchored to ``base_dir``."""
+    if not isinstance(value, str):
+        return value
+    p = Path(value)
+    if p.is_absolute():
+        return value
+    return str((base_dir / p).resolve())

sphinx_mounts/extension.py

@@ -0,0 +1,249 @@
+"""Sphinx extension entry point for sphinx-mounts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.config import Config
+from sphinx.errors import ExtensionError
+from sphinx.util import logging
+
+from sphinx_mounts import __version__
+from sphinx_mounts.config import MountConfig, load_mounts_from_toml, parse_mounts
+from sphinx_mounts.mounter import _MountAwareProject, install_mount_aware_project
+
+logger = logging.getLogger(__name__)
+
+_CACHED_KEY = "_sphinx_mounts_parsed"
+
+#: Default file name for the declarative TOML configuration. The file is
+#: resolved relative to Sphinx's ``confdir``. ``ubproject.toml`` is the
+#: convention shared with other useblocks tooling (sphinx-needs,
+#: sphinx-codelinks) so that a single declarative file can describe a
+#: project's documentation setup to *every* downstream consumer — Sphinx,
+#: IDE extensions, language servers, build-system integrations — without
+#: any of them having to execute ``conf.py``.
+DEFAULT_TOML_FILENAME = "ubproject.toml"
+
+
+def _on_load_toml(app: Sphinx, config: Config) -> None:
+    """Load mount entries from the TOML config file, if present.
+
+    Runs on ``config-inited`` *before* :func:`_on_config_inited`. If
+    ``mounts_from_toml`` resolves to an existing file, its top-level
+    ``[[mounts]]`` array replaces any value of ``mounts`` set in
+    ``conf.py``. If the file does not exist, ``config.mounts`` is left
+    untouched and any legacy conf.py-style value is used instead.
+    """
+    toml_setting = getattr(config, "mounts_from_toml", None)
+    if not toml_setting:
+        return
+    toml_path = (Path(app.confdir) / toml_setting).resolve()
+    raw = load_mounts_from_toml(toml_path)
+    if raw is None:
+        logger.debug(
+            "sphinx-mounts: no mounts loaded from TOML (path=%s, exists=%s).",
+            toml_path,
+            toml_path.is_file(),
+        )
+        return
+    config["mounts"] = raw
+    logger.info(
+        "sphinx-mounts: loaded %d mount(s) from %s",
+        len(raw),
+        toml_path,
+    )
+
+
+def _on_config_inited(app: Sphinx, config: Config) -> None:
+    """Validate the ``mounts`` config and cache the parsed result.
+
+    ``config-inited`` fires *before* ``app.project`` is constructed
+    (see :mod:`sphinx.application`), so the actual project replacement is
+    deferred to ``builder-inited``. We still parse here to surface
+    configuration errors as early as possible.
+    """
+    parsed = parse_mounts(getattr(config, "mounts", None), Path(app.confdir))
+    setattr(app, _CACHED_KEY, parsed)
+
+
+def _on_builder_inited(app: Sphinx) -> None:
+    """Replace ``app.project`` with a mount-aware project.
+
+    By the time ``builder-inited`` fires, ``app.project`` exists and the
+    build environment has been bound to it. We swap both so that the
+    subsequent ``env.find_files`` -> ``project.discover()`` call goes
+    through our subclass.
+    """
+    parsed: tuple[MountConfig, ...] = getattr(app, _CACHED_KEY, ())
+    if not parsed:
+        return
+
+    if not isinstance(app.project, _MountAwareProject):
+        app.project = install_mount_aware_project(app.project, parsed)
+        logger.info(
+            "sphinx-mounts: installed mount-aware project with %d mount(s)",
+            len(parsed),
+        )
+
+    if app.env is not None:
+        app.env.project = app.project
+
+
+def _on_doctree_read(app: Sphinx, doctree: nodes.document) -> None:
+    """Extend (or create) toctrees in host docs to reference mount entries.
+
+    For every mount whose ``attach_to`` equals the doc currently being
+    read, locate the configured toctree (by ``toctree_index``, 0-based)
+    and append ``{mount_at}/{entry_doc}`` to it. If the host doc contains
+    no toctree at all, a new one is added beneath the first section. If
+    ``toctree_index`` exceeds the number of toctrees in the doc, raise
+    :class:`ExtensionError` — silent misconfiguration would leave the
+    mount unreferenced.
+    """
+    parsed: tuple[MountConfig, ...] = getattr(app, _CACHED_KEY, ())
+    if not parsed:
+        return
+    docname = app.env.docname
+    targets = [m for m in parsed if m.attach_to == docname]
+    if not targets:
+        return
+
+    toctrees: list[addnodes.toctree] = list(doctree.findall(addnodes.toctree))
+
+    for mount in targets:
+        entry_docname = (
+            mount.entry_doc
+            if mount.mount_at is None
+            else f"{mount.mount_at}/{mount.entry_doc}"
+        )
+
+        if not toctrees:
+            new_node = _build_toctree_node(docname, entry_docname)
+            _attach_to_first_section(doctree, new_node)
+            toctrees.append(new_node)
+            logger.info(
+                "sphinx-mounts: added toctree to %r referencing %r",
+                docname,
+                entry_docname,
+            )
+            continue
+
+        if mount.toctree_index >= len(toctrees):
+            mount_label = "<root>" if mount.mount_at is None else repr(mount.mount_at)
+            msg = (
+                f"sphinx-mounts: mount {mount_label} requested "
+                f"toctree_index={mount.toctree_index} in host doc "
+                f"{docname!r}, but only {len(toctrees)} toctree(s) exist."
+            )
+            raise ExtensionError(msg)
+
+        target = toctrees[mount.toctree_index]
+        if entry_docname in target["includefiles"]:
+            # Already referenced (e.g. the host author wrote the entry by
+            # hand). Skip silently so attach_to is idempotent next to a
+            # static toctree.
+            continue
+        target["entries"].append((None, entry_docname))
+        target["includefiles"].append(entry_docname)
+        logger.info(
+            "sphinx-mounts: extended toctree #%d in %r with %r",
+            mount.toctree_index,
+            docname,
+            entry_docname,
+        )
+
+
+def _on_check_consistency(app: Sphinx, env: Any) -> None:
+    """Warn when ``attach_to`` targets a docname that does not exist."""
+    parsed: tuple[MountConfig, ...] = getattr(app, _CACHED_KEY, ())
+    if not parsed:
+        return
+    found = set(env.found_docs)
+    for mount in parsed:
+        if mount.attach_to is None:
+            continue
+        if mount.attach_to not in found:
+            mount_label = "<root>" if mount.mount_at is None else repr(mount.mount_at)
+            logger.warning(
+                "sphinx-mounts: mount %s has attach_to=%r, but that "
+                "docname does not exist in the project — nothing was "
+                "extended.",
+                mount_label,
+                mount.attach_to,
+            )
+
+
+def _build_toctree_node(parent: str, entry: str) -> addnodes.toctree:
+    """Construct a fresh ``toctree`` node with sane defaults."""
+    node = addnodes.toctree()
+    node["parent"] = parent
+    node["entries"] = [(None, entry)]
+    node["includefiles"] = [entry]
+    node["maxdepth"] = -1
+    node["caption"] = None
+    node["glob"] = False
+    node["hidden"] = False
+    node["includehidden"] = False
+    node["numbered"] = 0
+    node["titlesonly"] = False
+    return node
+
+
+def _attach_to_first_section(
+    doctree: nodes.document, toctree_node: addnodes.toctree
+) -> None:
+    """Append ``toctree_node`` at the **end** of the first top-level section.
+
+    Position matters: the host author owns the document's content and
+    ordering. Any prose, directives, or subsections they wrote come
+    first; the auto-injected mount entry is placed strictly below them
+    so the host doc remains self-contained and the injected references
+    are always at the bottom.
+
+    The append happens after *all* existing children of the section,
+    including nested subsections. Falls back to appending directly to
+    the document if it has no top-level section (e.g. a doc with only a
+    paragraph at the document root).
+    """
+    for child in doctree.children:
+        if isinstance(child, nodes.section):
+            # ``Element.append`` is ``self.children.append`` — i.e. end
+            # of the list, so the toctree ends up after every existing
+            # child of the section.
+            child.append(toctree_node)
+            return
+    doctree.append(toctree_node)
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    """Register the extension with Sphinx."""
+    app.add_config_value("mounts", default=[], rebuild="env", types=(list,))
+    app.add_config_value(
+        "mounts_from_toml",
+        default=DEFAULT_TOML_FILENAME,
+        rebuild="env",
+        types=(str, type(None)),
+    )
+    # Priority is "lower = earlier"; the TOML loader must run before the
+    # validator so that the TOML-derived list is what gets validated.
+    app.connect("config-inited", _on_load_toml, priority=400)
+    app.connect("config-inited", _on_config_inited, priority=500)
+    app.connect("builder-inited", _on_builder_inited)
+    # ``doctree-read`` priority 400 (< 500) places our toctree
+    # mutation *before* Sphinx's TocTreeCollector.process_doc, so the
+    # collector's pass sees the injected entries and includes them in
+    # ``env.included`` — without that, Sphinx's ``toc.not_included``
+    # consistency check would flag every mounted entry doc.
+    app.connect("doctree-read", _on_doctree_read, priority=400)
+    app.connect("env-check-consistency", _on_check_consistency)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_mounts/mounter.py

@@ -0,0 +1,297 @@
+"""Core mounting logic.
+
+This module intentionally writes to ``sphinx.project.Project._docname_to_path``
+and ``_path_to_docname``. Those attributes are private (single-underscore) in
+Sphinx; we depend on the following observable contract from
+``sphinx/project.py``:
+
+* ``Project.doc2path(docname, absolute=True)`` returns
+  ``self.srcdir / self._docname_to_path[docname]``.
+* ``pathlib.Path("/srcdir") / Path("/abs/external")`` returns
+  ``Path("/abs/external")`` because the right operand is absolute.
+
+So storing an absolute external path in ``_docname_to_path`` causes Sphinx
+to read from that external location transparently. This is the entire trick.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ignore import Walk, WalkBuilder
+from ignore.overrides import OverrideBuilder
+from sphinx.project import Project
+from sphinx.util import logging
+
+from sphinx_mounts.config import MountConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+logger = logging.getLogger(__name__)
+
+
+def _join_mount(mount_at: str | None, tail: str) -> str:
+    """Compose a docname from a mount prefix and a relative tail.
+
+    When ``mount_at`` is ``None`` the bundle is mounted at the host
+    project root, so the tail is returned unchanged. Otherwise the
+    prefix is joined with a single slash.
+    """
+    return tail if mount_at is None else f"{mount_at}/{tail}"
+
+
+class _MountAwareProject(Project):
+    """A :class:`sphinx.project.Project` that also discovers mounted trees.
+
+    After ``super().discover()`` populates docnames from the host ``srcdir``,
+    each configured mount is walked and its files are injected with
+    **absolute** filesystem paths in ``_docname_to_path``.
+    """
+
+    def __init__(
+        self,
+        srcdir: str | Path,
+        source_suffix: Iterable[str],
+        mounts: tuple[MountConfig, ...],
+    ) -> None:
+        super().__init__(srcdir, source_suffix)
+        self._mounts = mounts
+
+    def discover(
+        self,
+        exclude_paths: Iterable[str] = (),
+        include_paths: Iterable[str] = ("**",),
+    ) -> set[str]:
+        """Discover host srcdir docs plus all mounted external trees."""
+        docs = super().discover(exclude_paths, include_paths)
+        for mount in self._mounts:
+            _enforce_strict_mount_at(Path(self.srcdir), mount)
+            docs |= _attach_mount(self, mount)
+        return docs
+
+
+def _enforce_strict_mount_at(srcdir: Path, mount: MountConfig) -> None:
+    """Raise if ``mount.strict_mount_at`` is set and the host srcdir
+    already contains a directory at ``mount.mount_at``.
+
+    The check is intentionally a no-op when ``strict_mount_at`` is
+    false (the default per-docname collision detector remains the only
+    gate) or when ``mount_at`` is ``None`` (rejected at config time so
+    this branch is defensive). It does not fire for stray files at the
+    path — files are left to the per-docname check, which catches the
+    only case Sphinx actually cares about.
+    """
+    if not mount.strict_mount_at or mount.mount_at is None:
+        return
+    candidate = srcdir / mount.mount_at
+    if candidate.is_dir():
+        msg = (
+            f"sphinx-mounts: strict_mount_at violation: host project "
+            f"already has a directory at {candidate}, but mount "
+            f"{mount.mount_at!r} requires the path to be free. "
+            f"Rename or remove the host directory, or set "
+            f"strict_mount_at = false to fall back to per-docname "
+            f"collision checking."
+        )
+        raise ValueError(msg)
+
+
+def _attach_mount(project: Project, mount: MountConfig) -> set[str]:
+    """Inject ``mount`` into ``project`` — either a directory or a file list.
+
+    Directory mode (``mount.dir`` set): walk the directory and pick up
+    every file whose suffix matches one of the project's configured
+    source suffixes. The docname tail is the relative path under
+    ``dir``, minus the matched suffix.
+
+    File-list mode (``mount.files`` set): each file's *basename* (minus
+    the matched suffix) becomes the docname tail under ``mount.mount_at``.
+    Subdirectories in the file paths are ignored; the result is a flat
+    namespace under ``mount_at``.
+
+    :param project: The Sphinx :class:`Project` to inject into.
+    :param mount: Validated mount configuration.
+    :return: The set of docnames added by this mount.
+    :raises ValueError: If a constructed docname collides with an existing
+        docname already in the project (host shadowing or two mounts
+        producing the same docname), or — in file-list mode — if a file's
+        suffix is not registered with Sphinx.
+    """
+    if mount.dir is not None:
+        return _attach_mount_dir(project, mount, mount.dir)
+    if mount.files is not None:
+        return _attach_mount_files(project, mount, mount.files)
+    # MountConfig.__post_init__ guarantees exactly one of dir/files is
+    # set, so this branch is unreachable in practice.
+    mount_label = "<root>" if mount.mount_at is None else repr(mount.mount_at)
+    msg = f"sphinx-mounts: mount {mount_label} has neither dir nor files."
+    raise ValueError(msg)
+
+
+def _attach_mount_dir(
+    project: Project, mount: MountConfig, mount_dir: Path
+) -> set[str]:
+    """Walk ``mount_dir`` with the ``ignore-python`` walker (a Rust
+    binding to the same crate used by ``sphinx-codelinks`` and ubCode).
+
+    The walker honours ``.gitignore`` and ``.ignore`` files *inside*
+    the mounted tree (when ``mount.gitignore`` is true), and exposes
+    the mount's ``include`` / ``exclude`` lists as gitignore-style
+    allowlist / denylist overrides. Parent ``.gitignore`` files are
+    NOT consulted regardless of the setting — otherwise mounting a
+    directory whose parent gitignores it (the canonical
+    ``bazel-bin/...`` case) would silently produce zero files.
+    """
+    added: set[str] = set()
+    suffixes = tuple(project.source_suffix)
+
+    walker = _build_walker(
+        mount_dir,
+        include=mount.include,
+        exclude=mount.exclude,
+        gitignore=mount.gitignore,
+    )
+
+    # Collect first, then process sorted, so docname order is
+    # deterministic regardless of filesystem walk order.
+    matched: list[tuple[Path, str]] = []
+    for entry in walker:
+        p = entry.path()
+        if not p.is_file():
+            continue
+        suffix = _match_suffix(p.name, suffixes)
+        if suffix is None:
+            continue
+        matched.append((p, suffix))
+    matched.sort(key=lambda pair: pair[0].as_posix())
+
+    for abs_path, suffix in matched:
+        rel_path = abs_path.relative_to(mount_dir)
+        # Strip the matched suffix (which may be multi-dot like ".rst.txt").
+        docname_tail = rel_path.as_posix()[: -len(suffix)]
+        docname = _join_mount(mount.mount_at, docname_tail)
+        _register(project, docname, abs_path, mount.mount_at)
+        added.add(docname)
+    return added
+
+
+def _build_walker(
+    mount_dir: Path,
+    *,
+    include: tuple[str, ...],
+    exclude: tuple[str, ...],
+    gitignore: bool,
+) -> Walk:
+    """Configure a ``WalkBuilder`` for a single mount and return its
+    iterator.
+
+    Behaviour:
+
+    - When ``gitignore`` is ``True``: ``.gitignore`` and ``.ignore``
+      files *inside* the walked tree are honoured (the Rust ``ignore``
+      crate only activates ``.gitignore`` inside a git repository).
+      When ``False``: those files are treated as data, not filters —
+      useful for sibling repositories whose ``.gitignore`` excludes
+      content you still want to publish.
+    - Parent directories are NOT scanned for ignore files, regardless
+      of ``gitignore``. Mounts often live under paths that the host
+      workspace gitignores (e.g. ``bazel-bin/``); we do not want
+      those rules to silently strip the mount.
+    - The user's global git config and ``.git/info/exclude`` are NOT
+      consulted — keeps builds reproducible across machines.
+    - Hidden entries (dotfiles, ``.git/``) are skipped.
+    - ``include`` entries are added as positive overrides
+      (allowlist); ``exclude`` entries are added as negated overrides
+      (``!pattern``). Aligned with sphinx-codelinks'
+      ``source_discover`` semantics.
+    """
+    builder = WalkBuilder(mount_dir)
+    builder.ignore(gitignore)
+    builder.git_ignore(gitignore)
+    builder.parents(False)
+    builder.git_global(False)
+    builder.git_exclude(False)
+    builder.hidden(True)
+
+    if include or exclude:
+        ob = OverrideBuilder(mount_dir)
+        for pattern in include:
+            ob.add(pattern)
+        for pattern in exclude:
+            ob.add(f"!{pattern}")
+        builder.overrides(ob.build())
+
+    return builder.build()
+
+
+def _attach_mount_files(
+    project: Project, mount: MountConfig, files: Iterable[Path]
+) -> set[str]:
+    added: set[str] = set()
+    suffixes = tuple(project.source_suffix)
+
+    for abs_path in files:
+        suffix = _match_suffix(abs_path.name, suffixes)
+        if suffix is None:
+            msg = (
+                f"sphinx-mounts: file {abs_path} has no extension matching "
+                f"the project's source_suffix {list(suffixes)!r}. Add a "
+                f"parser extension (e.g. myst_parser for .md) or remove "
+                f"the file from the mount's `files` list."
+            )
+            raise ValueError(msg)
+        docname_tail = abs_path.name[: -len(suffix)]
+        docname = _join_mount(mount.mount_at, docname_tail)
+        _register(project, docname, abs_path, mount.mount_at)
+        added.add(docname)
+    return added
+
+
+def _register(
+    project: Project, docname: str, abs_path: Path, mount_at: str | None
+) -> None:
+    """Add a single (docname, abs_path) entry to the project, checking for
+    collisions with already-registered docnames."""
+    if docname in project.docnames:
+        existing = project._docname_to_path.get(docname)
+        mount_label = "<root>" if mount_at is None else repr(mount_at)
+        msg = (
+            f"sphinx-mounts: docname conflict for {docname!r}: "
+            f"mount {mount_label} would supply {abs_path}, "
+            f"but {existing} already provides it."
+        )
+        raise ValueError(msg)
+    project.docnames.add(docname)
+    project._docname_to_path[docname] = abs_path
+    project._path_to_docname[abs_path] = docname
+    logger.debug("sphinx-mounts: mounted %s -> %s", docname, abs_path)
+
+
+def _match_suffix(filename: str, suffixes: Iterable[str]) -> str | None:
+    """Return the matching source suffix for ``filename``, or None."""
+    for suffix in suffixes:
+        if filename.endswith(suffix):
+            return suffix
+    return None
+
+
+def install_mount_aware_project(
+    app_project: Project,
+    mounts: tuple[MountConfig, ...],
+) -> _MountAwareProject:
+    """Build a :class:`_MountAwareProject` carrying state from ``app_project``.
+
+    The original docname/path dictionaries are copied across so that any
+    state populated by Sphinx between construction and now is preserved.
+    """
+    new = _MountAwareProject(
+        app_project.srcdir,
+        app_project.source_suffix,
+        mounts,
+    )
+    new.docnames = set(app_project.docnames)
+    new._docname_to_path = dict(app_project._docname_to_path)
+    new._path_to_docname = dict(app_project._path_to_docname)
+    return new

sphinx_mounts-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: sphinx-mounts
+Version: 0.1.0
+Summary: Mount external sources into a Sphinx build without copying or symlinking
+Keywords: sphinx,documentation,mount,bazel,monorepo
+Author-email: team useblocks <info@useblocks.com>
+Maintainer-email: Marco Heinemann <marco.heinemann@useblocks.com>
+Requires-Python: >=3.12,<4
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+License-File: LICENSE
+Requires-Dist: sphinx>=7.4,<10
+Requires-Dist: ignore-python>=0.3.3
+Project-URL: Changelog, https://github.com/useblocks/sphinx-mounts/blob/main/docs/source/changelog.rst
+Project-URL: Documentation, https://sphinx-mounts.useblocks.com
+Project-URL: Homepage, https://sphinx-mounts.useblocks.com
+Project-URL: Issues, https://github.com/useblocks/sphinx-mounts/issues
+Project-URL: Repository, https://github.com/useblocks/sphinx-mounts
+
+# Sphinx Mounts
+
+Mount external source trees into a Sphinx build without copying or
+symlinking. Sources stay where they live — for example, a Bazel `bazel-bin/`
+output tree, a sibling repository, or a generated cache directory — and are
+made visible to Sphinx at a configured docname prefix. RST works out of the
+box; Markdown works as soon as `myst-parser` is loaded in the host project;
+any other format a Sphinx parser extension registers is picked up the same
+way.
+
+## Features
+
+- **No materialization**: sources are read directly from their original
+  location. No copy, no symlink, no staging step.
+- **Declarative TOML config**: the mount mapping lives in `ubproject.toml`
+  (or any TOML file you name via `mounts_from_toml`). `conf.py` only
+  references it.
+- **Language-agnostic & toolable**: because the config is static TOML, IDE
+  plugins, language servers, indexers, and build-system integrations
+  written in any language can read the same mount mapping that
+  `sphinx-build` reads — without having to evaluate `conf.py`.
+- **Toctree auto-wiring**: an optional `attach_to` per mount injects the
+  bundle's entry doc into a host toctree at build time, so the host stays
+  buildable when a mount is absent (a developer hasn't run the upstream
+  build, CI hasn't fetched the bundle).
+- **Self-contained bundles**: each mount is intended to be a
+  self-contained tree of `.rst` files with relative links only, so it can
+  be reused across host projects. A linter is on the roadmap; the
+  convention is not currently enforced.
+
+## Quick Start
+
+```bash
+pip install sphinx-mounts
+```
+
+Add to your `conf.py`:
+
+```python
+extensions = ["sphinx_mounts"]
+```
+
+Describe your mounts in `ubproject.toml` next to `conf.py`:
+
+```toml
+[[mounts]]
+dir = "/abs/path/to/bazel-bin/docs/api-foo"
+mount_at = "_generated/api-foo"
+```
+
+Reference mounted documents from your host project just like any other doc:
+
+```rst
+.. toctree::
+
+   _generated/api-foo/index
+```
+
+## Why TOML?
+
+A `conf.py` is executable Python — only a Python interpreter can read it
+correctly. A TOML file is static data, parseable by every common language.
+Putting the mount mapping in `ubproject.toml` means that any external tool
+(an IDE extension, a documentation indexer, a CI gate, a non-Python build
+system) can resolve cross-references without running Sphinx. The same file
+can also carry sections owned by sibling tools such as [Sphinx-Needs]
+(`[needs]`) and [sphinx-codelinks] (`[codelinks]`), keeping the project's
+documentation configuration in one place.
+
+If TOML isn't an option for your setup, the legacy `mounts = [...]` list in
+`conf.py` is still honored as a fallback — see the docs for details.
+
+## Related projects
+
+- [bazel-drives-sphinx] — a heavier take on Bazel-driven Sphinx
+  documentation: Bazel rules declare every RST file (and `needs.json`
+  artifact) as a label, and generated per-project targets invoke
+  `sphinx-build` on the assembled tree. `sphinx-mounts` is the lightweight
+  alternative — Bazel drops generated files under `bazel-bin/`, the
+  extension mounts that directory, and Sphinx reads in place. Pick the
+  former for fine-grained multi-project rule collection and tag-driven
+  variants; pick the latter when "Bazel build, then Sphinx" is enough.
+  See `docs/source/bazel.rst` for a side-by-side comparison.
+
+## Documentation
+
+See `docs/source/` for the full configuration reference and the Bazel
+integration walkthrough. The "Related projects" section in
+`docs/source/index.rst` lists sibling tools ([Sphinx-Needs],
+[sphinx-codelinks], [ubCode], [bazel-drives-sphinx]) that share the
+`ubproject.toml` convention.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+[Sphinx-Needs]: https://sphinx-needs.readthedocs.io/
+[sphinx-codelinks]: https://github.com/useblocks/sphinx-codelinks
+[ubCode]: https://ubcode.useblocks.com/
+[bazel-drives-sphinx]: https://github.com/useblocks/bazel-drives-sphinx
+

sphinx_mounts-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sphinx_mounts/__init__.py,sha256=rF9MDLsXakhe1fiW7bTeeMkGAToTi7ViAG5JGLjU_3o,187
+sphinx_mounts/config.py,sha256=tjTUKMEn21RIY37eFSFcvKzcBvrHuvocRNSQEZ0kBik,21743
+sphinx_mounts/extension.py,sha256=SUt65SBkt6wdUU5N2Q7p81N68gSSJTi6gvxO7Kv2qmI,9491
+sphinx_mounts/mounter.py,sha256=oncPo5eQ6k5Md5jPrENOurmjbvPeyq703C2Xb0dQrIE,11309
+sphinx_mounts-0.1.0.dist-info/licenses/LICENSE,sha256=72nRnAqdEM2NFi7I1q4xUAeEx-3bs7q7kdd_RnZI9L0,1066
+sphinx_mounts-0.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+sphinx_mounts-0.1.0.dist-info/METADATA,sha256=HSGlWQtjBtsn8CLqRFlBeSmVMmxrPS3qJfekq_k62fc,5406
+sphinx_mounts-0.1.0.dist-info/RECORD,,

sphinx_mounts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sphinx_mounts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 useblocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.