### Initialize Sphinx Project using Quickstart

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

This command initiates the Sphinx documentation generator, creating a source directory and a default configuration file (`conf.py`). It guides the user through setup prompts to define project metadata.

```bash
uv run sphinx-quickstart docs

> 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

```

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

### GitHub Actions CI/CD for Documentation

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Provides a GitHub Actions workflow example (`.github/workflows/docs.yml`) for building documentation. It includes steps for checking out code, setting up Python, installing system and Python dependencies (including PlantUML and Java), and building the documentation.

```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
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y default-jre graphviz

      - name: Download PlantUML
        run: |
          mkdir -p docs/utils
          curl -L -o docs/utils/plantuml.jar \
            https://github.com/plantuml/plantuml/releases/download/v1.2024.8/plantuml-1.2024.8.jar

      - name: Install Python dependencies
        run: |
          pip install uv
          uv sync

      - name: Build documentation
        run: |
          uv run sphinx-build -W -b html docs docs/_build/html

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


```

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

### Install Java (Windows)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Installs OpenJDK on Windows using Chocolatey package manager or by downloading from the official Adoptium website.

```bash
# Using Chocolatey
choco install openjdk

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

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

### Check Java Installation (Shell)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Commands to check if Java is installed and accessible in the system's PATH. Includes an example for macOS to add OpenJDK to the PATH if it's not automatically detected.

```bash
# Check Java installation
java -version

# On macOS, you may need to add to PATH
export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"
```

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

### Install Java (Ubuntu/Debian)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

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

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

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

### Install Java (macOS)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Installs OpenJDK using Homebrew on macOS. Includes adding the Java executable to the PATH 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
```

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

### Install sphinxcontrib-plantuml

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Installs the `sphinxcontrib-plantuml` Python package using uv. This extension facilitates the integration of PlantUML diagrams within Sphinx documentation.

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

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

### Install Graphviz (Windows)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Installs Graphviz on Windows using the Chocolatey package manager. This enables advanced layout capabilities for PlantUML diagrams.

```bash
choco install graphviz
```

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

### Project Structure Example

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Illustrates a typical project structure for documentation using Sphinx and Sphinx-Needs. It includes directories for source files, build output, static assets, templates, and configuration files.

```tree
my-docs-project/
├── docs/
│   ├── conf.py              # Minimal Sphinx config
│   ├── ubproject.toml       # Sphinx-Needs configuration
│   ├── index.rst            # Main page with toctree
│   ├── requirements.rst     # Requirements documentation
│   ├── specifications.rst   # Specifications and test cases
│   ├── traceability.rst     # Traceability views
│   ├── Makefile
│   ├── make.bat
│   ├── _build/
│   │   └── html/
│   │       └── needs.json   # Exported needs data
│   ├── _static/
│   └── _templates/
├── .venv/                   # Virtual environment (gitignore)
├── .python-version
└── pyproject.toml
```

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

### Verify Graphviz Installation

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Checks if Graphviz is installed and accessible from the command line. This command verifies the 'dot' executable.

```bash
dot -version
```

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

### Live Preview with sphinx-autobuild

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Installs and runs `sphinx-autobuild` for live preview of documentation during development. This tool automatically rebuilds the documentation and refreshes the browser when files change.

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

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

### Apply Configuration Presets with needflow

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example shows how to apply predefined styles or configurations to `needflow` diagrams using the `:config:` option. Two examples are provided: 'monochrome' for a grayscale theme and 'lefttoright' for a specific layout direction.

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

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

```

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

### Install Sphinx and sphinx-needs Dependencies

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Adds Sphinx and the sphinx-needs extension to the project's dependencies using uv. This step ensures the necessary tools for documentation generation and requirements management are installed.

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

```

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

