Documentation Guide

Documentation for the Eleanor AI project is generated using MkDocs and the Material for MkDocs theme. This guide provides quickstart information on how to develop and publish the documentation.

Writing Documentation

To start the local development server, run the following command:

make mkdocs-serve

When adding new images, it is recommended that unoptimized images are kept in the docs/images_src directory. There is an image optimization pipeline that will convert images to webp format and optimize them for the web. The optimized images are stored in the docs/images directory.

make mkdocs-images

Publishing

To publish the documentation, run the following command:

make mkdocs-publish

The publication pipeline is controlled via the previously mentioned make target. The publish process will first regenerates the images, builds the local static site, syncs the local site to the stage bucket, syncs the stage site to the live bucket, and then cleans up local static files and remote staging files.

The publication pipeline is depicted in the following sequence diagram:

sequenceDiagram
    autonumber
    participant MAKE as Make
    participant STAGE as Stage Bucket
    participant LIVE as Live Bucket

    MAKE ->> MAKE: Regenerate images
    MAKE ->> MAKE: Build local static site
    MAKE ->> STAGE: Sync local site to stage
    MAKE ->> LIVE: Sync stage site to live
    MAKE ->> MAKE: Clean up

Python Documentation

MkDocs navigation Python API documentation is auto-generated via bin/gen_ref_nav.py which scans src/eleanor recursively for Python files and generates a navigation structure. Note that alembic scripts are omitted. This process is triggered automatically by the MkDocs gen-files plugin.

API Documentation

API documentation is generated automatically via FastAPI.