### Install Java on Windows (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs OpenJDK on Windows using Chocolatey, a package manager for Windows. Alternatively, users can download the installer from the provided link.

```bash
# Using Chocolatey
choco install openjdk

# Or download from: https://adoptium.net/
```

--------------------------------

### Initialize Sphinx Project with Quickstart

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Initializes a new Sphinx project using the quickstart wizard. This command generates the basic directory structure and configuration files for a Sphinx documentation site.

```bash
uv run sphinx-quickstart docs
```

--------------------------------

### Install Java on Ubuntu/Debian (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs the default Java Runtime Environment (JRE) on Ubuntu or Debian-based systems using the apt package manager.

```bash
sudo apt update
sudo apt install default-jre
```

--------------------------------

### Install System Dependencies (GitHub Actions)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs necessary system packages like Java (default-jre) and Graphviz for documentation generation within a GitHub Actions workflow.

```bash
sudo apt-get update
sudo apt-get install -y default-jre graphviz
```

--------------------------------

### Project Structure Example (Text)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Illustrates a typical project directory structure after setting up documentation with Sphinx, PlantUML, and GitHub Actions.

```text
my-docs-project/
├── docs/
│   ├── conf.py              # PlantUML configuration
│   ├── ubproject.toml       # Sphinx-Needs configuration
│   ├── utils/
│   │   └── plantuml.jar     # PlantUML JAR file
│   ├── index.rst
│   └── ...
├── .github/
│   └── workflows/
│       └── docs.yml         # CI/CD workflow
└── pyproject.toml
```

--------------------------------

### Install Python Dependencies with uv (GitHub Actions)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs and synchronizes Python dependencies using the 'uv' package manager in a GitHub Actions workflow.

```bash
pip install uv
uv sync
```

--------------------------------

### Sphinx Quickstart Prompts and Project Structure

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Illustrates the interactive prompts and the resulting file structure after initializing a Sphinx project. It shows the generated directories and key configuration files.

```text
> Separate source and build directories (y/n) [n]: n
> Project name: My Documentation Project
> Author name(s): Your Name
> Project release []: 0.1.0
> Project language [en]: en

my-docs-project/
├── docs/
│   ├── conf.py          # Sphinx configuration (Python)
│   ├── index.rst        # Root document with toctree
│   ├── make.bat         # Windows build script
│   ├── Makefile         # Unix build script
│   ├── _build/          # Generated output (gitignore this)
│   ├── _static/         # Static files (CSS, images)
│   └── _templates/      # Custom templates
├── .venv/
└── pyproject.toml
```

--------------------------------

### Install sphinxcontrib-plantuml (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs the 'sphinxcontrib-plantuml' Python package using 'uv', a Python package installer. This extension integrates PlantUML rendering capabilities into Sphinx.

```bash
uv add sphinxcontrib-plantuml
```

--------------------------------

### Install Java on macOS (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs OpenJDK on macOS using Homebrew. It also includes steps to add the Java executable to the PATH environment variable for Apple Silicon Macs.

```bash
# Using Homebrew
brew install openjdk

# Add to PATH (for Apple Silicon Macs)
echo 'export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Add Java to PATH (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

An example bash command to add a specific Java installation directory to the system's PATH environment variable, often needed on macOS.

```bash
export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"
```

--------------------------------

### Verify Graphviz Installation (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Checks if Graphviz is installed correctly by running the 'dot' command and displaying its version information. This confirms the layout engine is accessible.

```bash
dot -version
```

--------------------------------

### Install Graphviz on Windows (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs Graphviz on Windows using Chocolatey. This is a dependency for certain advanced diagram types generated by PlantUML.

```bash
choco install graphviz
```

--------------------------------

### GitHub Actions Workflow for Building Documentation

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Provides an example GitHub Actions workflow file (`.github/workflows/docs.yml`) for automatically building documentation on push or pull request events. It includes steps for checking out code and setting up Python.

```yaml
# .github/workflows/docs.yml
name: Build Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python