### Install Graphviz (Ubuntu/Debian)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

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
```

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

### Install sphinx-needs Package

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Installs the 'sphinx-needs' package using 'uv', a fast Python package installer and resolver. This command is used to resolve 'Module sphinx_needs not found' errors.

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

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

### Verify Sphinx Build Version

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Verifies the installed version of the Sphinx build tool using uv to ensure the correct version is active in the environment. This confirms the successful installation of Sphinx.

```shell
uv run sphinx-build --version

```

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

### Check Java Installation

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

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

```bash
java -version
```

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

### Install Graphviz for Diagram Rendering

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Provides commands to install the Graphviz system package on macOS, Ubuntu/Debian, and Windows. Graphviz is a rendering engine for needflow diagrams.

```bash
# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt install graphviz

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

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

### Component Interaction Example

Source: https://x-as-code.useblocks.com/how-to-guides/arc42/index

Illustrates the interaction between different system components. This example shows a basic interaction flow, likely involving requests and responses between services.

```text

```

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

### Verify PlantUML Installation

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Tests the PlantUML JAR installation by running a check command. This command also verifies if Graphviz is correctly configured and accessible by PlantUML.

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

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

### Install uv Package Manager

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Installs the uv package and project manager, a fast alternative to pip, for macOS/Linux and Windows systems. This is a prerequisite for managing Python dependencies.

```shell
# 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"

```

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

### Add Furo Theme (Shell)

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Installs the 'furo' theme for Sphinx documentation using the `uv add` command. This theme can enhance the visual appearance of the generated documentation.

```shell
uv add furo

```

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

### Install Graphviz (macOS)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

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

```bash
brew install graphviz
```

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

### Docker Compose for DevContainer Setup

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Defines a Docker Compose service for a DevContainer, specifying the build context, Dockerfile, volume mounts for code synchronization, and environment file for license configuration. This is suitable for complex development environments.

```yaml
version: '3.8'
services:
  devcontainer:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
    env_file:
      - ../.env.devcontainer
    # Alternatively, use environment directly:
    # environment:
    #   - UBCODE_LICENSE_KEY=${UBCODE_LICENSE_KEY}
    #   - UBCODE_LICENSE_USER=${UBCODE_LICENSE_USER}

```

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

### Dockerfile for Sphinx and PlantUML

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

A Dockerfile to create a consistent build environment for Sphinx documentation that includes PlantUML and necessary system dependencies. It installs Java, downloads PlantUML, sets up Python dependencies using uv, and defines the default command for building HTML documentation.

```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"]
```

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

### CI/CD Workflow for C++ Project Testing

Source: https://x-as-code.useblocks.com/how-to-guides/testing/index

An example GitHub Actions workflow for a C++ project. It includes steps to build the project, run tests generating an XML report, and upload the test results as an artifact.

```yaml
# .github/workflows/test.yml
- name: Build C++ Project
  run: |
    cd src
    cmake -S . -B build
    cmake --build build

- name: Run Tests
  run: |
    cd src/build
    ./eac_test --gtest_output=xml:test-results.xml

- name: Upload Test Results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: src/build/test-results.xml


```

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

### Test PlantUML JAR (Shell)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

A command to directly test the PlantUML JAR file's installation and version. This is useful for troubleshooting if PlantUML is not recognized or failing to execute.

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

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

### Enable Headless Mode for PlantUML (Python)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

An example of configuring the PlantUML command to run in headless mode. This is crucial for environments like CI/CD pipelines where a graphical display is not available, preventing errors related to GUI operations.

```python
plantuml = 'java -Djava.awt.headless=true -jar /path/to/plantuml.jar'
```

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

### Needsequence Diagram Generation

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

Explains how to create sequence diagrams using the `needsequence` directive. It specifies a starting need and follows its links to visualize interactions.

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


```

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

### Create Basic Gantt Chart with needgantt

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example shows the basic usage of the `needgantt` directive to create a project timeline. It filters needs based on the 'gantt_demo' tag to include them in the chart.

```rst
.. needgantt:: Project Timeline
   :filter: 'gantt_demo' in tags

