Warning, /AID2E-framework/docs/docs-guide.md is written in an unsupported language. File is not indexed.
0001 # AID2E Documentation Guide
0002
0003 This guide explains how to generate, preview, and deploy the AID2E documentation site using MkDocs.
0004
0005 ## Prerequisites
0006 - Python 3.8+
0007 - MkDocs tooling (install via project extras):
0008
0009 ```bash
0010 pip install -e ".[docs]"
0011 ```
0012
0013 ## Quick Start
0014 - Preview locally (live-reload on changes):
0015
0016 ```bash
0017 ./scripts/docs-serve.sh
0018 ```
0019
0020 - Build static site into `site/`:
0021
0022 ```bash
0023 ./scripts/docs-build.sh
0024 ```
0025
0026 - Deploy to GitHub Pages (main branch):
0027
0028 ```bash
0029 ./scripts/docs-deploy-ghpages.sh
0030 ```
0031
0032 ## Project Layout
0033 - MkDocs config: `mkdocs.yml` (repo root)
0034 - Markdown sources: `docs/` (this directory)
0035 - Built site output: `site/` (created on build)
0036
0037 ## Writing Docs
0038 - Add new pages under `docs/` as `.md` files.
0039 - Update navigation in `mkdocs.yml` under the `nav:` section.
0040 - Use Markdown and admonitions (notes, tips) supported by Material theme.
0041
0042 ## API Reference (mkdocstrings)
0043 MkDocs is configured to use `mkdocstrings` for Python API docs. Ensure modules are importable:
0044
0045 - Core: `packages/aid2e-core/src`
0046 - Optimizers: `packages/aid2e-optimizers/src`
0047 - Schedulers: `packages/aid2e-schedulers/src`
0048 - Utilities: `packages/aid2e-utilities/src`
0049
0050 ## Troubleshooting
0051 - If `mkdocs` is not found, install docs extras: `pip install -e ".[docs]"`.
0052 - If API pages fail to render, verify import paths in `mkdocs.yml` `setup_commands` and that packages are installed in editable mode: `pip install -e .`.
0053 - GitHub Pages must be enabled in the repository settings to deploy with `gh-deploy`.
