template: integrate docs-as-code (#15)

* template: integrate docs-as-code
* docs: fixed formatting

Use the `docs-as-code` tool for building documentation
fixed formatting issues

Addresses: eclipse-score/score#926
---------

Signed-off-by: Dan Calavrezo <[email protected]>

Author: dcalavrezo-qorix

MODULE.bazel

@@ -60,3 +60,6 @@ bazel_dep(name = "score_dash_license_checker", version = "0.1.1")
 bazel_dep(name = "score_format_checker", version = "0.1.1")
 bazel_dep(name = "aspect_rules_lint", version = "1.0.3")
 bazel_dep(name = "buildifier_prebuilt", version = "7.3.1")
+
+#docs-as-code
+bazel_dep(name = "score_docs_as_code", version = "0.2.1")

docs/BUILD

@@ -0,0 +1,18 @@
+load("@score_docs_as_code//:docs.bzl", "docs")
+
+# Creates all documentation targets:
+# - `docs:incremental` for building docs incrementally at runtime
+# - `docs:live_preview` for live preview in the browser without an IDE
+# - `docs:ide_support` for creating python virtualenv for IDE support
+# - `docs:docs` for building documentation at build-time
+
+docs(
+    #   conf_dir = "docs",
+    docs_targets = [
+        {
+            "suffix": "",  # local without external needs
+        },
+    ],
+    #   source_dir = "docs",
+    source_files_to_scan_for_needs_links = [],
+)

docs/conf.py

@@ -0,0 +1,54 @@
+# *******************************************************************************
+# Copyright (c) 2024 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
+# *******************************************************************************
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Module Template Project"
+author = "S-CORE"
+version = "0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+extensions = [
+    "sphinx_design",
+    "sphinx_needs",
+    "sphinxcontrib.plantuml",
+    "score_plantuml",
+    "score_metamodel",
+    "score_draw_uml_funcs",
+    "score_source_code_linker",
+    "score_layout",
+]
+
+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
+    # building the documentation via 'bazel run //docs:incremental' or esbonio, these
+    # entries are required to prevent the build from failing.
+    "bazel-*",
+    ".venv_docs",
+]
+
+templates_path = ["templates"]
+
+# Enable numref
+numfig = True

docs/index.rst

@@ -0,0 +1,81 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 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
+   # *******************************************************************************
+
+Module Template Documentation
+=============================
+
+This documentation describes the structure, usage and configuration of the Bazel-based C++/Rust module template.
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Overview
+--------
+
+This repository provides a standardized setup for projects using **C++** or **Rust** and **Bazel** as a build system.
+It integrates best practices for build, test, CI/CD and documentation.
+
+Requirements
+------------
+
+.. stkh_req:: Example Functional Requirement
+   :id: stkh_req__docgen_enabled
+   :status: valid
+   :safety: QM
+   :reqtype: Functional
+   :rationale: Ensure documentation builds are possible for all modules
+
+
+Project Layout
+--------------
+
+The module template includes the following top-level structure:
+
+- `src/`: Main C++/Rust sources
+- `tests/`: Unit and integration tests
+- `examples/`: Usage examples
+- `docs/`: Documentation using `docs-as-code`
+- `.github/workflows/`: CI/CD pipelines
+
+Quick Start
+-----------
+
+To build the module:
+
+.. code-block:: bash
+
+   bazel build //src/...
+
+To run tests:
+
+.. code-block:: bash
+
+   bazel test //tests/...
+
+Configuration
+-------------
+
+The `project_config.bzl` file defines metadata used by Bazel macros.
+
+Example:
+
+.. code-block:: python
+
+   PROJECT_CONFIG = {
+       "asil_level": "QM",
+       "source_code": ["cpp", "rust"]
+   }
+
+This enables conditional behavior (e.g., choosing `clang-tidy` for C++ or `clippy` for Rust).