add documentation examples

BUILD

@@ -23,7 +23,7 @@ setup_starpls(
 copyright_checker(
     name = "copyright",
     srcs = [
-        "src",
+        "score",
         "tests",
         "//:BUILD",
         "//:MODULE.bazel",
@@ -44,5 +44,8 @@ dash_license_checker(
 use_format_targets()
 
 docs(
-    source_dir = "docs",
+    data = [
+        "@score_process//:needs_json",
+    ],
+    source_dir = ".",
 )

MODULE.bazel

@@ -15,7 +15,7 @@ module(
     version = "1.0",
 )
 
-bazel_dep(name = "rules_python", version = "1.4.1", dev_dependency = True)
+bazel_dep(name = "rules_python", version = "1.8.3", dev_dependency = True)
 
 # Python 3.12: Required for testing infrastructure and code generation tools
 PYTHON_VERSION = "3.12"
@@ -30,6 +30,20 @@ python.toolchain(
     python_version = PYTHON_VERSION,
 )
 
+pip = use_extension(
+    "@rules_python//python/extensions:pip.bzl",
+    "pip",
+    dev_dependency = True,
+)
+pip.parse(
+    envsubst = ["PIP_INDEX_URL"],
+    extra_pip_args = ["--index-url=${PIP_INDEX_URL:-https://pypi.org/simple/}"],
+    hub_name = "module_template_docs_hub_env",
+    python_version = PYTHON_VERSION,
+    requirements_lock = "@score_docs_as_code//src:requirements.txt",
+)
+use_repo(pip, "module_template_docs_hub_env")
+
 # Add GoogleTest dependency
 bazel_dep(name = "googletest", version = "1.17.0", dev_dependency = True)
 
@@ -57,9 +71,16 @@ use_repo(llvm, "llvm_toolchain_llvm")
 register_toolchains("@llvm_toolchain//:all")
 
 # tooling
-bazel_dep(name = "score_tooling", version = "1.0.4", dev_dependency = True)
+bazel_dep(name = "score_tooling", version = "1.2.0", dev_dependency = True)
 bazel_dep(name = "aspect_rules_lint", version = "1.10.2", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "8.2.0.2", dev_dependency = True)
 
 #docs-as-code
-bazel_dep(name = "score_docs_as_code", version = "2.3.0", dev_dependency = True)
+bazel_dep(name = "score_docs_as_code", version = "3.1.0", dev_dependency = True)
+bazel_dep(name = "score_process", version = "1.5.1", dev_dependency = True)
+
+git_override(
+    module_name = "score_docs_as_code",
+    commit = "817080b1f184618a3ecb5bb9029e453ebc5fe806",
+    remote = "https://github.com/eclipse-score/docs-as-code.git",
+)

README.md

@@ -31,7 +31,7 @@ It provides a **standardized project structure**, ensuring best practices for:
 | File/Folder                         | Description                                       |
 | ----------------------------------- | ------------------------------------------------- |
 | `README.md`                         | Short description & build instructions            |
-| `src/`                              | Source files and Unit Tests for the module        |
+| `score/`                            | Source files and Unit Tests for the module        |
 | `tests/`                            | Component and Feature Integration Tests (CIT&FIT) |
 | `examples/`                         | Example files used for guidance                   |
 | `docs/`                             | Documentation (Doxygen for C++ / mdBook for Rust) |
@@ -61,15 +61,15 @@ cd YOUR_PROJECT
 To build all targets of the module the following command can be used:
 
 ```sh
-bazel build //src/...
+bazel build //score/...
 ```
 
 This command will instruct Bazel to build all targets that are under Bazel
-package `src/`. The ideal solution is to provide single target that builds
+package `score/`. The ideal solution is to provide single target that builds
 artifacts, for example:
 
 ```sh
-bazel build //src/<module_name>:release_artifacts
+bazel build //score/<module_name>:release_artifacts
 ```
 
 where `:release_artifacts` is filegroup target that collects all release
@@ -89,7 +89,7 @@ bazel test //...
 Unit tests:
 
 ```sh
-bazel test //src/...
+bazel test //score/...
 ```
 
 Component / Feature integration tests:
@@ -113,6 +113,14 @@ The template integrates **tools and linters** from **centralized repositories**
 ## 📖 Documentation
 
 - A **centralized docs structure** is planned.
+- This template builds Sphinx from the repository root. The configuration stays in
+    `conf.py`, the main document is `docs/index.rst`, and the root `BUILD` target uses
+    a repository-local `docs.bzl` wrapper because the upstream SCORE docs macro does not
+    currently support `source_dir = "."`.
+
+```sh
+bazel run //:docs
+```
 
 ---
 

docs/conf.py → conf.py

@@ -41,6 +41,15 @@
     "score_layout",
 ]
 
+# Collect documentation from the module-level docs folder and from each
+# component's docs folder. Using include_patterns (added in Sphinx 7.1) avoids
+# the need for symlinks inside the docs/ folder.
+include_patterns = [
+    "index.rst",
+    "docs/**",
+    "score/example_component/docs/**",
+]
+
 exclude_patterns = [
     # The following entries are not required when building the documentation via 'bazel
     # build //docs:docs', as that command runs in a sandboxed environment. However, when
@@ -50,7 +59,9 @@
     ".venv_docs",
 ]
 
-templates_path = ["templates"]
+root_doc = "index"
+
+templates_path = ["docs/templates"]
 
 # Enable numref
 numfig = True