Skip to content

Step 10 — Documentation Guide

1. Scope

This documentation site provides step-by-step reproduction guides for the SentriPi edge computing cluster. Every task page records the exact procedure, configuration files, commands, and pitfalls encountered — so that students, researchers, and lecturers can reproduce the setup without rediscovering the same failures.

2. Documentation structure

  • docs/
  • index.md — Overview and architecture diagram
  • tasks/
    • task-01-infrastructure.md — PXE network boot cluster setup
    • task-02-linpack.md — LINPACK / HPL benchmark
    • task-03-mpi.md — MPI-based pi computation and scaling
    • task-04-non-mpi.md — Non-MPI distributed task processing
    • task-05-monitoring.md — Cluster monitoring and telemetry
    • task-06-model-training.md — ML model training on edge
    • task-07-backend.md — Backend data pipeline and storage
    • task-08-frontend.md — Web frontend
    • task-09-telegram.md — Telegram bot
    • task-10-documentation.md — This page
  • results/
    • index.md — Consolidated benchmarks and chart images
  • images/ — Screenshots, diagrams, and charts
  • stylesheets/
    • extra.css — Custom CSS for topology containers and layout
  • mkdocs.yml — Site configuration (theme, nav, plugins)

3. Philosophy

  • Reproduction-focused: Each task page is a step-by-step guide someone can follow.
  • Pitfalls documented: Issues encountered and how to avoid them.
  • Results separate: Benchmarks, speedup plots, and findings under results/.

4. Documentation conventions

All pages in this site follow consistent formatting rules:

Rule Convention Example reference
Title # Step N — Title All task pages
Section numbering ## N. Title All task pages
Network topology diagrams HTML <div class="topology-container"> tasks 1, 3, 5, 7
File / directory listings Nested - bullet lists tasks 2, 4
Warnings and pitfalls !!! warning "Title" admonition All tasks
Informational notes !!! tip "Title" admonition Common
Code blocks Language annotation required (```bash, ```text, ```ini, ```yaml, ```json, ```c, ```python) Every code block
Configuration file creation sudo tee heredoc — no interactive editors All tasks
Image references ../images/filename.png from task pages All tasks
Tables Standard pipe tables All tasks

5. Build and maintenance

Local preview

python -m mkdocs serve
Run from the NodeManager directory. Open http://127.0.0.1:8000 in a browser.

Deployment

The site auto-deploys to GitHub Pages via GitHub Actions on every push to the main branch. No manual build step is required.

Adding a new task page

  1. Create docs/tasks/task-NN-description.md
  2. Add an entry in mkdocs.yml under the nav section
  3. Reference images using ../images/ relative to the tasks directory
  4. Push to main — the site redeploys automatically

Image paths

Task pages live in docs/tasks/, so image paths must use ../images/. Images are stored in docs/images/. New image files must be explicitly tracked with git — they are not included when only .md files are committed.