```

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

### GitHub Actions Workflow for Building and Deploying Docs

Source: https://x-as-code.useblocks.com/how-to-guides/github_actions/index

A comprehensive GitHub Actions workflow designed to build C++ code, run tests, generate Sphinx documentation, and deploy it to GitHub Pages. It utilizes various GitHub Actions for checkout, setup, artifact handling, and deployment. Dependencies include C++ build tools, lcov, graphviz, plantuml, and Python with uv.

```yaml
# Workflow for building and deploying the Sphinx site to GitHub Pages
#
name: Deploy docs to GH Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  BUILD_TYPE: Release

jobs:
  cpp-build:
    name: C++ Build and Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: lukka/get-cmake@latest
      
      # Install lcov for coverage support
      - name: Install lcov
        run: sudo apt-get update && sudo apt-get install -y lcov
      
      - name: Build C++ Project with Tests
        working-directory: src
        run: |
          # Configure CMake without coverage for CI (coverage can be added later if needed)
          cmake -B build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
          
          # Build the project
          cmake --build build --config ${{env.BUILD_TYPE}}
      
      - name: Run C++ Tests
        working-directory: src/build
        run: |
          # Run tests with XML output
          ./eac_test --gtest_output=xml:test-results.xml
      
      - name: Upload Test Results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: src/build/test-results.xml
          
  build:
    name: Build Documentation
    runs-on: ubuntu-latest
    needs: cpp-build
    steps:
      - uses: actions/checkout@v5
      
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      
      - name: Download Test Results
        uses: actions/download-artifact@v4
        with:
          name: test-results
          path: src/build
      
      - name: Install System Dependencies
        run: sudo apt-get update && sudo apt-get install -y graphviz plantuml
      
      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
      
      - name: Install Python dependencies
        run: uv sync
      
      - name: Build Sphinx Documentation
        run: uv run sphinx-build -b html docs docs/_build/html 
      
      - name: Upload Documentation Artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: docs/_build/html

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

```

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

### Create Status Overview Pie Chart with needpie

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example shows how to create a pie chart for visualizing the status overview of requirements using the `needpie` directive. It defines labels, colors, and filters needs based on type and status.

```rst
.. needpie:: Requirements Status
   :labels: Open, In Progress, Done
   :legend:
   :colors: #ff6b6b, #ffd93d, #6bcb77

   type == 'req' and status == 'open'
   type == 'req' and status == 'in_progress'
   type == 'req' and status == 'done'

```

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

### Configure String Links in conf.py

Source: https://x-as-code.useblocks.com/how-to-guides/jira/index

This snippet demonstrates how to configure various string links in the Sphinx-Needs settings within the conf.py file. It includes examples for linking to Sphinx-Needs documentation and GitHub issues, showcasing the use of regex, URL templating, and custom options.

```python
# conf.py
needs_string_links = {
    'custom_name': {
        'regex': "...",
        'link_url' : "...",
        'link_name': '...'
        'options': ['status', '...']
    }
}
# Examples
needs_string_links = {
    # Adds link to the Sphinx-Needs configuration page
    'config_link': {
        'regex': r'^(?P<value>\\w+)$',
        'link_url': 'https://sphinx-needs.readthedocs.io/en/latest/configuration.html#{{value | replace("_", "-") }}',
        'link_name': 'Sphinx-Needs docs for {{value | replace("_", "-") }}',
        'options': ['config']
    },
    # Links to the related github issue
    'github_link': {
        'regex': r'^(?P<value>\\w+)$',
        'link_url': 'https://github.com/useblocks/sphinx-needs/issues/{{value}}',
        'link_name': 'GitHub #{{value}}',
        'options': ['github']
    }
}

