Building the Documentation
The documentation site is built with MkDocs and the Material theme. The API reference is pulled from the source repositories, which are included as git submodules, so clone recursively:
git clone --recursive https://github.com/AI4Optics/docs.git
cd docs
pip install -r docs/requirements.txt
mkdocs serve # preview at http://127.0.0.1:8000
If you already cloned without --recursive, fetch the submodules with
git submodule update --init.
Maintaining both languages
The main site's English pages are served at /, and Simplified Chinese pages at
/zh/. Use the header language menu to switch to the equivalent page. Preview
Chinese locally at http://127.0.0.1:8000/zh/.
Each English page.md must have a matching page.zh.md. Update both versions
when content changes, translating prose, headings, captions and descriptions
while preserving code, API identifiers, equations and citation records. Use
unsuffixed page.md internal links and preserve heading anchors referenced by
other pages so readers stay in their language. Generated API docstrings retain
their original English; images and styles are shared.
DeepO user manual
The canonical English and Chinese manual lives in deepo-manual/docs/ and follows
the same translation rules. Its separate configuration preserves the manual's own
navigation, search and language selector:
The manual preview serves English at / and Chinese at /zh/ on port 8002.
Building it does not require access to the private DeepO application repository.
Maintainers use the corresponding approved application release to check product
behavior, then commit only reviewed public documentation and assets here.
Build and validate both sites
The shared script runs strict builds for the main documentation and then the
manual, placing the manual under site/deepo/manual/. Both are published by the
existing docs service. Navigation and search remain separate between the two
builds. The checks verify translation coverage and code parity, plus generated page
languages, navigation, search indexes and links.