ceedling 1.0.1 → 1.1.0

data/docs/mkdocs/getting-started/index.md

@@ -0,0 +1,41 @@
+# Getting Started
+
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch: **[Quick Start](quick-start.md)**
+
+    ---
+
+    Steps from installation through running your first build tasks — 
+    get up and running fast.
+
+-   :material-download: **[Installation](installation.md)**
+
+    ---
+
+    Install Ceedling as a Ruby Gem or use a prepackaged _MadScienceLab_
+    Docker image with Ceedling, GCC, and supporting tools already bundled.
+
+-   :material-console: **[Command Line](command-line.md)**
+
+    ---
+
+    Application commands (project creation, help, config inspection) and
+    build & plugin tasks (test runs, release builds, clean, and more).
+
+-   :material-file-code: **[Commented Sample Test File](../testing-guide/test-sample.md)**
+
+    ---
+
+    A sample test file illustrating the Ceedling conventions that make it go. 
+    Includes a discussion of what gets compiled and linked into a test executable.
+
+-   :material-package-variant-closed-check: **[Example Projects](example-projects/index.md)**
+
+    ---
+
+    Ceedling includes several readymade example projects for learning and reference.
+
+</div>
+
+<br/><br/>

data/docs/mkdocs/getting-started/installation.md

