Enable adding any folder into docs (#431)

Author: a-zw

docs/conf.py

@@ -18,3 +18,7 @@
 extensions = [
     "score_sphinx_bundle",
 ]
+
+score_any_folder_mapping = {
+    "../src/extensions/docs": "internals/extensions",
+}

docs/how-to/any_folder.rst

@@ -0,0 +1,29 @@
+Use Any Folder for Documentation
+================================
+
+Generally, your documentation must be ``docs/``,
+but the RST files for a module may live closer to the code they describe,
+for example in ``src/my_module/docs/``.
+You can symlink the folders by adding to your ``conf.py``:
+
+.. code-block:: python
+
+   score_any_folder_mapping = {
+       "../score/containers/docs": "component/containers",
+   }
+
+With this configuration, all files in ``score/containers/docs/`` become available at ``docs/component/containers/``.
+
+If you have ``docs/component/overview.rst``, for example,
+you can include the component documentation via ``toctree``:
+
+.. code-block:: rst
+
+   .. toctree::
+
+      containers/index
+
+Only relative links are allowed.
+
+The symlinks will show up in your sources.
+**Don't commit the symlinks to git!**

docs/how-to/index.rst

@@ -16,3 +16,4 @@ Here you find practical guides on how to use docs-as-code.
    source_to_doc_links
    test_to_doc_links
    add_extensions
+   any_folder

src/BUILD

@@ -37,6 +37,7 @@ filegroup(
     srcs = glob(
         ["*.py"],
     ) + [
+        "//src/extensions/score_any_folder:all_sources",
         "//src/extensions/score_draw_uml_funcs:all_sources",
         "//src/extensions/score_header_service:all_sources",
         "//src/extensions/score_layout:all_sources",

src/extensions/docs/any_folder.rst

@@ -0,0 +1,38 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Any Folder
+==========
+
+The extension ``score_any_folder`` allows documentation roots to stay in ``docs/``
+while pulling in source files from anywhere else in the repository.
+
+It does this by creating symlinks inside the Sphinx source directory (``confdir``) that point to the configured external directories.
+Sphinx then discovers and buildsthose files as if they were part of ``docs/`` from the start.
+
+The extension hooks into the ``builder-inited`` event,
+which fires before Sphinx reads any documents.
+
+Difference to Sphinx-Collections
+--------------------------------
+
+The extension `sphinx-collections <https://sphinx-collections.readthedocs.io/>`_
+is very similar to this extension.
+We use it for including external modules
+as it allows conditional inclusion
+and we need to switch between "normal" and "combo" builds.
+
+The relevant difference is that this extension allows to include folders to anywhere
+and is not restricted to a ``_collections/`` folder.
+We consider this additional control over folder placement necessary.

docs/internals/extensions/data_flow.png src/extensions/docs/data_flow.pngdocs/internals/extensions/data_flow.png renamed to src/extensions/docs/data_flow.png

@@ -1,15 +1,16 @@
-..  # *******************************************************************************
-    # Copyright (c) 2025 Contributors to the Eclipse Foundation
-    #
-    # See the NOTICE file(s) distributed with this work for additional
-    # information regarding copyright ownership.
-    #
-    # This program and the accompanying materials are made available under the
-    # terms of the Apache License Version 2.0 which is available at
-    # https://www.apache.org/licenses/LICENSE-2.0
-    #
-    # SPDX-License-Identifier: Apache-2.0
-    # *******************************************************************************
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
 
 .. _extensions:
 
@@ -71,6 +72,16 @@ Hello there
       `ubCode <https://ubcode.useblocks.com>`__ VS Code extension.
       Getting IDE support for Sphinx-Needs in a Bazel context made easy.
 
+   .. grid-item-card::
+
+      Any Folder
+      ^^^^^^^^^^
+
+      Learn about the :doc:`any_folder` extension that creates symlinks
+      from arbitrary repository locations into the docs folder,
+      allowing Sphinx to discover and build source files
+      that live outside the documentation root.
+
 
 
 .. toctree::
@@ -83,3 +94,4 @@ Hello there
    Source Code Linker <source_code_linker>
    Extension Guide <extension_guide>
    Sync TOML <sync_toml>
+   Any Folder <any_folder>