```

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

### GitLab CI Configuration for Building Docs

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

A GitLab CI job that uses a Python Docker image, sets environment variables from CI/CD variables, installs dependencies, and runs a build command. This configures the build process within GitLab's CI/CD system.

```yaml
build_docs:
  image: python:3.12
  variables:
    UBCODE_LICENSE_KEY: $UBCODE_LICENSE_KEY
    UBCODE_LICENSE_USER: $UBCODE_LICENSE_USER
  script:
    - pip install ubconnect
    - make docs

```

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

### Build HTML Documentation with Sphinx

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Commands to build HTML documentation from Sphinx source files. It shows how to use `sphinx-build` from the project root or `make html` from the docs directory. Also includes commands to open the generated documentation on different operating systems.

```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
```

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

### Create Project Directory

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Creates a new directory for the documentation project and navigates into it. This is the first step in organizing your project files.

```shell
mkdir my-docs-project
cd my-docs-project

```

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

### POST /api/v1/auth/login

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Handles user authentication by accepting credentials and returning an authentication token upon success.

```APIDOC
## POST /api/v1/auth/login

### Description
This endpoint handles user login. It accepts a username and password and returns a JWT token upon successful authentication.

### Method
POST

### Endpoint
/api/v1/auth/login

### Parameters
#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "string",
  "password": "string"
}
```

### Response
#### Success Response (200)
- **token** (string) - The JWT authentication token.
- **expires_in** (integer) - The token's expiration time in seconds.

#### Error Response (401)
- **error** (string) - Description of the error, e.g., "Invalid credentials".

#### Response Example (Success)
```json
{
  "token": "jwt-token-here",
  "expires_in": 3600
}
```

#### Response Example (Error)
```json
{
  "error": "Invalid credentials"
}
```
```

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

### GitHub Actions Workflow for Building Documentation

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

A GitHub Actions workflow that checks out code, sets environment variables for license keys from repository secrets, and runs a build command. This automates the build process in a CI/CD environment.

```yaml
name: Build Documentation
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      UBCODE_LICENSE_KEY: ${{ secrets.UBCODE_LICENSE_KEY }}
      UBCODE_LICENSE_USER: ${{ secrets.UBCODE_LICENSE_USER }}
      UBCONNECT_LICENSE_KEY: ${{ secrets.UBCONNECT_LICENSE_KEY }}
      UBCONNECT_LICENSE_USER: ${{ secrets.UBCONNECT_LICENSE_USER }}
    steps:
      - uses: actions/checkout@v4
      - name: Build docs
        run: |
          # ubCode/ubConnect will pick up the env vars automatically
          make docs

```

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

### Initialize Python Project with uv

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Initializes a new Python project using uv, specifying Python 3.12, and creates a virtual environment. It also shows how to activate the environment on different operating systems.

```shell
# 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

```

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

### Sphinx Build Commands (Shell)

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Provides a collection of common shell commands for building Sphinx documentation. Includes commands for standard HTML builds, live reloads, cleaning the build directory, building with warnings as errors, checking for broken links, and generating PDF output.

```shell
# 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

```

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

### Create ubCode Configuration Directory (Linux)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

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

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

```

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

### Configure ubCode License (TOML)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Sets up the ubCode license using a TOML configuration file. This file should be placed in the platform-specific configuration directory.

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

```

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

### Build and Run Tests with CMake and Generate XML Report

Source: https://x-as-code.useblocks.com/how-to-guides/testing/index

This snippet demonstrates the command-line steps to build a C++ project using CMake, run the tests, and generate a GoogleTest XML report. The XML report is crucial for integrating test results and enabling traceability.

```bash
# Build and run tests
cd src
cmake -S . -B build
cmake --build build
cd build
./eac_test --gtest_output=xml:test-results.xml

```

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

### Set Graphviz as Default Needflow Engine

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Configures Sphinx-Needs to use Graphviz as the default rendering engine for needflow diagrams in 'conf.py'. This can resolve PlantUML setup issues.

```python
needs_flow_engine = "graphviz"
```

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

### Create ubConnect Configuration Directory (Linux)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

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

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