```

--------------------------------

### Live Preview Sphinx Documentation (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

This bash command installs and runs sphinx-autobuild for live preview of the documentation during development. It automatically rebuilds the documentation and refreshes the browser when files change.

```bash
uv add sphinx-autobuild
uv run sphinx-autobuild docs docs/_build/html
```

--------------------------------

### Install Furo Theme for Sphinx

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Installs the Furo theme using the 'uv' package manager. This theme is a popular choice for Sphinx documentation projects, offering a modern and clean look. After installation, you need to configure Sphinx to use it.

```bash
uv add furo
```

--------------------------------

### Dockerfile for Documentation Build

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

A Dockerfile to create an environment for building documentation, including system dependencies, PlantUML, and Python package installation.

```dockerfile
FROM python:3.12-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    default-jre \
    graphviz \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Download PlantUML
RUN curl -L -o /opt/plantuml.jar \
    https://github.com/plantuml/plantuml/releases/download/v1.2024.8/plantuml-1.2024.8.jar

ENV PLANTUML_JAR=/opt/plantuml.jar

WORKDIR /docs

# Install Python dependencies
COPY pyproject.toml .
RUN pip install uv && uv sync

CMD ["uv", "run", "sphinx-build", "-b", "html", ".", "_build/html"]
```

--------------------------------

### Install Graphviz on Ubuntu/Debian (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs Graphviz on Ubuntu or Debian-based systems using the apt package manager. This is required for specific PlantUML diagram layouts.

```bash
sudo apt install graphviz
```

--------------------------------

### Run Docker Container with Runtime Environment Variables for License

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Starts a Docker container and passes UBCODE license key and user as environment variables at runtime. This is suitable for temporary configurations or when building images.

```bash
docker run -e UBCODE_LICENSE_KEY="AAAAA-BBBBB-CCCCC-DDDDD" \
           -e UBCODE_LICENSE_USER="your.email@example.com" \
           your-image:tag
```

--------------------------------

### Execute Full Project Build Script

Source: https://github.com/useblocks/x-as-code/blob/main/README.md

This script performs a comprehensive build of the project, including documentation, the C++ executable, and running unit tests. It's recommended for initial setup or complete rebuilds.

```shell
./scripts/build.sh
```

--------------------------------

### Check Java Installation (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Verifies if Java Runtime Environment (JRE) version 8 or higher is installed on the system. This is a prerequisite for PlantUML.

```bash
java -version
```

--------------------------------

### Verify PlantUML Installation (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Tests the PlantUML installation by running the JAR file with the '-testdot' option. This command verifies that PlantUML can communicate with Graphviz for diagram layout.

```bash
java -jar docs/utils/plantuml.jar -testdot
```

--------------------------------

### Serve Generated HTML Files with HTTP Server

Source: https://github.com/useblocks/x-as-code/blob/main/README.md

This script starts an HTTP server to serve the generated HTML files. It's particularly useful when developing within GitHub Codespaces, allowing you to view the documentation in a browser.

```shell
./scripts/run_http_server.sh
```

--------------------------------

### Install Sphinx and sphinx-needs Dependencies

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Adds Sphinx and sphinx-needs to the project's dependencies using the 'uv' package manager. This ensures the documentation generator and the requirements management extension are installed with specific versions.

```bash
uv add sphinx==8.3.0 sphinx-needs==6.3.0
```

--------------------------------

### Setup Python Environment (GitHub Actions)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Configures the Python environment for a GitHub Actions workflow, specifying the Python version to be used for subsequent steps.

```yaml
uses: actions/setup-python@v5
with:
  python-version: '3.12'
