Merge pull request #1118 from DocArmoryTech/mkdocs-readme

docs: add mkdocs readme

Author: adulau

tools/mkdocs/README.md

@@ -0,0 +1,79 @@
+# MISP Galaxy MkDocs: Setup & Usage
+
+This folder contains the tooling to generate and publish the MISP Galaxy documentation site using MkDocs (Material theme).
+
+The documentation content is generated by `generator.py` from the JSON galaxies and clusters in the repository, then built with MkDocs using the configuration in `site/mkdocs.yml`.
+
+## Prerequisites
+- Python 3.10+ recommended (Linux, bash)
+- A virtual environment (optional but recommended)
+- `pip` for installing dependencies
+
+## Install Dependencies
+Run these from `misp-galaxy/tools/mkdocs`:
+
+```bash
+# Create and activate a virtual environment (recommended)
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install required packages
+pip install -r requirements.txt
+```
+
+Dependencies include `mkdocs`, `mkdocs-material`, and plugins listed in `requirements.txt`.
+
+## Generate Site Content
+The static pages are generated from the Galaxy/Cluster JSON files via `generator.py` and written to `site/docs/`.
+
+```bash
+python3 generator.py
+```
+
+This will:
+- Parse `../../clusters` and `../../galaxies`
+- Build relations and statistics
+- Write Markdown files under `site/docs/`
+
+## Build the MkDocs Site
+MkDocs uses the configuration in `site/mkdocs.yml`.
+
+```bash
+cd site
+mkdocs build
+```
+
+The static site will be generated into `site/site/`.
+
+## Local Preview (Live Server)
+To preview locally with auto-reload:
+
+```bash
+cd site
+mkdocs serve
+# Visit http://127.0.0.1:8000
+```
+
+Note: Re-run `python3 generator.py` when source JSON changes so `site/docs/` stays up to date.
+
+## One-Step Build Script
+The `build.sh` script checks installed packages vs `requirements.txt`, runs the generator, builds the site, and (for maintainers) deploys via `rsync`.
+
+```bash
+bash build.sh
+```
+
+Deployment via `rsync` requires access to the target host. If you are not a maintainer, you can comment out or remove the `rsync` line in `build.sh`.
+
+## Project Structure
+- `generator.py`: Generates Markdown content into `site/docs/`
+- `modules/`: Helpers for building the universe, galaxies, clusters, and site pages
+- `site/mkdocs.yml`: MkDocs configuration (Material theme, plugins, assets)
+- `site/docs/`: Generated documentation content
+- `requirements.txt`: Python dependencies for generation and MkDocs
+- `build.sh`: Helper script to generate, build, and deploy
+
+## Troubleshooting
+- If `mkdocs` is not found, ensure your venv is activated and `mkdocs` is installed: `pip install -r requirements.txt`.
+- If content seems outdated, re-run: `python3 generator.py` before `mkdocs serve` or `mkdocs build`.
+- If plugin errors occur, verify plugin versions match `requirements.txt` and reinstall.