```

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

### Use Reusable Filters in needtable

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example demonstrates how to use the predefined reusable filters defined in `conf.py` within a `needtable` directive. The `:filter: current_sprint` option applies the filter named 'current_sprint'.

```rst
.. needtable:: Sprint Items
   :filter: current_sprint
   :columns: id; title; status

```

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

### Setting Environment Variables in a Running Container

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Demonstrates how to set environment variables for license keys and user information directly within a running Docker container using an interactive bash session. This is useful for debugging or temporary configurations.

```bash
# Enter the container
docker exec -it <container_name> /bin/bash

# Set environment variables for current session
export UBCODE_LICENSE_KEY="AAAAA-BBBBB-CCCCC-DDDDD"
export UBCODE_LICENSE_USER="your.email@example.com"

# 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

```

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

### Add Duration to Needs for Gantt Charts

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This snippet illustrates how to add duration information to needs, which is essential for creating Gantt charts with `needgantt`. It shows examples for `req`, `spec`, and `test` directives, each with an `:duration:` attribute.

```rst
.. req:: Feature Development
   :id: REQ_GANTT_001
   :status: in_progress
   :duration: 5
   :tags: gantt_demo

   Implement the core feature.

.. spec:: API Design
   :id: SPEC_GANTT_001
   :status: done
   :duration: 2
   :tags: gantt_demo
   :links: REQ_GANTT_001

   Design the REST API endpoints.

.. test:: Integration Tests
   :id: TEST_GANTT_001
   :status: open
   :duration: 3
   :tags: gantt_demo
   :tests: SPEC_GANTT_001

   Write integration tests.

```

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

### Define Project Requirements (reStructuredText)

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

This reStructuredText snippet defines project requirements using the Sphinx-Needs 'req' directive. It includes examples of requirement IDs, statuses, priorities, and links between requirements, demonstrating how to structure and document system needs.

```rst
Requirements
============

This section contains all project requirements.

System Requirements
-------------------

.. req:: User Authentication
   :id: REQ_001
   :status: open
   :priority: high
   :author: Your Name

   The system shall provide user authentication functionality.
   Users must be able to log in with username and password.

   **Acceptance Criteria:**

   * Users can register with email and password
   * Users can log in with valid credentials
   * Failed login attempts are logged

.. req:: Data Persistence
   :id: REQ_002
   :status: open
   :priority: high
   :derives: REQ_001

   The system shall persist user data securely in a database.
   This requirement depends on user authentication.

.. req:: Performance Target
   :id: REQ_003
   :status: open
   :priority: medium

   The system shall respond to API requests within 200ms
   under normal load conditions (< 1000 concurrent users).


```

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

### Annotate Source Code for Needs Tracing (C++)

Source: https://x-as-code.useblocks.com/how-to-guides/trace-code/index

Example of C++ source code annotated with comments to link code lines to documentation needs. Uses a specific format for extracting need IDs, types, and links.

```cpp
#include <iostream>

// @Adding two integers, IMPL_1, impl, [REQ_0815]
int add(int a, int b) {
    return a + b;
}

int main() {
  
    std::cout << "Hello World" << std::endl;

    return 0;
}


```

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

### Create ubCode Configuration Directory (macOS)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

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

```bash
# For ubCode
mkdir -p ~/Library/Application\ Support/ubcode

```

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

### Generate Full Traceability Diagram with needflow

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example uses the `needflow` directive to create a comprehensive traceability diagram showing links between different need types. It specifies the link types to include and whether to display link names.

```rst
.. needflow:: Full Traceability
   :link_types: tests, links
   :show_link_names:

