tinkering but doesn't work yet

Author: a-zw

docs/how-to/any_folder.rst

@@ -12,7 +12,8 @@ You can symlink the folders by adding to your ``conf.py``:
        "../score/containers/docs": "component/containers",
    }
 
-With this configuration, all files in ``score/containers/docs/`` become available at ``docs/component/containers/``.
+All files in ``score/containers/docs/`` become available at ``docs/component/containers/``.
+Include them via ``toctree`` as usual.
 
 If you have ``docs/component/overview.rst``, for example,
 you can include the component documentation via ``toctree``:
@@ -46,3 +47,20 @@ in your ``docs()`` call so Bazel tracks them as dependencies:
 
 This is necessary for sandboxed builds.
 For example, when other modules use your documentation's ``needs.json`` as a dependency.
+
+Combo builds
+------------
+
+When a combo build aggregates multiple modules, only the main ``conf.py`` is
+processed by Sphinx.  External modules mounted via ``sphinx_collections`` have
+their own ``score_any_folder_mapping`` that would otherwise be ignored, leaving
+their externally-mapped files at the wrong paths.
+
+No extra configuration is required.  The extension automatically scans
+``confdir`` subdirectories for ``conf.py`` files after the primary symlink pass
+and applies any ``score_any_folder_mapping`` it finds, with paths resolved
+relative to each module's directory.  All secondary symlinks are cleaned up
+alongside the primary ones when the build finishes.
+
+The handler runs at event priority 600 (above the default 500) to ensure
+``sphinx_collections`` has finished mounting modules before the scan begins.

src/extensions/docs/any_folder.rst

@@ -24,8 +24,23 @@ Sphinx then discovers and buildsthose files as if they were part of ``docs/`` fr
 The extension hooks into the ``builder-inited`` event,
 which fires before Sphinx reads any documents.
 
+Configuration reference
+-----------------------
+
+``score_any_folder_mapping``
+    *dict[str, str]*, default ``{}``
+
+    Maps source directories to symlink paths, both relative to ``confdir``.
+    Applied on every Sphinx build.
+
+    .. code-block:: python
+
+       score_any_folder_mapping = {
+           "../src/my_module/docs": "my_module",
+       }
+
 Difference to Sphinx-Collections
---------------------------------
+---------------------------------
 
 The extension `sphinx-collections <https://sphinx-collections.readthedocs.io/>`_
 is very similar to this extension.

src/extensions/score_any_folder/__init__.py

@@ -28,14 +28,28 @@
 
 The extension creates the symlinks on ``builder-inited``,
 before Sphinx starts reading any documents.
-Existing correct symlinks are left in place(idempotent);
+Existing correct symlinks are left in place (idempotent);
 a symlink pointing to the wrong target is replaced.
 
 Symlinks created by this extension are removed again on ``build-finished``.
 Misconfigured pairs (absolute paths, non-symlink path at the target location)
 are logged as errors and skipped.
