sphinx-mounts 0.1.0__tar.gz

sphinx_mounts-0.1.0/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.

sphinx_mounts-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,100 @@
+# 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/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+name = "sphinx-mounts"
+version = "0.1.0"
+description = "Mount external sources into a Sphinx build without copying or symlinking"
+authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
+maintainers = [
+  { name = "Marco Heinemann", email = "marco.heinemann@useblocks.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.12,<4"
+dependencies = ["sphinx>=7.4,<10", "ignore-python>=0.3.3"]
+keywords = ["sphinx", "documentation", "mount", "bazel", "monorepo"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+]
+
+[project.urls]
+Homepage = "https://sphinx-mounts.useblocks.com"
+Documentation = "https://sphinx-mounts.useblocks.com"
+Repository = "https://github.com/useblocks/sphinx-mounts"
+Issues = "https://github.com/useblocks/sphinx-mounts/issues"
+Changelog = "https://github.com/useblocks/sphinx-mounts/blob/main/docs/source/changelog.rst"
+
+[build-system]
+requires = ["flit_core >=3.4,<4"]
+build-backend = "flit_core.buildapi"
+
+[dependency-groups]
+dev = ["prek>=0.3.3"]
+testing = [
+  "pytest>=8.2.2",
+  "pytest-cov>=5.0.0",
+  "beautifulsoup4>=4.12",
+  # Exercised by the Markdown-mounting test; the extension supports any
+  # source suffix Sphinx knows about, so `.md` works whenever the host
+  # project loads `myst_parser`.
+  "myst-parser>=4.0.0",
+]
+docs = ["furo>=2024.5.6", "myst-parser>=4.0.0", "sphinx-design>=0.6.1"]
+ty = ["ty>=0.0.37"]
+ruff = ["ruff>=0.8.0"]
+
+[tool.ruff.lint]
+extend-select = [
+  "S",
+  "ARG",
+  "B",    # flake8-bugbear
+  "C4",   # flake8-comprehensions
+  "FURB", # refurb (modernising code)
+  "I",    # isort
+  "ICN",  # flake8-import-conventions
+  "ISC",  # flake8-implicit-str-concat
+  "N",    # pep8-naming
+  "PERF", # perflint (performance anti-patterns)
+  "PGH",  # pygrep-hooks
+  "PIE",  # flake8-pie
+  "PL",   # pylint
+  "PTH",  # flake8-use-pathlib
+  "RUF",  # Ruff-specific rules
+  "SIM",  # flake8-simplify
+  "SLF",  # private member access
+  "UP",   # pyupgrade
+  "T20",  # flake8-print
+]
+extend-ignore = [
+  "ISC001", # implicit-str-concat
+]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+force-sort-within-sections = true
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = [
+  "ARG001",  # unused-function-argument - fixtures
+  "ARG005",  # unused-lambda-argument - monkeypatches
+  "PLR2004", # magic-value-comparison - valuable for tests
+  "S101",    # assert - needed for tests
+  "S603",    # subprocess - bazel invocation in tests
+  "S607",    # partial-executable-path - bazel by name
+  "SLF001",  # private-member-access - inspecting Project._docname_to_path
+]
+"src/sphinx_mounts/mounter.py" = [
+  "SLF001", # private-member-access - we intentionally write to Project._docname_to_path
+]
+
+[tool.ty.src]
+# Only the package source is type-checked. Tests, docs, and build artefacts
+# are skipped — they are not part of the published API surface.
+include = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# ``bazel build`` materialises ``tests/example/bazel-*`` convenience symlinks
+# that point into the Bazel execroot. Without this filter, pytest happily
+# walks them and tries to collect ``test_*.py`` from ``bazel_tools`` external
+# repositories — none of which can import in our environment.
+norecursedirs = [
+  "bazel-*",
+  "*.egg-info",
+  ".git",
+  ".tox",
+  ".venv",
+  "build",
+  "dist",
+]
+markers = [
+  "bazel: tests that require a Bazel installation on PATH (deselect with '-m \"not bazel\"')",
+]

sphinx_mounts-0.1.0/src/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",
+]