```

--------------------------------

### Test PlantUML Version (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

A bash command to test the PlantUML installation by checking its version.

```bash
java -jar docs/utils/plantuml.jar -version
```

--------------------------------

### Example Directory Structure for Draw.io Diagrams

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/drawio/index.rst

Illustrates a recommended directory structure for organizing Draw.io source files and their HTML exports within a Sphinx documentation project.

```text
docs/
├── how-to-guides/
│   └── my-guide/
│       ├── index.rst
│       └── _diagrams/
│           ├── workflow.drawio           # Source file
│           ├── workflow.drawio.html      # Exported HTML
│           ├── architecture.drawio
│           └── architecture.drawio.html
```

--------------------------------

### Install Graphviz on macOS (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Installs Graphviz on macOS using Homebrew. Graphviz is recommended for certain PlantUML diagram types like class and component diagrams.

```bash
brew install graphviz
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Installs the 'uv' package and project manager using a script. This tool is a fast alternative to pip and manages Python environments and dependencies. It is available for macOS/Linux and Windows.

```bash
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Check Sphinx Build Version

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Verifies the installed version of the Sphinx build tool. This is a simple command-line check to ensure Sphinx is available and to identify its version.

```bash
uv run sphinx-build --version
# Output: sphinx-build 8.3.0
```

--------------------------------

### CMake Project Setup with GoogleTest Integration

Source: https://context7.com/useblocks/x-as-code/llms.txt

Configures a CMake project to build libraries and executables, fetch and integrate GoogleTest for unit testing, and set up a custom target to run tests with XML output. It also includes an option to enable code coverage.

```cmake
cmake_minimum_required(VERSION 3.14)
project(eac)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Coverage build option
option(ENABLE_COVERAGE "Enable code coverage" OFF)

if(ENABLE_COVERAGE)
  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage -fprofile-arcs -ftest-coverage")
  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} --coverage")
endif()

# Fetch GoogleTest
include(FetchContent)
FetchContent_Declare(
  googletest
  URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
)
FetchContent_MakeAvailable(googletest)

# Library with code to test
add_library(samples sample1.cpp sample2.cpp)

# Test executable
add_executable(eac_test
  eac_test.cpp
  sample1_unittest.cpp
  sample2_unittest.cpp
)

target_link_libraries(eac_test samples GTest::gtest_main)

# Custom target to run tests with XML output
add_custom_target(run_tests
  COMMAND ${CMAKE_CURRENT_BINARY_DIR}/eac_test --gtest_output=xml:${CMAKE_CURRENT_BINARY_DIR}/test-results.xml
  DEPENDS eac_test
  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
)
```

--------------------------------

### Create a Needflow Diagram with Configuration Presets

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

These `needflow` examples demonstrate applying predefined configuration styles ('monochrome' and 'lefttoright') to flow diagrams for needs tagged 'dashboard_demo'.

```rst
.. needflow:: Monochrome Flow
   :filter: 'dashboard_demo' in tags
   :config: monochrome

.. needflow:: Left to Right Flow
   :filter: 'dashboard_demo' in tags
   :config: lefttoright
```

--------------------------------

### Document System Context using Sphinx-Needs

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/arc42/index.rst

This example shows the basic structure for documenting the system context using the `arch` directive with the `System Context` title and a unique ID.

```rst
.. arch:: System Context
   :id: ARCH_CTX_001
```

--------------------------------

### Build and Deploy Documentation with GitHub Actions (YAML)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/github_actions/index.rst

This workflow automates the process of building documentation and deploying it to GitHub Pages. It utilizes standard GitHub Actions steps for checkout, setup, build, and deployment. No external dependencies beyond the GitHub Actions environment are required.

```yaml
name: Build and Deploy Documentation

# Controls when the workflow will run
# For now, trigger the workflow on push to the main branch
# and on pull request events

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This job builds and deploys the documentation
  build-and-deploy:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    # See, for more information on github-actions, see:
    # https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Checkout
        uses: actions/checkout@v3

      # Sets up the Python environment for the documentation build
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      # Installs the necessary dependencies for the documentation build
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      # Builds the documentation using Sphinx
      - name: Build documentation
        run: |
          make html

      # Deploys the documentation to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $secrets.GITHUB_TOKEN
          publish_dir: ./_build/html

