docs: Complete MkDocs Material documentation revamp with Diátaxis framework (#191)

## Documentation Revamp — MkDocs Material

Complete rewrite of NUClear's documentation using MkDocs Material,
replacing the old Sphinx/RST docs.

### What Changed

- **Removed old Sphinx docs** — `docs/` previously contained RST files,
`conf.py`, `Doxyfile`, etc. All removed.
- **New documentation in `docs/`** — 73 Markdown files organized into
sections:
  - `getting-started/` — installation, quick-start guide
- `concepts/` — core architecture (reactors, reactions, DSL, threading,
networking)
- `how-to/` — task-oriented guides (logging, IO, testing, TCP/UDP,
watchdogs, etc.)
- `reference/` — complete DSL word reference, emit scopes, extension
points
  - `contributing/` — development setup, style guide
- **MkDocs Material configuration** (`mkdocs.yml`) — theme, navigation,
mkdoxy plugin for API docs, mermaid diagrams
- **Python tooling** — `pyproject.toml` with `uv` dependency groups for
docs and dev; `uv.lock` for reproducible builds; `mdformat` for
consistent Markdown formatting
- **Read the Docs** — `.readthedocs.yaml` configured for MkDocs builds
- **Git hygiene** — `.gitignore` updated for `.venv/` and `site/`

### Documentation Structure

```
docs/
├── index.md                    # Landing page
├── getting-started/            # Installation & quick start
├── concepts/                   # Architecture deep-dives
├── how-to/                     # Task-oriented guides
├── reference/                  # DSL, emit, extensions reference
│   ├── dsl/                    # All DSL words (Trigger, With, Every, etc.)
│   ├── emit/                   # Emit scopes (Local, Direct, Network, etc.)
│   └── extensions/             # Extension system & points
├── contributing/               # Dev setup & style guide
└── api/                        # mkdoxy-generated C++ API reference
```

### Build & Preview

```bash
uv sync --group docs
uv run mkdocs serve
```

### Formatting

All Markdown files are formatted with `mdformat` (config in
`pyproject.toml`):

```bash
uv sync --group dev
uv run mdformat docs/
```

Author: TrentHouliston

.github/copilot-instructions.md

@@ -0,0 +1,131 @@
+# GitHub Copilot Instructions
+
+This repository contains NUClear — a C++ reactive framework for robot software.
+
+## Project Overview
+
+NUClear is a C++14 message-passing framework built around reactive programming.
+Reactors define event-driven callbacks using a domain-specific language (DSL) of template words.
+The framework handles threading, scheduling, and data routing automatically.
+
+### Core Components
+
+- **PowerPlant**: Top-level container that manages the system lifecycle
+- **Reactor**: Base class for user modules that define reactions
+- **DSL Words**: Template parameters that define triggering and data access (`Trigger`, `With`, `Every`, etc.)
+- **Threading**: Pool-based scheduler with priority queuing and group synchronisation
+- **Extensions**: Plugin system for IO, networking, timers, and tracing
+
+### Build System
+
+- CMake with C++14 target (`cxx_std_14`)
+- Catch2 for unit testing (fetched via CMake)
+- Platform support: Linux, macOS, Windows
+
+## Code Quality Standards
+
+- **Language Standard**: C++14 (do not use C++17 or later features)
+- **Formatting**: clang-format
+- **Linting**: clang-tidy (config in `cmake/ClangTidy.cmake`)
+- **Testing**: Catch2, run via CTest
+- **Language**: American English for all code, comments, and documentation
+
+### Code Style
+
+- **Clean Changes**: When making changes don't leave behind comments describing what was once there; comments should always describe code as it exists
+- **API Evolution**: When making changes don't leave behind backwards-compatible interfaces for internal APIs; there should always be a complete clean changeover
+- **Property Access**: Assume fields that should exist do exist directly; rely on errors if they don't rather than adding unnecessary null checks
+
+## Documentation Standards
+
+Documentation lives in `docs/` and is built with MkDocs Material.
+All documentation files are Markdown.
+
+### Markdown Formatting
+
+- **Formatter**: mdformat (config in `pyproject.toml`)
+- **Semantic Line Breaks**: Follow the [Semantic Line Breaks specification (SemBr)](https://sembr.org/)
+  - One sentence per line
+  - Break after sentences (`.`, `!`, `?`)
+  - Break after independent clauses (`,`, `;`, `:`, `—`) when it improves readability
+  - Break after dependent clauses for clarity when lines are long
+  - **Never break lines based on column count**
+  - If a line exceeds ~120 characters, consider simplifying the prose rather than wrapping mid-sentence
+  - Example:
+    ```markdown
+    NUClear is a reactive framework for building modular robot software.
+    It uses a domain-specific language embedded in C++ templates to define event-driven callbacks.
+
+    Each module is a Reactor that declares what data it needs,
+    and the framework handles threading and scheduling automatically.
+    ```
+
+### Writing Style
+
+- **Tone**: Friendly and informative
+- **Perspective**: Use second-person ("you" and "your") for user-facing documentation
+- **Language**: American English with sentence case for titles
+- **Clarity**: Write for non-native English speakers; avoid jargon without explanation
+- **Formatting in prose**:
+  - Use backticks for: type names, function names, file paths, DSL words, template parameters
+  - Use sentence case for headings (capitalize only the first word and proper nouns)
+  - Avoid abbreviations when possible
+
+### Documentation Structure (Diátaxis)
+
+The docs follow the [Diátaxis framework](https://diataxis.fr/):
+
+| Section        | Purpose                              | Path               |
+| -------------- | ------------------------------------ | ------------------ |
+| Getting started | Tutorials for new users             | `getting-started/` |
+| Concepts       | Explanation of architecture          | `concepts/`        |
+| How-to guides  | Task-oriented recipes                | `how-to/`          |
+| Reference      | Complete DSL/API reference           | `reference/`       |
+| Explanation    | Deep-dive background material        | `explanation/`     |
+| Contributing   | Developer setup and style guide      | `contributing/`    |
+
+### Code Examples in Documentation
+
+- All C++ examples should compile conceptually (correct syntax, proper includes)
+- Use `#include "nuclear"` as the canonical include
+- Examples should be self-contained where possible
+- Verify API usage against source code — do not guess signatures or return types
+
+### Documentation Tooling
+
+```bash
+# Install docs dependencies
+uv sync --group docs
+
+# Preview documentation
+uv run mkdocs serve
+
+# Format all markdown files
+uv sync --group dev
+uv run mdformat docs/
+```
+
+## Development Workflow
+
+### Building
+
+```bash
+mkdir build && cd build
+cmake .. -GNinja
+ninja
+```
+
+### Testing
+
+```bash
+cd build
+ctest
+```
+
+### Documentation Development
+
+```bash
+uv sync --group docs --group dev
+uv run mkdocs serve        # Live preview at http://127.0.0.1:8000
+uv run mdformat docs/      # Format markdown
+```

.github/workflows/linting.yaml

@@ -97,3 +97,20 @@ jobs:
 
       - name: CTCache Stats
         run: clang-tidy-cache --show-stats
+
+  markdown-format:
+    name: Markdown Formatting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Check markdown formatting
+        run: uv run mdformat --check docs/

.gitignore

@@ -28,3 +28,7 @@ docs/doxygen
 docs/doxygen_sqlite3.db
 *.sublime-workspace
 .DS_Store
+site/
+.venv/
+
+site/

.readthedocs.yaml

@@ -1,22 +1,18 @@
-# .readthedocs.yaml
 # Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
 
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
+  apt_packages:
+    - doxygen
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml
 
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-  - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

.vscode/settings.json

@@ -15,5 +15,68 @@
   "sonarlint.connectedMode.project": {
     "connectionId": "fastcode",
     "projectKey": "Fastcode_NUClear"
+  },
+  "files.associations": {
+    "__bit_reference": "cpp",
+    "__config": "cpp",
+    "__hash_table": "cpp",
+    "__locale": "cpp",
+    "__node_handle": "cpp",
+    "__split_buffer": "cpp",
+    "__threading_support": "cpp",
+    "__tree": "cpp",
+    "__verbose_abort": "cpp",
+    "array": "cpp",
+    "bitset": "cpp",
+    "cctype": "cpp",
+    "charconv": "cpp",
+    "clocale": "cpp",
+    "cmath": "cpp",
+    "complex": "cpp",
+    "condition_variable": "cpp",
+    "csignal": "cpp",
+    "cstdarg": "cpp",
+    "cstddef": "cpp",
+    "cstdint": "cpp",
+    "cstdio": "cpp",
+    "cstdlib": "cpp",
+    "cstring": "cpp",
+    "ctime": "cpp",
+    "cwchar": "cpp",
+    "cwctype": "cpp",
+    "deque": "cpp",
+    "execution": "cpp",
+    "fstream": "cpp",
+    "future": "cpp",
+    "initializer_list": "cpp",
+    "iomanip": "cpp",
+    "ios": "cpp",
+    "iosfwd": "cpp",
+    "iostream": "cpp",
+    "istream": "cpp",
+    "limits": "cpp",
+    "list": "cpp",
+    "locale": "cpp",
+    "map": "cpp",
+    "mutex": "cpp",
+    "new": "cpp",
+    "optional": "cpp",
+    "ostream": "cpp",
+    "ratio": "cpp",
+    "regex": "cpp",
+    "set": "cpp",
+    "sstream": "cpp",
+    "stack": "cpp",
+    "stdexcept": "cpp",
+    "streambuf": "cpp",
+    "string": "cpp",
+    "string_view": "cpp",
+    "tuple": "cpp",
+    "typeindex": "cpp",
+    "typeinfo": "cpp",
+    "unordered_map": "cpp",
+    "variant": "cpp",
+    "vector": "cpp",
+    "algorithm": "cpp"
   }
 }