```

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

### Set System-Wide ubCode Environment Variables (/etc/environment)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Sets ubCode license key and user environment variables system-wide by adding them to the /etc/environment file. This makes the variables available to all users and requires root privileges. Changes typically require a system reboot or re-login.

```bash
UBCODE_LICENSE_KEY="AAAAA-BBBBB-CCCCC-DDDDD"
UBCODE_LICENSE_USER="your.email@example.com"
```

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

### Create ubCode Configuration Directory (Windows PowerShell)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Creates the necessary directory for ubCode configuration files on a Windows system using PowerShell. This is a prerequisite for setting up the ubcode.toml file.

```powershell
# For ubCode
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\useblocks\ubcode"

```

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

### Enable PlantUML Debug Mode (RST)

Source: https://x-as-code.useblocks.com/tutorials/plantuml-setup

An example of using the `:debug:` option within a Sphinx-Needs directive (`.. needflow::`). This option prints the generated PlantUML code, which can be used to diagnose syntax errors by testing the code directly with the PlantUML JAR.

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

```

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

### Setting Environment Variables in Dockerfile (Not Recommended)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Shows how to set environment variables directly within a Dockerfile using the ENV instruction. This method is not recommended for sensitive information like license keys as they can be exposed in image layers.

```dockerfile
# NOT RECOMMENDED - exposes secrets in image layers
ENV UBCODE_LICENSE_KEY="AAAAA-BBBBB-CCCCC-DDDDD"
ENV UBCODE_LICENSE_USER="your.email@example.com"

```

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

### Basic Need Item Example (Sphinx-Needs)

Source: https://x-as-code.useblocks.com/how-to-guides/writing-requirements/index

This snippet demonstrates the basic structure of a 'need' item in Sphinx-Needs, representing a generic project element like a requirement. It shows how to define the item type, a title, an ID, and a description. No external dependencies are needed beyond Sphinx-Needs itself.

```rst
.. req:: Basic need example
   :id: REQ_42

   A basic example of a need item.
```

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

### Use Graphviz Engine for Complex Diagrams

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This snippet demonstrates how to use the Graphviz engine with the `needflow` directive for generating complex diagrams. It requires Graphviz to be installed on the system. The `:filter:` option selects needs based on tags, and `:engine: graphviz` specifies the rendering engine.

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

```

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

### Linked Need Item Example (Sphinx-Needs)

Source: https://x-as-code.useblocks.com/how-to-guides/writing-requirements/index

This snippet illustrates how to create a 'need' item that links to another existing 'need' item using its ID. It also shows how to assign a status to the need. This functionality is crucial for establishing relationships between different project artifacts managed by Sphinx-Needs.

```rst
.. req:: Requirement linking to another requirement
   :id: REQ_43
   :status: open
   :links_outgoing: REQ_42

   This is a requirement that links to another requirement via its id and has a status.
```

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

### Define Specifications and Test Cases (reStructuredText)

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

This reStructuredText snippet defines technical specifications and test cases using Sphinx-Needs directives 'spec' and 'test'. It includes JSON code blocks for API request/response examples and details test steps and expected results, linking tests to specifications.

```rst
Specifications
==============

Technical specifications derived from requirements.

Authentication Specification
----------------------------

.. 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):

   .. code-block:: json

      {
        "token": "jwt-token-here",
        "expires_in": 3600
      }

   **Error Response** (401):

   .. code-block:: json

      {
        "error": "Invalid credentials"
      }

Test Cases
----------

Test cases verify that specifications are correctly implemented.

.. test:: Login Success Test
   :id: TC_001
   :status: open
   :tests: SPEC_001

   **Preconditions**: User "testuser" exists with password "secret123"

   **Steps**:

   1. Send POST to ``/api/v1/auth/login``
   2. Include body: ``{"username": "testuser", "password": "secret123"}``

   **Expected Result**: 200 response with valid JWT token

.. test:: Login Failure Test
   :id: TC_002
   :status: open
   :tests: SPEC_001

   **Preconditions**: User "testuser" exists

   **Steps**:

   1. Send POST to ``/api/v1/auth/login``
   2. Include body: ``{"username": "testuser", "password": "wrong"}``

   **Expected Result**: 401 response with error message


