Agent Maintenance Guide

This document is written for Kimi and other AI agents that may need to modify, update, or extend the Evercycle API documentation project.

Project Layout

/SSD2/sites/Evercycle-Docs/
├── docs/
│   ├── source/              # Sphinx RST source files
│   │   ├── index.rst        # Main toctree
│   │   ├── overview.rst
│   │   ├── architecture.rst
│   │   ├── api_endpoints.rst
│   │   ├── operational_flows.rst
│   │   ├── modules.rst      # Toctree for module docs
│   │   ├── module_*.rst     # One per Python module
│   │   ├── examples.rst
│   │   ├── agents.rst       # This file
│   │   ├── _static/         # Empty; for CSS/images
│   │   └── _templates/      # Empty; for HTML overrides
│   ├── build/               # Generated HTML (do not edit by hand)
│   └── Makefile             # Auto-generated by sphinx-quickstart
├── examples/                # Placeholder for extra code examples
├── api_specs/               # Placeholder for OpenAPI/JSON specs
└── requirements.txt         # Python packages needed to build docs

How to Update the Documentation

  1. Edit RST files in docs/source/.

  2. Add new pages to the appropriate toctree (e.g., index.rst or modules.rst).

  3. Re-build HTML by running:

    cd /SSD2/sites/Evercycle-Docs
pip install -r requirements.txt
sphinx-build -b html docs/source docs/build/html

  4. Verify the output in docs/build/html/index.html.

  5. Reload Caddy if site paths changed (not needed for content-only updates).

Adding a New Python Module

  1. Create docs/source/module_<name>.rst following the style of existing module files.

  2. Document every public class, method, and function.

  3. Add the new file to docs/source/modules.rst under its toctree.

  4. Re-build and verify.

Adding a New API Endpoint

  1. Update docs/source/api_endpoints.rst: * Add the endpoint to the Flask proxy table. * Add the backend endpoint description under the correct heading.

  2. Update docs/source/operational_flows.rst if the new endpoint has a unique flow (e.g., special path patching or body merging).

  3. Add a curl example to docs/source/examples.rst.

  4. Re-build.

Adding Code Examples

  1. For simple one-liners, add them directly to docs/source/examples.rst.

  2. For multi-file or runnable scripts, place them in examples/ and link to them using :download: or a literal block with a file path note.

Styling Conventions

  • Use .. http:get:: / .. http:post:: etc. for REST endpoints.

  • Use .. py:function::, .. py:class::, .. py:method:: for Python APIs.

  • Use .. code-block:: json or .. code-block:: bash for all code.

  • Keep line lengths reasonable (≤120 characters) for readability in terminals.

Do Not Edit by Hand

  • docs/build/html/ — this is auto-generated. Any hand edits will be lost on the next sphinx-build.

Caddy Configuration

The documentation site is served at https://evercycle-docs.veraetime.net from /SSD2/sites/Evercycle-Docs/docs/build/html.

Config file: /etc/caddy/sites/evercycle-docs.veraetime.net.caddy

If the build output directory changes, update the root directive in that Caddyfile and run caddy reload.