+
+Combo builds
+------------
+
+When a combo build mounts external modules via ``sphinx_collections``,
+those modules may have their own ``score_any_folder_mapping`` in their
+``conf.py``.  This extension automatically discovers those files by scanning
+``confdir`` subdirectories after the primary symlink pass and applies their
+mappings with paths resolved relative to each module's directory.
+
+No extra configuration is required.  The handler is registered at event
+priority 600 (above the default 500) to ensure it runs after
+``sphinx_collections`` has mounted its collections.
 """
 
+import ast
 from pathlib import Path
 
 from sphinx.application import Sphinx
@@ -45,9 +59,11 @@
 
 _APP_ATTRIBUTE = "_score_any_folder_created_links"
 
+
 def setup(app: Sphinx) -> dict[str, str | bool]:
     app.add_config_value("score_any_folder_mapping", default={}, rebuild="env")
-    app.connect("builder-inited", _create_symlinks)
+    # Priority 600 > default 500: run after sphinx_collections has mounted modules.
+    app.connect("builder-inited", _create_symlinks, priority=600)
     app.connect("build-finished", _cleanup_symlinks)
     return {
         "version": "0.1",
@@ -56,11 +72,39 @@ def setup(app: Sphinx) -> dict[str, str | bool]:
     }
 
 
-def _symlink_pairs(app: Sphinx) -> list[tuple[Path, Path]]:
-    """Return ``(resolved_source, link_path)`` pairs from the mapping."""
-    confdir = Path(app.confdir)
+def _extract_mapping_from_conf(conf_path: Path) -> dict[str, str]:
+    """Safely extract ``score_any_folder_mapping`` from a ``conf.py`` file.
+
+    Uses ``ast.literal_eval`` so no arbitrary code is executed.
+    Returns an empty dict if the key is absent or cannot be parsed.
+    """
+    try:
+        tree = ast.parse(conf_path.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Assign):
+                continue
+            for target in node.targets:
+                if (
+                    isinstance(target, ast.Name)
+                    and target.id == "score_any_folder_mapping"
+                ):
+                    return ast.literal_eval(node.value)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug(
+            "score_any_folder: could not extract mapping from %s: %s",
+            conf_path,
+            exc,
+        )
+    return {}
+
+
+def _symlink_pairs(confdir: Path, mapping: dict[str, str]) -> list[tuple[Path, Path]]:
+    """Return ``(resolved_source, link_path)`` pairs from *mapping*.
+
+    Entries with absolute paths are logged as errors and skipped.
+    """
     pairs = []
-    for source_rel, target_rel in app.config.score_any_folder_mapping.items():
+    for source_rel, target_rel in mapping.items():
         if Path(source_rel).is_absolute():
             logger.error(
                 "score_any_folder: source path must be relative, got: %r; skipping",
@@ -79,39 +123,62 @@ def _symlink_pairs(app: Sphinx) -> list[tuple[Path, Path]]:
     return pairs
 
 
+def _maybe_create_symlink(source: Path, link: Path, created_links: set[Path]) -> None:
+    """Create a symlink at *link* pointing to *source*, if needed.
+
+    Handles the idempotent / stale-symlink / existing-path cases and logs
+    errors without raising.  Successfully created links are added to
+    *created_links* for later cleanup.
+    """
+    if link.is_symlink():
+        if link.resolve() == source:
+            logger.debug("score_any_folder: symlink already correct: %s", link)
+            return
+        logger.info("score_any_folder: replacing stale symlink %s -> %s", link, source)
+        link.unlink()
+    elif link.exists():
+        logger.error(
+            "score_any_folder: target path already exists and is not a symlink: "
+            "%s; skipping",
+            link,
+        )
+        return
+
+    link.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        link.symlink_to(source)
+    except OSError as exc:
+        logger.error(
+            "score_any_folder: failed to create symlink %s -> %s: %s",
+            link,
+            source,
+            exc,
+        )
+        return
+    created_links.add(link)
+    logger.debug("score_any_folder: created symlink %s -> %s", link, source)
+
+
 def _create_symlinks(app: Sphinx) -> None:
     created_links: set[Path] = set()
+    confdir = Path(app.confdir)
 
-    for source, link in _symlink_pairs(app):
-        if link.is_symlink():
-            if link.resolve() == source:
-                logger.debug("score_any_folder: symlink already correct: %s", link)
-                continue
-            logger.info(
-                "score_any_folder: replacing stale symlink %s -> %s", link, source
-            )
-            link.unlink()
-        elif link.exists():
-            logger.error(
-                "score_any_folder: target path already exists and is not a symlink: "
-                "%s; skipping",
-                link,
-            )
-            continue
-
-        link.parent.mkdir(parents=True, exist_ok=True)
-        try:
-            link.symlink_to(source)
-        except OSError as exc:
-            logger.error(
-                "score_any_folder: failed to create symlink %s -> %s: %s",
-                link,
-                source,
-                exc,
-            )
+    # Primary pass — mappings defined in the main conf.py.
+    for source, link in _symlink_pairs(confdir, app.config.score_any_folder_mapping):
+        _maybe_create_symlink(source, link, created_links)
+
+    # Secondary pass — auto-discover conf.py files in subdirectories.
+    # Picks up modules mounted by sphinx_collections (or any other mechanism).
+    # Running at priority 600 ensures sphinx_collections has already mounted
+    # its collections before we scan.
+    for conf_py in sorted(confdir.rglob("conf.py")):
+        if conf_py.parent == confdir:
+            continue  # skip the main conf.py
+        module_mapping = _extract_mapping_from_conf(conf_py)
+        if not module_mapping:
             continue
-        created_links.add(link)
-        logger.debug("score_any_folder: created symlink %s -> %s", link, source)
+        for source, link in _symlink_pairs(conf_py.parent, module_mapping):
+            _maybe_create_symlink(source, link, created_links)
 
     setattr(app, _APP_ATTRIBUTE, created_links)
 

src/extensions/score_any_folder/tests/test_score_any_folder.py

@@ -16,6 +16,7 @@
 from pathlib import Path
 
 import pytest
+from score_any_folder import _extract_mapping_from_conf
 from sphinx.testing.util import SphinxTestApp
 
 
@@ -68,6 +69,49 @@ def _factory(mapping: dict[str, str]) -> SphinxTestApp:
         app.cleanup()
 
 
+# ---------------------------------------------------------------------------
+# _extract_mapping_from_conf
+# ---------------------------------------------------------------------------
+
+
+def test_extract_mapping_returns_dict(tmp_path: Path) -> None:
+    conf = tmp_path / "conf.py"
+    conf.write_text('score_any_folder_mapping = {"../src": "src"}\n')
+    assert _extract_mapping_from_conf(conf) == {"../src": "src"}
+
+
+def test_extract_mapping_missing_key_returns_empty(tmp_path: Path) -> None:
+    conf = tmp_path / "conf.py"
+    conf.write_text("project = 'test'\n")
+    assert _extract_mapping_from_conf(conf) == {}
+
+
+def test_extract_mapping_non_literal_value_returns_empty(tmp_path: Path) -> None:
+    conf = tmp_path / "conf.py"
+    conf.write_text("score_any_folder_mapping = dict(src='src')\n")
+    assert _extract_mapping_from_conf(conf) == {}
+
+
+def test_extract_mapping_syntax_error_returns_empty(tmp_path: Path) -> None:
+    conf = tmp_path / "conf.py"
+    conf.write_text("score_any_folder_mapping = {this is not valid python\n")
+    assert _extract_mapping_from_conf(conf) == {}
+
+
+def test_extract_mapping_multiple_assignments_returns_first(tmp_path: Path) -> None:
+    conf = tmp_path / "conf.py"
+    conf.write_text(
+        'score_any_folder_mapping = {"../a": "a"}\n'
+        'score_any_folder_mapping = {"../b": "b"}\n'
+    )
+    assert _extract_mapping_from_conf(conf) == {"../a": "a"}
+
+
+# ---------------------------------------------------------------------------
+# Primary symlink behaviour
+# ---------------------------------------------------------------------------
+
+
 def test_symlink_exposes_files_at_target_path(
     make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp],
     docs_dir: Path,
@@ -175,3 +219,86 @@ def test_target_in_subfolder(
     link = docs_dir / "foo" / "other"
     assert link.is_symlink()
     assert link.resolve() == src_docs.resolve()
+
+
+# ---------------------------------------------------------------------------
+# Auto-discovery of module conf.py files (combo build support)
+# ---------------------------------------------------------------------------
+
+
+def test_autodiscovery_applies_module_mapping(
+    make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp],
+    docs_dir: Path,
+    tmp_path: Path,
+) -> None:
+    """A conf.py found in a subdirectory has its mapping applied automatically."""
+    # Simulate a sphinx_collections mount at docs/_collections/module/
+    module_docs = docs_dir / "_collections" / "module"
+    module_docs.mkdir(parents=True)
+    containers = tmp_path / "module_repo" / "containers" / "docs"
+    containers.mkdir(parents=True)
+    (containers / "page.rst").write_text("Container Page\n==============\n")
+    (module_docs / "conf.py").write_text(
+        'score_any_folder_mapping = {"../../../module_repo/containers/docs":'
+        ' "component/containers"}\n'
+    )
+
+    make_sphinx_app({})
+
+    link = module_docs / "component" / "containers"
+    assert link.is_symlink()
+    assert link.resolve() == containers.resolve()
+    assert (link / "page.rst").read_text() == "Container Page\n==============\n"
+
+
+def test_autodiscovery_cleans_up_secondary_symlinks(
+    make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp],
+    docs_dir: Path,
+    tmp_path: Path,
+) -> None:
+    """Secondary symlinks from auto-discovered modules are removed on build-finished."""
+    module_docs = docs_dir / "_collections" / "module"
+    module_docs.mkdir(parents=True)
+    external = tmp_path / "external"
+    external.mkdir()
+    (module_docs / "conf.py").write_text(
+        'score_any_folder_mapping = {"../../../external": "ext"}\n'
+    )
+
+    make_sphinx_app({}).build()
+
+    assert not (module_docs / "ext").exists()
+
+
+def test_autodiscovery_ignores_conf_without_mapping(
+    make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp],
+    docs_dir: Path,
+) -> None:
+    """A subdirectory conf.py with no score_any_folder_mapping produces no symlinks."""
+    module_docs = docs_dir / "_collections" / "module"
+    module_docs.mkdir(parents=True)
+    (module_docs / "conf.py").write_text("project = 'test'\n")
+
+    make_sphinx_app({}).build()
+
+    assert [p for p in module_docs.iterdir() if p.is_symlink()] == []
+
+
+def test_autodiscovery_nested_conf(
+    make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp],
+    docs_dir: Path,
+    tmp_path: Path,
+) -> None:
+    """Auto-discovery works for conf.py files nested more than one level deep."""
+    nested_docs = docs_dir / "_collections" / "org" / "module" / "docs"
+    nested_docs.mkdir(parents=True)
+    external = tmp_path / "external"
+    external.mkdir()
+    (nested_docs / "conf.py").write_text(
+        'score_any_folder_mapping = {"../../../../../external": "ext"}\n'
+    )
+
+    make_sphinx_app({})
+
+    assert (nested_docs / "ext").is_symlink()
+    assert (nested_docs / "ext").resolve() == external.resolve()