Add Sphinx docs

docs/conf.py

@@ -10,10 +10,17 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
+import importlib.util
+
 project = "S-CORE Bazel C/C++ Toolchain configurations"
 project_url = "https://eclipse-score.github.io/bazel_cpp_toolchains"
 version = "0.1"
-extensions = [
+
+_optional_extensions = [
     "sphinxcontrib.plantuml",
     "score_sphinx_bundle",
 ]
+
+extensions = [
+    ext for ext in _optional_extensions if importlib.util.find_spec(ext) is not None
+]

docs/examples_and_validation.rst

@@ -0,0 +1,84 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+Examples And Validation
+=======================
+
+Example Workspace Purpose
+-------------------------
+
+The ``examples/`` directory is a separate Bazel workspace used as a lightweight
+integration test bed for the repository.
+
+It demonstrates how consumers declare toolchains while also serving as the main
+smoke-test surface for validating that the generated toolchains can build and,
+where appropriate, run example targets.
+
+Important Files
+---------------
+
+``examples/MODULE.bazel``
+   Declares representative Linux and QNX toolchain repositories and wires the
+   example workspace back to the local checkout with ``local_path_override``.
+
+``examples/.bazelrc``
+   Defines named Bazel configurations that activate the generated toolchains and
+   platforms.
+
+``examples/BUILD``
+   Contains small C++ targets used to verify compilation, linking, pthread
+   support, and sanitizer integration.
+
+``examples/tests/toolchain_smoke_tests.sh``
+   Matrix runner that maps each configuration name to a small build or test
+   sequence.
+
+Smoke-Test Matrix
+-----------------
+
+The example workspace currently validates these configuration groups:
+
+- Linux host toolchains
+- Linux cross-compilation toolchains
+- runtime-specific Linux toolchains such as AutoSD and EB corbos Linux for Safety Applications
+- packaged QNX toolchains
+- locally built QNX SDP toolchains
+
+The smoke-test runner isolates Bazel state per configuration so it does not rely
+on ``bazel clean --expunge`` between cases.
+
+Useful Commands
+---------------
+
+.. code-block:: bash
+
+   cd examples
+   ./test.sh --list
+   ./test.sh host_config_1
+   ./test.sh --keep-going
+
+What The Tests Prove
+--------------------
+
+The example workspace is not intended to be an exhaustive compiler correctness
+suite. Instead, it answers a narrower question: did the configuration repository
+produce a usable toolchain definition for each supported scenario?
+
+In practice this means checking:
+
+- successful compilation with the selected compiler and sysroot,
+- correct toolchain registration and platform matching,
+- basic linking behavior,
+- feature coverage such as pthread-enabled builds,
+- optional sanitizer feature wiring for the local Linux toolchain path.

docs/extension_api.rst

@@ -0,0 +1,121 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+Extension API
+=============
+
+Consumer Entry Point
+--------------------
+
+Consumers interact with this repository through the ``gcc`` module extension in
+``@score_bazel_cpp_toolchains//extensions:gcc.bzl``.
+
+Typical usage looks like this:
+
+.. code-block:: starlark
+
+   bazel_dep(name = "score_bazel_cpp_toolchains", version = "0.4.0")
+
+   gcc = use_extension("@score_bazel_cpp_toolchains//extensions:gcc.bzl", "gcc")
+
+   gcc.toolchain(
+       name = "score_gcc_toolchain",
+       target_cpu = "x86_64",
+       target_os = "linux",
+       version = "12.2.0",
+       use_default_package = True,
+   )
+
+   use_repo(gcc, "score_gcc_toolchain")
+
+Public Tags
+-----------
+
+``gcc.toolchain(...)``
+   Declares a toolchain repository to generate.
+
+``gcc.sdp(...)``
+   Declares a package repository explicitly. This is used when the package is
+   not taken from the default version matrix or when local QNX SDP generation is
+   required.
+
+``gcc.toolchain(...)`` Attributes
+---------------------------------
+
+Required attributes:
+
+- ``name``: name of the generated repository
+- ``target_cpu``: target CPU, currently ``x86_64`` or ``aarch64``
+- ``target_os``: target OS, currently ``linux`` or ``qnx``
+
+Common package selection attributes:
+
+- ``use_default_package``: resolve package metadata from ``packages/version_matrix.bzl``
+- ``version``: GCC version string for Linux toolchains
+- ``sdp_version``: QNX SDP version string
+- ``sdk_version``: alternative SDK identifier used in matrix resolution
+- ``sdp_to_link``: override the package repository name that the toolchain uses
+
+Flag and runtime attributes:
+
+- ``extra_compile_flags``
+- ``extra_c_compile_flags``
+- ``extra_cxx_compile_flags``
+- ``extra_link_flags``
+- ``ld_library_paths``
+- ``runtime_ecosystem``
+- ``use_base_constraints_only``
+
+QNX-specific attributes:
+
+- ``license_path``
+- ``license_info_variable``
+- ``license_info_url``
+
+``gcc.sdp(...)`` Attributes
+---------------------------
+
+The ``gcc.sdp`` tag defines the package side of the toolchain setup. Important
+attributes are:
+
+- ``name``: repository name for the package
+- ``build_file``: BUILD file that exposes the package contents as Bazel targets
+- ``url`` and ``sha256``: archive or installer source
+- ``strip_prefix``: extraction prefix for packaged archives
+- ``mode``: ``archive`` or ``build``
+- ``patchset``: QNX SDP patchset definition used in build mode
+- ``target_cpu``: target CPU used when building an SDP locally
+
+Activation In A Workspace
+-------------------------
+
+Declaring a toolchain repository is not enough on its own. Consumers still need
+to activate the generated toolchain during Bazel analysis, typically with a
+configuration such as:
+
+.. code-block:: text
+
+   --extra_toolchains=@score_gcc_toolchain//:x86_64-linux-gcc_12.2.0
+
+The example workspace under ``examples/`` provides complete ``.bazelrc``
+configurations for this activation step.
+
+Behavior Notes
+--------------
+
+- The extension is intended for the root module.
+- When ``use_default_package`` is enabled, the version matrix can inject extra
+  include and link flags required by non-standard sysroot layouts.
+- QNX toolchains use additional licensing and include-path parameters that do
+  not apply to Linux toolchains.

docs/generation_flow.rst

@@ -0,0 +1,98 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+Generation Flow
+===============
+
+End-To-End Flow
+---------------
+
+The repository turns a small ``MODULE.bazel`` declaration into a generated
+toolchain repository through these steps:
+
+1. ``extensions/gcc.bzl`` collects ``gcc.toolchain`` and ``gcc.sdp`` tags.
+2. Package metadata is resolved from ``packages/version_matrix.bzl`` or from an
+   explicit ``gcc.sdp`` declaration.
+3. ``rules/gcc.bzl`` renders a BUILD file and configuration files into a new
+   repository.
+4. Platform-specific templates from ``templates/linux/`` or ``templates/qnx/``
+   are populated with CPU, version, licensing, and flag information.
+5. The consuming workspace enables the generated toolchain with
+   ``--extra_toolchains`` and compatible platform constraints.
+
+Subsystem Roles
+---------------
+
+``packages/version_matrix.bzl``
+   Defines the supported package matrix. Each entry maps a logical toolchain key
+   to download metadata and, when needed, extra compiler or linker flags.
+
+``rules/common.bzl``
+   Provides small helpers that convert lists of flags into the Bazel
+   ``flag_group`` representation needed by the templates and repository rules.
+
+``rules/gcc.bzl``
+   Generates the toolchain repository. It decides whether Linux or QNX template
+   content is required, performs placeholder substitution, and emits the final
+   ``BUILD``, ``cc_toolchain_config.bzl``, ``flags.bzl``, and Linux ``gcov``
+   wrapper files.
+
+``rules/qnx_sdp_gen.bzl``
+   Handles the special case where a QNX SDP must be built locally rather than
+   downloaded as a ready-made archive.
+
+Template Families
+-----------------
+
+Linux templates:
+
+- ``templates/linux/cc_toolchain_config.bzl.template``
+- ``templates/linux/cc_toolchain_flags.bzl.template``
+- ``templates/linux/cc_gcov_wrapper.template``
+
+QNX templates:
+
+- ``templates/qnx/cc_toolchain_config.bzl.template``
+- ``templates/qnx/cc_toolchain_flags.bzl.template``
+
+Shared template:
+
+- ``templates/BUILD.template``
+
+Important Implementation Details
+--------------------------------
+
+- Some package definitions rely on the ``%{toolchain_pkg}%`` placeholder, which
+  is rewritten to the canonical Bzlmod repository name during repository-rule
+  generation.
+- QNX ``aarch64`` is mapped internally to ``aarch64le`` where required by the
+  underlying SDK layout.
+- SDP version ``8.0.3`` is normalized to ``8.0.0`` in the generated toolchain
+  configuration because platform constraint support currently uses the older
+  identifier.
+- Linux toolchains generate an extra ``gcov_wrapper`` script to work around the
+  current ``rules_cc`` coverage integration behavior.
+
+Version Matrix Responsibilities
+-------------------------------
+
+The version matrix is more than a list of URLs. It is also the place where the
+repository centralizes:
+
+- package build-file selection,
+- archive extraction prefixes,
+- sysroot-specific compiler flags,
+- extra link flags,
+- compiler library search paths,
+- runtime-ecosystem variants such as AutoSD or EB corbos Linux for Safety Applications.

docs/index.rst

@@ -11,22 +11,49 @@
    #
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
-Bazel C/C++ Toolchain Config Documentation
-============================
 
-TBD
+S-CORE Bazel C/C++ Toolchain Configuration Repository
+=====================================================
 
-.. contents:: Table of Contents
-   :depth: 2
-   :local:
+This repository contains the configuration layer for S-CORE C and C++
+toolchains used in Bazel builds. It does not ship compiler binaries. Instead,
+it defines the metadata, templates, repository rules, module extension logic,
+and validation workspace needed to fetch and register external toolchain
+packages reproducibly.
 
-Purpose
--------
-TBD
+The documentation below is organized around the main subsystems of the
+repository: how consumers declare toolchains, how Bazel repositories are
+generated, how platform packages are described, how the example workspace
+validates the setup, and how QNX-specific authentication and licensing fit in.
 
-Summary
--------
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
 
-**Library:** `Score C/C++ Toolchain configurations`
+   overview
+   repository_layout
+   extension_api
+   generation_flow
+   examples_and_validation
+   qnx_integration
+   maintenance
 
-**Type:** Bazel toolchain configurations
+Quick Summary
+-------------
+
+**Library:** S-CORE Bazel C/C++ toolchain configurations
+
+**Type:** Bazel module with repository rules, templates, and example validation
+
+**Primary consumer entry point:** ``@score_bazel_cpp_toolchains//extensions:gcc.bzl``
+
+**Main validation surface:** ``examples/`` smoke-test workspace
+
+Key Capabilities
+----------------
+
+- Define Linux and QNX toolchains through a Bzlmod extension.
+- Resolve default package metadata through ``packages/version_matrix.bzl``.
+- Generate toolchain repositories from platform-specific templates.
+- Support both packaged and locally built QNX SDP flows.
+- Validate toolchain selections through the example workspace test matrix.