```

--------------------------------

### DevContainer Configuration for VS Code

Source: https://context7.com/useblocks/x-as-code/llms.txt

Defines the configuration for a DevContainer used with VS Code. It specifies the base image, post-creation commands, and VS Code extensions to install, along with remote environment variables for license keys.

```json
{
  "name": "X-as-Code DevContainer",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "postCreateCommand": "./scripts/postCreateCommand.sh",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "useblocks.ubcode"
      ]
    }
  },
  "remoteEnv": {
    "UBCODE_LICENSE_KEY": "${localEnv:UBCODE_LICENSE_KEY}",
    "UBCODE_LICENSE_USER": "${localEnv:UBCODE_LICENSE_USER}"
  }
}
```

--------------------------------

### Structured JSON Logging Example

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/arc42/index.rst

Demonstrates the format of structured JSON logs used across all services. It includes fields for correlation IDs, log levels, and timestamps, facilitating centralized logging and request tracing.

```json
{
   "error": {
      "code": "BUILD_FAILED",
      "message": "Documentation build failed",
      "details": "Sphinx error: ...",
      "timestamp": "2025-11-12T10:30:00Z",
      "trace_id": "abc123"
   }
}
```

--------------------------------

### Mermaid Sequence Diagram Example

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/mermaid/index.rst

This snippet demonstrates how to create a basic sequence diagram using Mermaid syntax within a Sphinx document. Ensure the 'sphinxcontrib-mermaid' extension is installed and configured.

```mermaid
sequenceDiagram
   participant Alice
   participant Bob
   Alice->John: Hello John, how are you?
   loop Healthcheck
       John->John: Fight against hypochondria
   end
   Note right of John: Rational thoughts <br/>prevail...
   John-->Alice: Great!
   John->Bob: How about you?
   Bob-->John: Jolly good!
```

--------------------------------

### Create a Needflow Diagram using Graphviz Engine

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

This `needflow` example utilizes the Graphviz engine for complex flow diagrams, visualizing needs tagged 'dashboard_demo' with specific link types and showing link names. Requires Graphviz installation.

```rst
.. needflow:: Graphviz Flow
   :filter: 'dashboard_demo' in tags
   :engine: graphviz
   :link_types: tests, links
   :show_link_names:
```

--------------------------------

### Build Sphinx Documentation (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

These bash commands demonstrate how to build the HTML documentation for the project using Sphinx. It includes instructions for building from the project root or the docs directory, and how to open the generated documentation.

```bash
# From the project root
uv run sphinx-build -b html docs docs/_build/html

# Or from the docs directory using make
cd docs
uv run make html

# macOS
open docs/_build/html/index.html

# Linux
xdg-open docs/_build/html/index.html

# Windows
start docs/_build/html/index.html
```

--------------------------------

### Build Documentation with Sphinx (GitHub Actions)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Builds the project documentation using Sphinx, with warnings treated as errors (-W), and outputs HTML to a specified directory.

```bash
uv run sphinx-build -W -b html docs docs/_build/html
```

--------------------------------

### Create Project Directory

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Creates a new directory for the documentation project and navigates into it. This is the first step in setting up a new Sphinx-needs documentation site.

```bash
mkdir my-docs-project
cd my-docs-project
```

--------------------------------

### Docker Run with Environment File for License

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Launches a Docker container using an environment file to set license-related environment variables. Ensure the '.env' file is correctly formatted and accessible.

```bash
docker run --env-file .env your-image:tag
```

--------------------------------

### Documentation Build Script

Source: https://context7.com/useblocks/x-as-code/llms.txt

Generates HTML documentation using Sphinx and its extensions. It first synchronizes Python dependencies using uv and then runs sphinx-build with warnings treated as errors. An alternative direct command is also provided.

```bash
# Build documentation only
./scripts/build_doc.sh

# The script performs:
# 1. Syncs Python dependencies via uv
# 2. Runs sphinx-build with warnings as errors (-W flag)
# Output: docs/_build/html/index.html

