Documentation improvements: build method, docstrings, and cross-references

docs/make.jl:
- Changed from Pkg.activate/instantiate to pushfirst!(LOAD_PATH, ...) for faster builds

src/Exceptions/types.jl:
- Added $(TYPEDEF) macro to ExtensionError and SolverFailure
- Simplified docstrings to focus on core functionality
- Moved constructor throws to # Throws section
- Consolidated examples and removed redundant sections
- Added cross-references to related exception types

src/Extensions/Extensions.jl:
- Added example code blocks for CoveragePostprocessingTag, AbstractTestRunnerTag, TestRunnerTag
- Fixed cross-references from CTBase.* to CTBase.Extensions.*

docs/:
- Updated guide files and index
- Added getting-started.md
- Updated Project.toml and README.md

All tests pass: 1161/1161
Documentation builds successfully

Author: ocots

docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
 Coverage = "a2441757-f6aa-5fb2-8edb-039e3f45d037"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"

docs/README.md

@@ -8,38 +8,29 @@ The documentation is built using [Documenter.jl](https://github.com/JuliaDocs/Do
 
 ## Building the Documentation
 
-There are several ways to build the documentation locally.
-
-### 1. Terminal One-Liner (Recommended)
-
-From the root of the `CTBase.jl` repository, run:
+From the root of the repository:
 
 ```bash
-julia --project=docs/ -e 'using Pkg; Pkg.develop(path=pwd()); include("docs/make.jl"); Pkg.rm("CTBase")'
+julia --project=. docs/make.jl
 ```
 
-This command:
-- Activates the `docs` project environment.
-- Temporarily "develops" the current package so changes are reflected in the build.
-- Executes `make.jl` to build the site.
-- Cleans up the `docs` environment by removing the temporary link to `CTBase`.
-
-### 2. Manual REPL Build
+`make.jl` prepends both `docs/` and the package root to `LOAD_PATH`, so the package
+project is picked up automatically — no `Pkg.develop` step needed.
 
-If you prefer working inside the Julia REPL:
+### Draft mode (fast link validation)
 
-```julia
-# 1. Activate the docs project
-using Pkg
-Pkg.activate("docs/")
+Set `draft = true` at the top of `docs/make.jl` to skip `@repl`/`@example` block
+execution. This is much faster when iterating on cross-references and page structure:
 
-# 2. Add CTBase in development mode (if not already done)
-Pkg.develop(path=pwd())
-
-# 3. Build the documentation
-include("docs/make.jl")
+```bash
+# edit docs/make.jl: draft = true  (line 16)
+julia --project=. docs/make.jl
 ```
 
+!!! note "warnonly"
+    `make.jl` uses `warnonly=[:cross_references]`, so cross-reference warnings do not
+    abort the build. Other errors (missing pages, broken `@repl` blocks) still fail.
+
 ## Viewing the Documentation
 
 After a successful build, the generated HTML files are located in `docs/build/`. You can open `index.html` in your browser:
@@ -54,7 +45,7 @@ xdg-open docs/build/index.html
 
 ## Directory Structure
 
-- `src/`: Contains the manual markdown files (Introduction, Tutorials, etc.).
+- `src/`: Contains the manual markdown files (Introduction, Getting Started, Guides, etc.).
 - `make.jl`: The main build script for Documenter.
 - `api_reference.jl`: Contains the logic for automatic API reference generation. It extracts docstrings from the source code and creates temporary markdown files.
 - `build/`: The directory where the static website is generated (ignored by git).

docs/make.jl

@@ -1,7 +1,7 @@
-using Pkg
-Pkg.activate(@__DIR__)
-Pkg.develop(PackageSpec(; path=joinpath(@__DIR__, "..")))
-Pkg.instantiate()
+# to run the documentation generation:
+# julia --project=. docs/make.jl
+pushfirst!(LOAD_PATH, joinpath(@__DIR__))
+pushfirst!(LOAD_PATH, joinpath(@__DIR__, ".."))
 
 using Documenter
 using CTBase
@@ -54,7 +54,7 @@ with_api_reference(src_dir) do api_pages
     makedocs(;
         draft=draft,
         remotes=nothing, # Disable remote links. Needed for DocumenterReference
-        warnonly=true,
+        warnonly=[:cross_references],
         sitename="CTBase.jl",
         format=Documenter.HTML(;
             repolink="https://" * repo_url,
@@ -67,6 +67,7 @@ with_api_reference(src_dir) do api_pages
         ),
         pages=[
             "Introduction" => "index.md",
+            "Getting Started" => "getting-started.md",
             "User Guides" => [
                 "Descriptions" => joinpath("guide", "descriptions.md"),
                 "Exceptions" => joinpath("guide", "exceptions.md"),

docs/src/getting-started.md

@@ -0,0 +1,114 @@
+```@meta
+CurrentModule = CTBase
+```
+
+# Getting Started
+
+## Installation
+
+CTBase.jl is typically installed as a dependency of another package in the ecosystem
+(e.g. [OptimalControl.jl](https://github.com/control-toolbox/OptimalControl.jl)).
+To install it directly:
+
+```julia
+import Pkg
+Pkg.add("CTBase")
+```
+
+**Requires Julia ≥ 1.10.**
+
+## Mental Model
+
+CTBase is the **base layer** of the control-toolbox ecosystem.
+It provides infrastructure shared by every package above it.
+
+Three things to keep in mind:
+
+1. **No top-level exports.** `using CTBase` loads the package but brings no symbols
+   into scope. Every symbol is accessed via its qualified path:
+   ```julia
+   CTBase.Descriptions.add       # ✓ always works
+   CTBase.Exceptions.NotImplemented
+   ```
+2. **Submodule-first API.** The public API lives in named submodules
+   (`Descriptions`, `Exceptions`, `Extensions`, `Core`, `Unicode`).
+   You can bring a submodule's exports into scope explicitly:
+   ```julia
+   using CTBase.Exceptions        # brings IncorrectArgument, NotImplemented, … into scope
+   ```
+3. **Extension-backed features.** `run_tests`, `postprocess_coverage`, and
+   `automatic_reference_documentation` require loading the matching weak dependency
+   (`Test`, `Coverage`, `Documenter` respectively) before they become active.
+
+## 5-Minute Walkthrough
+
+### Working with Descriptions
+
+A *description* is a `Tuple` of `Symbol`s that declaratively identifies an algorithm
+or configuration. Catalogues collect known descriptions; `complete` resolves a partial
+description to an exact one.
+
+```@repl walkthrough
+using CTBase
+
+# Build a catalogue
+descs = CTBase.Descriptions.add((), (:euler, :explicit))
+descs = CTBase.Descriptions.add(descs, (:euler, :implicit))
+descs = CTBase.Descriptions.add(descs, (:runge_kutta, :explicit))
+
+# Partial completion: find the unique entry containing :implicit
+CTBase.Descriptions.complete(:implicit; descriptions=descs)
+
+# Ambiguous completion raises AmbiguousDescription
+try
+    CTBase.Descriptions.complete(:euler; descriptions=descs)
+catch e
+    println(typeof(e))
+end
+```
+
+For more, see the **[Descriptions guide](guide/descriptions.md)**.
+
+### Working with Exceptions
+
+CTBase defines a typed exception hierarchy rooted at
+[`CTBase.Exceptions.CTException`](@ref).
+Each type carries structured context fields for actionable error messages.
+
+```@repl walkthrough
+# IncorrectArgument — invalid input value
+try
+    throw(CTBase.Exceptions.IncorrectArgument(
+        "state dimension must be positive";
+        got="0",
+        expected="n > 0",
+        suggestion="Pass a positive integer for the state dimension",
+    ))
+catch e
+    println(e)
+end
+
+# NotImplemented — interface stub
+try
+    throw(CTBase.Exceptions.NotImplemented(
+        "solve! is not implemented";
+        required_method="solve!(::MyStrategy, ocp)",
+        suggestion="Import the package that provides this strategy",
+    ))
+catch e
+    println(typeof(e))
+end
+```
+
+For more, see the **[Exceptions guide](guide/exceptions.md)**.
+
+## Next Steps
+
+| Topic | Guide |
+|:---|:---|
+| Descriptions catalogue and completion | [Descriptions](guide/descriptions.md) |
+| Exception hierarchy and best practices | [Exceptions](guide/exceptions.md) |
+| Modular test runner setup | [Test Runner](guide/test-runner.md) |
+| Coverage report generation | [Coverage](guide/coverage.md) |
+| Auto-generated API reference | [API Documentation](guide/api-documentation.md) |
+| Full API reference | API Reference (left sidebar) |

docs/src/guide/api-documentation.md

@@ -1,10 +1,14 @@
+```@meta
+CurrentModule = CTBase
+```
+
 # API Documentation Guide
 
 This guide explains how to set up automated API reference documentation generation using the **DocumenterReference** extension of `CTBase.jl`. This is particularly useful for maintaining comprehensive and up-to-date API documentation as your codebase evolves.
 
 ## Overview
 
-The `DocumenterReference` extension provides the `CTBase.automatic_reference_documentation()` function, which automatically generates API reference pages from your Julia source code. It:
+The `DocumenterReference` extension provides the [`CTBase.automatic_reference_documentation`](@ref) function, which automatically generates API reference pages from your Julia source code. It:
 
 - Extracts docstrings from your modules
 - Separates public and private APIs

docs/src/guide/coverage.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = CTBase
+```
+
 # Coverage Post-processing Guide
 
 This guide explains how to generate human-readable and machine-parseable coverage reports using the **CoveragePostprocessing** extension of `CTBase.jl`.
@@ -25,14 +29,15 @@ To generate actionable coverage reports, we use a dedicated `coverage.jl` script
 pushfirst!(LOAD_PATH, @__DIR__)
 
 using Pkg
-using CTBase # Provides postprocess_coverage
+using CTBase # Provides CTBase.postprocess_coverage
 using Coverage
 
 # This function:
 # 1. Aggregates coverage data.
 # 2. Generates an LCOV file (coverage/lcov.info).
 # 3. Generates a markdown summary (coverage/cov_report.md).
 # 4. Archives used .cov files to keep the directory clean.
+# See: CTBase.postprocess_coverage
 CTBase.postprocess_coverage(; 
     root_dir=dirname(@__DIR__) # Point to the package root
 )