@@ -0,0 +1,172 @@
+# Ceedling Installation & Set Up
+
+**How Exactly Do I Get Started?**
+
+!!! tip
+    You will see various references to Ruby. You do not need to know Ruby
+    to use Ceedling! Ruby is simply the implementation language and 
+    software packaging for Ceedling as a tool.
+
+    Once Ceedling is installed, you interact with it as a command line
+    utility (`ceedling ...`).
+
+You have two good options for installing and running Ceedling:
+
+1. The Ceedling Ruby Gem
+1. Prepackaged _MadScienceLab_ Docker images
+
+One way to get started is to 
+[install Ceedling as a Ruby gem](#installation-as-a-ruby-gem). Gems are 
+simply prepackaged Ruby-based software. Other options exist, but the 
+Ceedling Gem is perhaps the simplest option for local installation.
+However, please note that you will also need a compiler toolchain 
+installed (e.g. GCC — GNU Compiler Collection) plus any supporting tools 
+used by any Ceedling plugins you enable.
+
+If you are familiar with the virtualization technology Docker, our premade
+Docker images will get you started with Ceedling and all the accompanying
+tools lickety split. Install Docker, pull down one of the
+[_MadScienceLab_](#madsciencelab-docker-images) images and go.
+
+## Installation as a [Ruby Gem][ruby-gem]
+
+1. [Download and install Ruby][ruby-install]. Ruby 3 is required.
+1. Use Ruby‘s command line gem package manager to install Ceedling from
+   the public [RubyGems repository][rubygems-repo]: `gem install ceedling`.
+    * Unity and CMock come along with Ceedling at no extra charge.
+    * Installing from the official RubyGems repository will automatically 
+      install Ceedling‘s dependencies.
+1. Use [Ceedling’s command line][command-line] to export an example 
+   project (`ceedling examples` for a listing) or create an empty Ceedling 
+   project with `ceedling new`. Of course, executing `ceedling help` first 
+   is, well, helpful.
+
+[ruby-gem]: http://docs.rubygems.org/read/chapter/1
+[ruby-install]: http://www.ruby-lang.org/en/downloads/
+[rubygems-repo]: http://rubygems.org
+[command-line]: 
+
+### Gem install notes
+
+Steps 1–2 above are a one-time affair for your local environment. 
+When steps 1-2 are completed once, only step 3 is needed for each new 
+code project.
+
+If you are working with prerelease versions of Ceedling or some other 
+off-the-beaten-path installation scenario, you may want to directly 
+install the Ceedling .gem file attached to any of the Github releases.
+No problem.
+
+The steps are similar to the preceding with two changes:
+
+1. `gem install --local <ceedling .gem filepath> --no-document`
+1. Any missing dependencies must be manually installed before 
+   installation of the local Ceedling gem will succeed. A local 
+   installation attempt will complain about any missing dependencies. 
+   Simply `gem install` them by name.
+
+## _MadScienceLab_ Docker Images
+
+As an alternative to local installation, fully packaged Docker images containing Ruby, Ceedling, the GCC toolchain, and more are also available. [Docker][docker-overview] is a virtualization technology that provides self-contained software bundles that are a portable, well-managed alternative to local installation of tools like Ceedling.
+
+Four Docker image variants containing Ceedling and supporting tools exist. These four images are available for both Intel and ARM host platforms (Docker does the right thing based on your host environment). The latter includes ARM Linux and Apple‘s M-series macOS devices.
+
+1. **_[MadScienceLab][docker-image-base]_**. This image contains Ruby, Ceedling, CMock, Unity, CException, the GNU Compiler Collection (gcc), and a handful of essential C libraries and command line utilities.
+1. **_[MadScienceLab Plugins][docker-image-plugins]_**. This image contains all of the above plus the command line tools that Ceedling‘s built-in plugins rely on. Naturally, it is quite a bit larger than option (1) because of the additional tools and dependencies.
+1. **_[MadScienceLab ARM][docker-image-arm]_**. This image mirrors (1) with the compiler toolchain replaced with the GNU `arm-none-eabi` variant. 
+1. **_[MadScienceLab ARM + Plugins][docker-image-arm-plugins]_**. This image is (3) with the addition of all the complementary plugin tooling just like (2) provides.
+
+See the Docker Hub pages linked above for more documentation on these images.
+
+Just to be clear here, most users of the _MadScienceLab_ Docker images will probably care about the ability to run unit tests on your own host. If you are one of those users, no matter what host platform you are on — Intel or ARM — you'll want to go with (1) or (2) above. The tools within the image will automatically do the right thing within your environment. Options (3) and (4) are most useful for specialized cross-compilation scenarios.
+
+!!! tip
+    If you are handy with Docker and want to create your own Docker image, please see the [MadScienceLab downloadable build artifacts](https://github.com/ThrowTheSwitch/MadScienceLabDocker/releases) at the source repository as a reference. The .zip archives for each release include the Dockerfiles and assets we used to build the MadScienceLab Docker images.
+
+### Usage basics
+
+To use a _MadScienceLab_ image from your local terminal:
+
+1. [Install Docker][docker-install]
+1. Determine:
+    1. The local path of your Ceedling project
+    1. The variant and revision of the Docker image you'll be using
+1. Run the container with:
+    1. The Docker `run` command and `-it --rm` command line options
+    1. A Docker volume mapping from the root of your project to the default project path inside the container (_/home/dev/project_)
+
+See the command line examples in the following two sections.
+
+Note that all of these somewhat lengthy command lines lend themselves well to being wrapped up in simple helper scripts specific to your project and directory structure.
+
+### Run as an interactive terminal
+
+When the container launches as shown below, it will drop you into a Z-shell command line that has access to all the tools and utilities available within the container. In this usage, the Docker container becomes just another terminal, including ending its execution with `exit`.
+
+```shell
+ > docker run -it --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0
+```
+
+Once the _MadScienceLab_ container‘s command line is available, to run Ceedling, execute it just as you would after installing Ceedling locally:
+
+```shell
+ ~/project > ceedling help
+```
+
+```shell
+ ~/project > ceedling new ...
+```
+
+```shell
+ ~/project > ceedling test:all
+```
+
+### Run as a command line utility
+
+Alternatively, you can run Ceedling through the _MadScienceLab_ Docker container directly from the command line as a command line utility. The general pattern is immediately below.
+
+```shell
+ > docker run --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0 <Ceedling command line>
+```
+
+As a specific example, to run all tests in a suite, the command line would be this:
+
+```shell
+ > docker run --rm -v /my/local/project/path:/home/dev/project throwtheswitch/madsciencelab-plugins:1.1.0 ceedling test:all
+```
+
+In this usage, the container starts, executes Ceedling, and then ends.
+
+[docker-overview]: https://www.ibm.com/topics/docker
+[docker-install]: https://www.docker.com/products/docker-desktop/
+
+[docker-image-base]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab
+[docker-image-plugins]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-plugins
+[docker-image-arm]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-arm-none-eabi
+[docker-image-arm-plugins]: https://hub.docker.com/repository/docker/throwtheswitch/madsciencelab-arm-none-eabi-plugins
+
+## Getting Started after installation
+
+1. Certain advanced features of Ceedling rely on `gcc` and `cpp` as
+   preprocessing tools. In most Linux systems, these tools are already available.
+   For Windows environments, we recommend the 
+   [MinGW project](http://www.mingw.org/) (Minimalist GNU for Windows). This 
+   represents an optional, additional setup / installation step to complement 
+   the list above. Upon installing MinGW ensure your system path is updated or 
+   set `:environment` ↳ `:path` in your project configuration (see `:environment`
+   section).
+
+1. Once Ceedling is installed, you'll want to start to integrate it with new
+   and old projects alike. If you wanted to start to work on a new project
+   named `foo`, Ceedling can create the skeleton of the project using `ceedling
+   new foo <destination>`. Likewise if you already have a project named `bar` 
+   and you want to "inject" Ceedling into it, you would run `ceedling new bar 
+   <destination>`, and Ceedling will create any files and directories it needs.
+
+1. Now that you have Ceedling integrated with a project, you can start using it.
+   A good starting point is to enable the [plugin](../plugins/index.md) 
+   `module_generator` in your project configuration file and create a source +
+   test code module to get accustomed to Ceedling by issuing the command 
+   `ceedling 'module:create[name]'`.
+
+<br/><br/>

data/docs/mkdocs/getting-started/quick-start.md

@@ -0,0 +1,65 @@
+# Quick Start
+
+## Handy Documentation
+
+* [Installation](installation.md)
+* [Sample test code file](../testing-guide/test-sample.md)
+* [Example Ceedling projects](example-projects/index.md)
+* [Simple Ceedling project file](../overview/build-system.md#simple-sample-project-file)
+* [Ceedling at the command line](command-line.md)
+* [All your project configuration file options](../configuration/index.md)
+
+---
+
+## Quick Start Steps
+
+Below is a quick overview of how to get started from Ceedling installation 
+through running build tasks. Jump down just a teeny bit to see what the Ceedling 
+command line looks like and navigate to all the documentation for the steps 
+listed immediately below.
+
+1. [Install Ceedling](installation.md)
+1. Create a project
+    * Use Ceedling to generate an example project (see next section), or
+    * Add a Ceedling project file to the root of an existing project, or
+    * Create a project from scratch:
+        1. Create a project directory.
+        1. Add source code and optionally test code however you’d like it organized.
+        1. Create a Ceedling project file in the root of your project directory.
+1. Run Ceedling tasks (see next section) from the working directory of your project.
+
+!!! note
+    Ceedling requires a command line C toolchain be available in your path. It’s 
+    flexible enough to work with most anything on any platform. By default, Ceedling 
+    is ready to work with [GCC] out of the box (we recommend the [MinGW] project 
+    on Windows).
+
+A common build strategy with tooling other than GCC is to use your target 
+toolchain for release builds—with or without Ceedling—but rely on Ceedling + 
+GCC for test builds (more on all this [here][overview]).
+
+[GCC]: https://gcc.gnu.org
+[MinGW]: http://www.mingw.org/
+[overview]: ../overview/index.md
+
+## Command Line & Build Tasks
+
+Once you have Ceedling installed, you always have access to `ceedling help`.
+
+Once you have Ceedling installed, you have options for project creation
+using Ceedling’s application commands:
+
+* `ceedling new <name> <destination>`
+* `ceedling examples` to list available example projects and 
+  `ceedling example <name> <destination>` to create a readymade sample 
+   project whose project file you can copy and modify.
+
+Once you have a Ceedling project file and a project directory structure for your
+code, Ceedling build tasks go like this:
+
+* `ceedling test:MyCodeModule`, or
+* `ceedling test:all`, or
+* `ceedling release`, or, if you fancy and have the GCov plugin enabled,
+* `ceedling clobber test:all gcov:all release --log --verbosity=obnoxious`
+
+<br/><br/>

data/docs/mkdocs/help.md

@@ -0,0 +1,49 @@
+# Help
+
+!!! sponsorship "Please consider sponsoring this project"
+    Ceedling, Unity, and CMock are free and open source, 
+    maintained by volunteers. [GitHub Sponsors](https://github.com/sponsors/ThrowTheSwitch) 
+    help fund ongoing maintenance, new features, and the infrastructure 
+    to host and develop the Ceedling Suite of tools.
+
+<div class="grid cards" markdown>
+
+-   :material-bug: **[Submit an Issue][ceedling-issues]**
+
+    ---
+
+    Found a bug or want to suggest a feature? Open an issue in the Ceedling
+    GitHub repository.
+
+-   :material-forum: **[Discussion Forums][forums]**
+
+    ---
+
+    Trying to understand a feature or work through a testing problem?
+    The ThrowTheSwitch community forums are the place to ask.
+
+-   :material-handshake: **[Ceedling Assist][ceedling-assist]**
+
+    ---
+
+    Paid training, customizations, and support contracts are available
+    through [Ceedling Assist][ceedling-assist] offered by [ThingamaByte].
+
+-   :material-school: **[Dr. Surly’s School For Mad Scientists][drsurlys-school]**
+
+    ---
+
+    A curriculum hosted at [Udemy](https://udemy.com) to promote good C development
+    techniques and embedded software practices through testing. So you too can
+    take over the world.
+
+</div>
+
+[ceedling-issues]:       https://github.com/ThrowTheSwitch/Ceedling/issues
+[forums]:                https://www.throwtheswitch.org/forums
+[ceedling-assist]:       https://www.thingamabyte.com/ceedlingassist
+[ThingamaByte]:          https://www.thingamabyte.com/
+[thingamabyte-ceedling]: https://www.thingamabyte.com/ceedling
+[drsurlys-school]:       https://www.throwtheswitch.org/dr-surlys-school
+
+<br/><br/>

data/docs/mkdocs/index.md

@@ -0,0 +1,215 @@
+# Ceedling Packet
+
+Ceedling is a fancypants build system that greatly simplifies building 
+C projects. While it can certainly build release targets, it absolutely 
+shines at running unit test suites.
+
+Ceedling and its suite of frameworks, including Unity and CMock, were developed 
+for use on platforms from heavy duty workstations to teeny tiny microcontrollers. 
+Features handy for low-level development have made these tools popular with 
+embedded systems developers.
+
+!!! tip "New to Ceedling?"
+    <img src="assets/images/ceedling.svg" width="130"><br/>
+    Jump straight to the [Quick Start][quick-start] — installation,
+    project set up, and your first build tasks all in one place.
+
+!!! feature "New in Ceedling 1.1.0 — Partials"
+    A [_Partial_](testing-guide/partials/index.md) is your C code sliced and diced
+    to expose functional elements for testing that you could not otherwise 
+    access without rewriting your source code. Think of Partials as a scalpel 
+    for testing your code.
+
+    👀 See the [Changelog](https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/Changelog.md)
+    for all the new goodness in 1.1.0.
+
+## Overview
+
+<div class="grid cards" markdown>
+
+-   :material-hammer-wrench: **[A Build System for C][build-system]**
+
+    ---
+
+    Generate a complete test and release build from a single YAML file.
+    Provides a minimal sample project configuration and an explanation of Ceedling’s
+    design philosophy.
+
+-   :material-toolbox: **[Tools & Frameworks][tools-and-frameworks]**
+
+    ---
+
+    Ruby, Rake, YAML, Unity, and CMock explained — the pieces that make
+    Ceedling possible and how they fit together.
+
+-   :material-test-tube: **[Test Environments][test-environments]**
+
+    ---
+
+    Native host builds, emulator-based runs, and on-target execution — choose the
+    right test suite strategy for your project.
+
+</div>
+
+## Getting Started
+
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch: **[Quick Start][quick-start]**
+
+    ---
+
+    Ready to go? Let’s go.
+
+-   :material-download: **[Ceedling Installation & Set Up][installation]**
+
+    ---
+
+    Installing Ceedling and its prerequisites.
+
+-   :material-console: **[Ceedling’s Command Line.][command-line]**
+
+    ---
+
+    Now what? How do I make it _Go_?
+
+</div>
+
+## Unit Testing
+
+<div class="grid cards" markdown>
+
+-   :material-help-circle: **[How Does a Test Case Even Work?][test-cases]**
+
+    ---
+
+    A brief overview of what a test case is with simple examples illustrating
+    how test cases work.
+
+-   :material-file-code: **[Commented Sample Test File][test-sample]**
+
+    ---
+
+    A sample test file illustrating test case creation and the conventions
+    that make it work. Includes a discussion of how test executables get built.
+
+-   :material-layers: **[Anatomy of a Test Suite][test-suite-anatomy]**
+
+    ---
+
+    How a unit test grows up to become a test suite.
+
+-   :material-link-variant: **[Using Unity and CMock][frameworks]**
+
+    ---
+
+    Ceedling links together Unity and CMock — each of which can
+    require configuration of their own. Ceedling facilitates this.
+
+-   :material-book-open-page-variant: **[Important Conventions & Behaviors][conventions]**
+
+    ---
+
+    Much of testing in Ceedling is accomplished by convention.
+    Code and files structured and named in certain ways trigger sophisticated build
+    features.
+
+-   :material-content-cut: **[Partials][partials]**
+
+    ---
+
+    Partials are like a scalpel for your source code. A generated partial allows 
+    you to test and mock parts of your code you could not otherwise access
+    without rewriting it first.
+</div>
+
+## Project Configuration
+
+<div class="grid cards" markdown>
+
+-   :material-file-import: **[How to Load a Project Configuration][configuration-loading]**
+
+    ---
+    You have options, my friend. Load your base configuration via command line 
+    flag, environment variable, or default file. Add Mixins to merge configuration 
+    for different build scenarios.
+
+-   :material-file-cog: **[The Mighty Project Configuration File][configuration-project-file]**
+
+    ---
+
+    Everything you need to know about the project configuration file. All in 
+    glorious YAML.
+
+-   :material-book-open-variant: **[Project Configuration Reference][configuration-reference]**
+
+    ---
+
+    Exhaustive documentation for all project configuration options — project
+    paths, testing features, plugins, and much more.
+
+-   :material-clipboard-play-multiple-outline: **[Parallel Builds][parallel-builds]**
+
+    ---
+
+    Configure Ceedling to take advantage of multiple CPU cores for faster build
+    steps and test suite execution.
+
+-   :material-directions-fork: **[Which Ceedling?][which-ceedling]**
+
+    ---
+
+    Sometimes you may need to point to a different Ceedling to run.
+
+</div>
+
+## Advanced & Extending
+
+<div class="grid cards" markdown>
+
+-   :material-pound: **[Build Directive Macros][build-directives]**
+
+    ---
+
+    Code macros to accomplish build goals when Ceedling's conventions aren't
+    quite enough.
+
+-   :material-puzzle-plus: **[Ceedling Plugins][plugins]**
+
+    ---
+
+    Ceedling is extensible with built-in plugins for code coverage, test reporting,
+    CI integration, file scaffolding, sophisticated release builds, and more.
+
+-   :material-database: **[Global Collections][global-collections]**
+
+    ---
+
+    Globally available Ruby lists of paths, files, and more — useful for advanced
+    project customization and plugin development.
+
+</div>
+
+[quick-start]:                 getting-started/quick-start.md
+[build-system]:                overview/build-system.md
+[tools-and-frameworks]:        overview/tools-and-frameworks.md
+[testing-abilities]:           overview/testing-abilities.md
+[test-environments]:           overview/test-environments.md
+[test-cases]:                  testing-guide/test-cases.md
+[test-sample]:                 testing-guide/test-sample.md
+[test-suite-anatomy]:          testing-guide/test-suite-anatomy.md
+[partials]:                    testing-guide/partials/index.md
+[installation]:                getting-started/installation.md
+[command-line]:                getting-started/command-line.md
+[conventions]:                 testing-guide/conventions.md
+[frameworks]:                  testing-guide/frameworks.md
+[configuration-loading]:       configuration/loading.md
+[configuration-project-file]:  configuration/project-file.md
+[configuration-reference]:     configuration/reference/index.md
+[parallel-builds]:             configuration/parallel-builds.md
+[which-ceedling]:              configuration/which-ceedling.md
+[build-directives]:            testing-guide/build-directives.md
+[plugins]:                     plugins/index.md
+[global-collections]:          configuration/global-collections.md
+
+<br/><br/>

data/docs/mkdocs/overview/build-system.md

@@ -0,0 +1,115 @@
+# A Build System for All Your C Mad Scientisting Needs
+
+Ceedling allows you to generate an entire test and release build 
+environment for a C project from a single, short YAML configuration 
+file. It truly shines at supporting unit testing and managing test 
+builds.
+
+Ceedling and its bundled frameworks, Unity and CMock, don't
+want to brag, but they're also quite adept at supporting the tiniest of
+embedded processors, the beefiest 64-bit powerhouses available, and
+everything in between.
+
+Assembling build environments for C projects — especially with
+automated unit tests — is a pain. No matter the all-purpose build 
+environment tool you use, configuration is tedious and requires 
+considerable glue code to pull together the necessary tools and 
+libraries to run unit tests. The Ceedling bundle handles all this 
+for you.
+
+## Simple Sample Project File
+
+For a project including Unity/CMock unit tests and using the default 
+toolchain `gcc`, the configuration file could be as simple as this:
+
+```yaml
+:project:
+  :build_root: project/build/
+  :release_build: TRUE
+
+:paths:
+  :test:
+    - tests/**
+  :source:
+    - source/**
+  :include:
+    - inc/**
+```
+
+!!! tip "Want to see a real world project configuration?"
+    See this [commented project file][example-config-file] 
+    for a much more complete and sophisticated example of a project 
+    configuration.
+
+From the command line, to run all your unit tests, you would run 
+`ceedling test:all`. To build the release version of your project,
+you would simply run `ceedling release`. That's it!
+
+Of course, many more advanced options allow you to configure
+your project with a variety of features to meet a variety of needs.
+Ceedling can work with practically any command line toolchain
+and directory structure – all by way of the configuration file.
+
+See the later [configuration section][project-configuration] for 
+way more details on your project configuration options.
+
+A facility for [plugins](../plugins/index.md) also allows you to 
+extend Ceedling's capabilities for needs such as custom code metrics 
+reporting, build artifact packaging, and much more. A variety of 
+built-in plugins come with Ceedling.
+
+[example-config-file]: ../snapshot/assets/project.yml
+[project-configuration]: ../configuration/index.md
+
+## What's with this name?
+
+Glad you asked. Ceedling is tailored for unit tested C projects and is built
+upon Rake, a Make replacement implemented in the Ruby scripting language.
+
+So, we've got C, our Rake, and the fertile soil of a build environment in which
+to grow and tend your project and its unit tests. Ta da — _Ceedling_.
+
+Incidentally, though Rake was the backbone of the earliest versions of
+Ceedling, it is now being phased out incrementally in successive releases. 
+The name Ceedling is not going away, however!
+
+## “Tailored for unit-tested C projects”?
+
+Well, we like to write unit tests for our C code to make it lean and
+mean — that whole [Test-Driven Development][tdd] thing.
+
+Along the way, this style of writing C code spawned two
+tools to make the job easier:
+
+1. A unit test framework for C called _Unity_
+1. A mocking library called _CMock_
+
+And, though it's not directly related to testing, a C framework for 
+exception handling called _CException_ also came along.
+
+[tdd]: http://en.wikipedia.org/wiki/Test-driven_development
+
+These tools and frameworks are great, but they require quite
+a bit of environment support to pull them all together in a convenient,
+usable fashion. We started off with Rakefiles to assemble everything.
+These ended up being quite complicated and had to be hand-edited
+or created anew for each new project. Ceedling replaces all that
+tedium and rework with a configuration file that ties everything
+together.
+
+Though Ceedling is tailored for unit testing, it can also go right 
+ahead and build your final binary release artifact for you as well. 
+That said, Ceedling is more powerful as a unit test build environment 
+than it is a general purpose release build environment. Complicated 
+projects including separate bootloaders or multiple library builds, 
+etc. are not necessarily its strong suit (but the 
+[`dependencies`](../plugins/dependencies.md) plugin can 
+accomplish quite a bit here).
+
+It's quite common and entirely workable to host Ceedling and your 
+test suite alongside your existing release build setup. That is, you 
+can use make, Visual Studio, SCons, Meson, etc. for your release build
+and Ceedling for your test build. Your two build systems will simply
+"point" to the same project code.
+
+<br/><br/>

data/docs/mkdocs/overview/index.md

@@ -0,0 +1,29 @@
+# Overview
+
+<div class="grid cards" markdown>
+
+-   :material-hammer-wrench: **[A Build System for C](build-system.md)**
+
+    ---
+
+    Generate a complete test and release build environment from a single
+    YAML file. Includes a minimal sample project configuration and an
+    explanation of Ceedling‘s design philosophy.
+
+-   :material-toolbox: **[Tools & Frameworks](tools-and-frameworks.md)**
+
+    ---
+
+    Ruby, Rake, YAML, Unity, and CMock explained — the pieces
+    that make Ceedling possible and how they fit together.
+
+-   :material-test-tube: **[Test Environments](test-environments.md)**
+
+    ---
+
+    Native host builds, emulator-based runs, and on-target execution —
+    choose the right test suite strategy for your project.
+
+</div>
+
+<br/><br/>