# Alternative: Direct sphinx-build command
uv run sphinx-build -a -E -W -b html docs docs/_build/html
```

--------------------------------

### Creating Configuration File in a Running Container (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

This bash snippet shows how to create a TOML configuration file for licenses within a running Docker container. It uses `mkdir -p` to ensure the directory exists and `cat` with a heredoc to write the file content.

```bash
# Or create the configuration file
mkdir -p ~/.config/ubcode
cat > ~/.config/ubcode/ubcode.toml << 'EOF'
[license]
key = "AAAAA-BBBBB-CCCCC-DDDDD"
user = "your.email@example.com"
EOF
```

--------------------------------

### Install Graphviz for Diagram Generation

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Provides commands to install the Graphviz system package on macOS, Ubuntu/Debian, and Windows. Graphviz is a dependency for rendering diagrams with the 'needflow' directive in Sphinx-Needs when using the 'graphviz' engine.

```bash
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt install graphviz

# Windows (via chocolatey)
choco install graphviz
```

--------------------------------

### Install Sphinx-Needs with uv

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Installs a specific version (6.3.0) of the 'sphinx-needs' package using the 'uv' package manager. This command ensures you have the correct version for compatibility and to avoid potential issues with older versions.

```bash
uv add sphinx-needs==6.3.0
```

--------------------------------

### Sphinx Build Commands (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Provides common bash commands for building Sphinx documentation in various formats (HTML, PDF), with options for live reload, cleaning, and error checking.

```bash
# Build HTML documentation
uv run sphinx-build -b html docs docs/_build/html

# Build with live reload (requires sphinx-autobuild)
uv run sphinx-autobuild docs docs/_build/html

# Clean build directory
rm -rf docs/_build

# Build with warnings as errors (useful for CI)
uv run sphinx-build -W -b html docs docs/_build/html

# Check for broken links
uv run sphinx-build -b linkcheck docs docs/_build/linkcheck

# Generate PDF (requires LaTeX)
uv run sphinx-build -b latex docs docs/_build/latex
cd docs/_build/latex && make
```

--------------------------------

### View Generated HTML Documentation

Source: https://github.com/useblocks/x-as-code/blob/main/README.md

This command opens the generated HTML documentation files in the default web browser. It requires the documentation to be built first.

```shell
"$BROWSER" docs/_build/html/index.html
```

--------------------------------

### Configure ubCode License (TOML)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Sets up the ubCode license using a TOML configuration file. Replace placeholder values with your actual license key and user email.

```toml
[license]
key = "AAAAA-BBBBB-CCCCC-DDDDD"
user = "your.email@example.com"
```

--------------------------------

### Full Project Build Script

Source: https://context7.com/useblocks/x-as-code/llms.txt

Executes a comprehensive build process for the entire project, including C++ compilation, running unit tests, and generating Sphinx documentation. This script is intended for a full project lifecycle build.

```bash
# Full build - compiles C++, runs tests, generates documentation
./scripts/build.sh

# Expected output:
# ============================================
# Full Build: C++ Project + Documentation
# Project Root: /path/to/project
# ============================================
# [CMake configuration output]
# [Test execution output]
# [Sphinx build output]
# Full build completed successfully!
```

--------------------------------

### Debug PlantUML Code Generation (RST)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

An example of using the ':debug:' option in a Sphinx directive to output the generated PlantUML code for debugging.

```rst
.. needflow::
   :filter: type == 'req'
   :debug:
```

--------------------------------

### Create ubCode Configuration Directory (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Creates the necessary directory for ubCode configuration files on Linux systems. This is a prerequisite for setting up the ubcode.toml file.

```bash
# For ubCode
mkdir -p ~/.config/ubcode
```

--------------------------------

### ReadTheDocs Configuration (YAML)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Specifies the build configuration for ReadTheDocs, including the operating system, Python version, system packages, and Python installation method.

```yaml
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  apt_packages:
    - default-jre
    - graphviz

python:
  install:
    - method: pip
      path: .
```

--------------------------------

### Initialize Python Project with uv

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Initializes a new Python project using the 'uv' package manager, specifying the Python version. It also automatically creates and manages a virtual environment.

```bash
# Initialize project with Python 3.12
uv init --python 3.12

# Create virtual environment (uv manages this automatically)
uv venv

