{"id":50699561,"url":"https://github.com/useblocks/sphinx-mounts","last_synced_at":"2026-06-09T08:32:44.631Z","repository":{"id":359582026,"uuid":"1243651994","full_name":"useblocks/sphinx-mounts","owner":"useblocks","description":"Mount external sources into a Sphinx build without copying or symlinking","archived":false,"fork":false,"pushed_at":"2026-06-07T10:49:36.000Z","size":314,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T12:21:37.215Z","etag":null,"topics":["bazel","docs-as-code","ide","sphinx","ubcode"],"latest_commit_sha":null,"homepage":"http://sphinx-mounts.useblocks.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/useblocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-19T14:35:26.000Z","updated_at":"2026-05-22T13:56:04.000Z","dependencies_parsed_at":"2026-05-22T19:04:17.341Z","dependency_job_id":null,"html_url":"https://github.com/useblocks/sphinx-mounts","commit_stats":null,"previous_names":["useblocks/sphinx-mounts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/useblocks/sphinx-mounts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/useblocks%2Fsphinx-mounts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/useblocks%2Fsphinx-mounts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/useblocks%2Fsphinx-mounts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/useblocks%2Fsphinx-mounts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/useblocks","download_url":"https://codeload.github.com/useblocks/sphinx-mounts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/useblocks%2Fsphinx-mounts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34098932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bazel","docs-as-code","ide","sphinx","ubcode"],"created_at":"2026-06-09T08:32:44.137Z","updated_at":"2026-06-09T08:32:44.618Z","avatar_url":"https://github.com/useblocks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sphinx Mounts\n\nMount external source trees into a Sphinx build without copying or\nsymlinking. Sources stay where they live — for example, a Bazel `bazel-bin/`\noutput tree, a sibling repository, or a generated cache directory — and are\nmade visible to Sphinx at a configured docname prefix. RST works out of the\nbox; Markdown works as soon as `myst-parser` is loaded in the host project;\nany other format a Sphinx parser extension registers is picked up the same\nway.\n\n## Features\n\n- **No materialization**: sources are read directly from their original\n  location. No copy, no symlink, no staging step.\n- **Declarative TOML config**: the mount mapping lives in `ubproject.toml`\n  (or any TOML file you name via `mounts_from_toml`). `conf.py` only\n  references it.\n- **Language-agnostic \u0026 toolable**: because the config is static TOML, IDE\n  plugins, language servers, indexers, and build-system integrations\n  written in any language can read the same mount mapping that\n  `sphinx-build` reads — without having to evaluate `conf.py`.\n- **Toctree auto-wiring**: an optional `attach_to` per mount injects the\n  bundle's entry doc into a host toctree at build time, so the host stays\n  buildable when a mount is absent (a developer hasn't run the upstream\n  build, CI hasn't fetched the bundle).\n- **Self-contained bundles**: each mount is intended to be a\n  self-contained tree of `.rst` files with relative links only, so it can\n  be reused across host projects. A linter is on the roadmap; the\n  convention is not currently enforced.\n\n## Quick Start\n\n```bash\npip install sphinx-mounts\n```\n\nAdd to your `conf.py`:\n\n```python\nextensions = [\"sphinx_mounts\"]\n```\n\nDescribe your mounts in `ubproject.toml` next to `conf.py`:\n\n```toml\n[[mounts]]\ndir = \"/abs/path/to/bazel-bin/docs/api-foo\"\nmount_at = \"_generated/api-foo\"\n```\n\nReference mounted documents from your host project just like any other doc:\n\n```rst\n.. toctree::\n\n   _generated/api-foo/index\n```\n\n## Why TOML?\n\nA `conf.py` is executable Python — only a Python interpreter can read it\ncorrectly. A TOML file is static data, parseable by every common language.\nPutting the mount mapping in `ubproject.toml` means that any external tool\n(an IDE extension, a documentation indexer, a CI gate, a non-Python build\nsystem) can resolve cross-references without running Sphinx. The same file\ncan also carry sections owned by sibling tools such as [Sphinx-Needs]\n(`[needs]`) and [sphinx-codelinks] (`[codelinks]`), keeping the project's\ndocumentation configuration in one place.\n\nIf TOML isn't an option for your setup, the legacy `mounts = [...]` list in\n`conf.py` is still honored as a fallback — see the docs for details.\n\n## Related projects\n\n- [bazel-drives-sphinx] — a heavier take on Bazel-driven Sphinx\n  documentation: Bazel rules declare every RST file (and `needs.json`\n  artifact) as a label, and generated per-project targets invoke\n  `sphinx-build` on the assembled tree. `sphinx-mounts` is the lightweight\n  alternative — Bazel drops generated files under `bazel-bin/`, the\n  extension mounts that directory, and Sphinx reads in place. Pick the\n  former for fine-grained multi-project rule collection and tag-driven\n  variants; pick the latter when \"Bazel build, then Sphinx\" is enough.\n  See `docs/source/bazel.rst` for a side-by-side comparison.\n\n## Documentation\n\nSee `docs/source/` for the full configuration reference and the Bazel\nintegration walkthrough. The \"Related projects\" section in\n`docs/source/index.rst` lists sibling tools ([Sphinx-Needs],\n[sphinx-codelinks], [ubCode], [bazel-drives-sphinx]) that share the\n`ubproject.toml` convention.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n[Sphinx-Needs]: https://sphinx-needs.readthedocs.io/\n[sphinx-codelinks]: https://github.com/useblocks/sphinx-codelinks\n[ubCode]: https://ubcode.useblocks.com/\n[bazel-drives-sphinx]: https://github.com/useblocks/bazel-drives-sphinx\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuseblocks%2Fsphinx-mounts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuseblocks%2Fsphinx-mounts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuseblocks%2Fsphinx-mounts/lists"}