docs: Migrate from sphinx to mkdocs. Improve Navigation (#42)

* docs: Migrate from sphinx to mkdocs - build

* docs: Migrate from sphinx to mkdocs - setup readthedocs

* docs: Migrate from sphinx to mkdocs - fix nifi link

* docs: Fix all admonitions

* docs: Refactor navigation

Author: alhendrickson

.github/workflows/doc-build.yml

@@ -7,21 +7,27 @@ on:
     branches:
       - '**'
     tags:
-      - 'v*.*.*'
+      - 'docs-v*.*.*'
   release:
     types: [published]
+
+defaults:
+  run:
+    working-directory: ./docs
 jobs:
   build:
     runs-on: ubuntu-latest
-    env:
-      working-directory: ./docs
     steps:
       - uses: actions/checkout@v3
-      - name: Check documentation build
+      - name: Install uv for Python 3.13
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: 3.13
+          enable-cache: true
+          cache-dependency-glob: "docs/uv.lock"
+      - name: Install the project
+        run: |
+          uv sync --all-extras
+      - name: Build documentation
         run: |
-          cd docs
-          pip3 install -r requirements.txt
-          make clean
-          # Fail buiild on any docs warning
-          # make html O=-W # Removed whilst migrating existing docs
-          make html
+          uv run mkdocs build

.readthedocs.yml

@@ -5,14 +5,19 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: "ubuntu-24.04"
   tools:
-    python: "3.9"
+    python: "3.13"
+  jobs:
+    pre_create_environment:
+        - cd docs
+        - asdf plugin add uv
+        - asdf install uv latest
+        - asdf global uv latest
+    create_environment:
+        - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+        - cd docs && UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen
 
-sphinx:
-  configuration: docs/conf.py
-  fail_on_warning: false # Removed warnings to migrate existing docs
-
-python:
-  install:
-    - requirements: docs/requirements.txt
+mkdocs:
+  configuration: docs/mkdocs.yml

docs/Makefile

@@ -0,0 +1,40 @@
+# CogStack Documentation
+
+The central documentation for cogstack, hosted on docs.cogstack.org
+
+## Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Installation
+
+```bash
+uv venv --python 3.12 --allow-existing 
+source .venv/bin/activate
+uv sync --dev
+```
+
+## Usage
+
+### Serve documentation locally (Development)
+
+To preview the documentation locally with live reload:
+
+```bash
+uv run mkdocs serve
+```
+
+The documentation will be available at `http://127.0.0.1:8000`
+
+### Build documentation
+
+To build the static site:
+
+```bash
+uv run mkdocs build
+```
+
+The built site will be in the `site/` directory.