# On macOS/Linux, activate it:
source .venv/bin/activate

# On Windows:
# .venv\Scripts\activate
```

--------------------------------

### Configure Source Code Tracing with TOML

Source: https://context7.com/useblocks/x-as-code/llms.txt

Configuration file in TOML format for setting up bidirectional traceability between documentation and C++ source code. Defines project settings, source discovery, and analysis options.

```toml
# docs/src_trace.toml - Source code tracing configuration
[codelinks]
set_local_url = false
local_url_field = "local"
set_remote_url = true
remote_url_field = "remote-url"

[codelinks.projects.eac-cpp]
remote_url_pattern = "https://github.com/useblocks/eac/blob/{commit}/{path}#L{line}"

[codelinks.projects.eac-cpp.source_discover]
src_dir = "../src"
include = ["*.cpp", "*.h"]
exclude = []
gitignore = true
comment_type = "cpp"

[codelinks.projects.eac-cpp.analyse]
get_need_id_refs = true
get_oneline_needs = true
get_rst = true

[codelinks.projects.eac-cpp.analyse.oneline_comment_style]
field_split_char = ","
needs_fields = [
   { "name" = "title", "type" = "str" },
   { "name" = "id", "type" = "str" },
   { "name" = "type", "type" = "str", "default" = "impl" },
   { "name" = "links", "type" = "list[str]", "default" = [] },
]

```

--------------------------------

### Defining Specifications with .. spec::

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

This snippet illustrates how to define a technical specification using the `.. spec::` directive, including API details and request/response examples.

```APIDOC
## Defining Specifications

### Description
Defines a technical specification using the `.. spec::` directive, often used to detail API endpoints, request bodies, and responses.

### Method
N/A (RST directive)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```rst
.. spec:: Login API Specification
   :id: SPEC_001
   :status: open
   :implements: REQ_001

   **Endpoint**: ``POST /api/v1/auth/login``

   **Request Body**:

   .. code-block:: json

      {
        "username": "string",
        "password": "string"
      }

   **Success Response** (200):
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Upload Documentation Artifact (GitHub Actions)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Uploads the generated HTML documentation as a build artifact in GitHub Actions for later retrieval or deployment.

```yaml
uses: actions/upload-artifact@v4
with:
  name: documentation
  path: docs/_build/html
```

--------------------------------

### Create a Needgantt Chart with Milestones

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

This `needgantt` example creates a timeline with milestones, filtering needs tagged 'gantt_demo' and specifically highlighting those where the status is 'done' as milestones.

```rst
.. needgantt:: Timeline with Milestones
   :filter: 'gantt_demo' in tags
   :milestone_filter: status == 'done'
```

--------------------------------

### Build Project Documentation

Source: https://github.com/useblocks/x-as-code/blob/main/README.md

This script focuses solely on building the documentation for the project, which is generated using Sphinx and Sphinx-Needs. It's ideal for updating or viewing the latest documentation.

```shell
./scripts/build_doc.sh
```

--------------------------------

### Add .env to .gitignore

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Appends the '.env' filename to the '.gitignore' file to prevent accidental commitment of sensitive license credentials to version control.

```bash
echo ".env" >> .gitignore
```

--------------------------------

### Create a Needflow Diagram with Filtered Link Types

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

This `needflow` example visualizes traceability by filtering needs tagged 'dashboard_demo' and specifically showing 'tests' relationship types.

```rst
.. needflow:: Test Coverage
   :filter: 'dashboard_demo' in tags
   :link_types: tests
```

--------------------------------

### Create ubConnect Configuration Directory (Bash)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/licensing-setup.rst

Creates the necessary directory for ubConnect configuration files on Linux systems. This is a prerequisite for setting up the ubconnect.toml file.

```bash
# For ubConnect
mkdir -p ~/.config/ubconnect
```

--------------------------------

### Create a Basic Needflow Diagram

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

The `needflow` directive generates flow diagrams to visualize relationships between needs, essential for traceability. This basic example shows all needs tagged with 'dashboard_demo'.

```rst
.. needflow:: Traceability
   :filter: 'dashboard_demo' in tags
