Convert all .rst into markdown

Author: nradakovic

README.md

@@ -154,7 +154,16 @@ Example cover:
 
 # Documentation
 
-Documentation uses **Sphinx** and lives in `docs/`. (Not yet prepared!)
+The documentation lives in `docs/` as Markdown sources rendered by Sphinx.
+
+- [Documentation index](docs/index.md)
+- [Overview](docs/overview.md)
+- [Repository layout](docs/repository_layout.md)
+- [Extension API](docs/extension_api.md)
+- [Generation flow](docs/generation_flow.md)
+- [Examples and validation](docs/examples_and_validation.md)
+- [QNX integration](docs/qnx_integration.md)
+- [Maintenance](docs/maintenance.md)
 
 # QNX License
 

docs/conf.py

@@ -17,10 +17,15 @@
 version = "0.1"
 
 _optional_extensions = [
+    "myst_parser",
     "sphinxcontrib.plantuml",
     "score_sphinx_bundle",
 ]
 
 extensions = [
     ext for ext in _optional_extensions if importlib.util.find_spec(ext) is not None
 ]
+
+source_suffix = {
+    ".md": "markdown",
+}

docs/examples_and_validation.md

@@ -0,0 +1,83 @@
+<!--
+# *******************************************************************************
+# 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
+
+```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/examples_and_validation.rst

@@ -0,0 +1,117 @@
+<!--
+# *******************************************************************************
+# 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:
+
+```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:
+
+```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.