```

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

### Set Persistent ubCode/ubConnect Environment Variables (.profile)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Sets ubCode and ubConnect license key and user environment variables for login shells by adding them to the ~/.profile file. This method applies to all shell types and requires logging out and back in or sourcing the file.

```bash
# ubCode/ubConnect License Configuration
export UBCODE_LICENSE_KEY="AAAAA-BBBBB-CCCCC-DDDDD"
export UBCODE_LICENSE_USER="your.email@example.com"
```

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

### Create Status by Type Bar Chart with needbar

Source: https://x-as-code.useblocks.com/tutorials/creating-dashboards

This example demonstrates creating a stacked bar chart to show status distribution across different need types (Requirements, Specifications, Tests) using the `needbar` directive. It specifies labels, colors, and filtering conditions for each segment.

```rst
.. needbar:: Status by Type
   :legend:
   :xlabels: Requirements, Specifications, Tests
   :stacked:
   :colors: #6bcb77, #ffd93d, #ff6b6b

   Done; type=='req' and status=='done'; type=='spec' and status=='done'; type=='test' and status=='done'
   In Progress; type=='req' and status=='in_progress'; type=='spec' and status=='in_progress'; type=='test' and status=='in_progress'
   Open; type=='req' and status=='open'; type=='spec' and status=='open'; type=='test' and status=='open'

```

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

### Mount Configuration Files in Docker

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Mounts license configuration files (e.g., `.toml`) from the host system into the Docker container. This is often used for more complex configurations or when managing secrets.

```docker
# For ubCode (Linux host)
docker run -v ~/.config/ubcode/ubcode.toml:/root/.config/ubcode/ubcode.toml:ro \
           your-image:tag

# For ubConnect (Linux host)
docker run -v ~/.config/ubconnect/ubconnect.toml:/root/.config/ubconnect/ubconnect.toml:ro \
           your-image:tag
```

```yaml
services:
  dev:
    image: your-image:tag
    volumes:
      # Mount as read-only (:ro) for security
      - ~/.config/ubcode/ubcode.toml:/root/.config/ubcode/ubcode.toml:ro
      - ~/.config/ubconnect/ubconnect.toml:/root/.config/ubconnect/ubconnect.toml:ro
```

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

### Create ubConnect Configuration Directory (macOS)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

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

```bash
# For ubConnect
mkdir -p ~/Library/Application\ Support/ubconnect

```

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

### Create ubConnect Configuration Directory (Windows PowerShell)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Creates the necessary directory for ubConnect configuration files on a Windows system using PowerShell. This is a prerequisite for setting up the ubconnect.toml file.

```powershell
# For ubConnect
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\useblocks\ubconnect"

```

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

### Generate Code Coverage Reports

Source: https://x-as-code.useblocks.com/how-to-guides/testing/index

These commands show how to execute tests with coverage enabled and then open the generated HTML coverage report. This provides line-level detail on code execution during tests.

```bash
# Run tests with coverage
./scripts/test_with_coverage.sh

# View coverage report
open src/build/coverage_html/index.html

```

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

### Clean Build Directory and Rebuild Project

Source: https://x-as-code.useblocks.com/tutorials/sphinx-needs-setup

Removes the Sphinx build directory and then rebuilds the project using 'uv run sphinx-build'. This is a common solution for changes not appearing after a rebuild.

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

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

### Set Temporary ubCode Environment Variables (macOS launchctl)

Source: https://x-as-code.useblocks.com/tutorials/licensing-setup

Sets ubCode license key and user environment variables for GUI applications using the launchctl command. Note that this method does not persist across reboots and requires creating a Launch Agent plist for persistence.

```bash
launchctl setenv UBCODE_LICENSE_KEY "AAAAA-BBBBB-CCCCC-DDDDD"
launchctl setenv UBCODE_LICENSE_USER "your.email@example.com"
```