```

--------------------------------

### Environment Variables for ubCode Extension

Source: https://context7.com/useblocks/x-as-code/llms.txt

Sets environment variables required for the ubCode VS Code extension. These variables, UBCODE_LICENSE_KEY and UBCODE_LICENSE_USER, should be configured for the extension to function correctly. For GitHub Codespaces, these should be set as repository secrets.

```bash
# Required for ubCode extension functionality
export UBCODE_LICENSE_KEY="your-license-key"
export UBCODE_LICENSE_USER="your-email@example.com"

# For GitHub Codespaces, configure as repository secrets:
# Settings -> Codespaces -> Codespace user secrets
```

--------------------------------

### Document Stakeholders using Sphinx-Needs

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/arc42/index.rst

This example shows how to document stakeholders using the `spec` Sphinx-Needs directive. Each stakeholder entry includes an ID, tags, and detailed expectations and influence.

```rst
.. spec:: Product Owner
   :id: STAKE_001
   :tags: stakeholder

   **Expectations**: Feature completeness, time-to-market, ROI
   
   **Influence**: High - Sets priorities and acceptance criteria

.. spec:: Development Team
   :id: STAKE_002
   :tags: stakeholder

   **Expectations**: Clear requirements, technical feasibility, maintainable codebase
   
   **Influence**: High - Implements and maintains the system
```

--------------------------------

### Build C++ Application and Run Tests

Source: https://github.com/useblocks/x-as-code/blob/main/README.md

This script is specifically for building the C++ project and executing its associated tests. It's useful for targeted development of the C++ components.

```shell
./scripts/build_app.sh
```

--------------------------------

### Annotate Source Code (C++)

Source: https://github.com/useblocks/x-as-code/blob/main/docs/how-to-guides/trace-code/index.rst

Example of annotating C++ source code with comments to link specific lines to documentation needs. These comments are parsed by CodeLinks to establish traceability.

```cpp
// src/main.cpp

// Need: REQ_001 - Initialize the system
void initialize_system() {
    // ... implementation ...
}

// Need: REQ_002 - Process user input
void process_input(const std::string& input) {
    // ... implementation ...
}

```

--------------------------------

### Create needsequence Diagrams with PlantUML

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/plantuml-setup.rst

Shows how to generate sequence diagrams using the `needsequence` directive, starting from a specified need. This helps visualize the interaction flow between different components or requirements.

```rst
.. needsequence:: Login Sequence
   :start: SPEC_001
```

--------------------------------

### Configure Sphinx to Use Furo Theme

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Sets the 'furo' theme as the active theme in your Sphinx project's configuration file (conf.py). This step is necessary after installing the theme to apply its styling to your documentation.

```python
html_theme = 'furo'
```

--------------------------------

### Clean Build Directory and Rebuild Documentation

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/sphinx-needs-setup.rst

Removes the Sphinx build directory and then rebuilds the documentation using 'uv run sphinx-build'. This is a common troubleshooting step to ensure changes are reflected and to clear any stale build artifacts.

```bash
rm -rf docs/_build
uv run sphinx-build -b html docs docs/_build/html
```

--------------------------------

### Create a Static Needbar Chart

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

This example demonstrates using the `needbar` directive with static data instead of filters. It creates a bar chart showing planned and completed counts for three sprints.

```rst
.. needbar:: Sprint Progress
   :legend:
   :xlabels: Sprint 1, Sprint 2, Sprint 3

   Planned; 10; 12; 8
   Completed; 10; 11; 5
```

--------------------------------

### Create a Needflow Diagram Showing Link Names

Source: https://github.com/useblocks/x-as-code/blob/main/docs/tutorials/creating-dashboards.rst

This `needflow` example visualizes traceability for needs tagged 'dashboard_demo', showing 'tests' and 'links' relationship types, and displaying the names of these links on the arrows.

```rst
.. needflow:: Detailed Traceability
   :filter: 'dashboard_demo' in tags
   :link_types: tests, links
   :show_link_names:
```