doc i18n fix

.gitignore

@@ -130,3 +130,6 @@ dmypy.json
 
 # IDE
 .idea/
+
+# Agents
+.codex

README.md

@@ -19,7 +19,7 @@ Please generously STAR★ our project or donate to us!
 
 ## Getting started
 
-Refer to[📚 Document & 中文文档](https://aloha-python.readthedocs.io/) for detailed introduction.
+Refer to 📚 [Document](https://aloha-python.readthedocs.io/) & [中文文档](https://aloha-python.readthedocs.io/zh-cn/main/) for detailed introduction.
 
 ```shell
 pip install aloha[all]

doc/.readthedocs.yaml

@@ -11,6 +11,8 @@ build:
   jobs:
     pre_create_environment:
       - echo "Command run at 'pre_create_environment' step"
+    pre_build:
+      - 'case "${READTHEDOCS_LANGUAGE}" in zh*) cp ./doc/mkdocs.zh.yml ./doc/mkdocs.yml ;; esac'
     post_build:
       - echo "Command run at 'post_build' step $(date)"
 
@@ -22,3 +24,5 @@ python:
     - requirements: ./doc/requirements.txt
     - method: pip
       path: ./src
+      extra_requirements:
+        - all

doc/en/README-cli.md

@@ -19,17 +19,34 @@ Note: this `module_name` **must** include a function named `main()`.
 
 ## Compile Python code into binary
 
-Sometimes you need to compile Python source code into binary libraries to protect source code.
+Sometimes you need to distribute Python code without shipping the raw `.py` files. This command turns most Python modules into compiled extension libraries (`.so` files on Linux/macOS), which can help with source-code protection and reduce direct readability of implementation details.
 
-Aloha helps you build Python source code into binaries using `Cython`:
+Aloha uses `Cython` for this workflow:
 
 ```bash
 aloha compile --base=./app --dist=./build --keep='main.py'
 ```
 
+How it works:
+
+1. Scan the source tree under `--base`.
+2. Skip hidden folders, the output folder, excluded paths, `.pyc` files, and `.pyx` files.
+3. Copy non-Python files directly into the target tree.
+4. Convert regular `.py` modules into compiled extension modules.
+5. Keep files listed in `--keep` as plain Python files.
+6. Move the final build result into `--dist` and clean up intermediate Cython artifacts.
+
+Notes:
+
+- `__init__.py` files are copied as plain Python files.
+- All python submodule folders MUST contain a `__init__.py` file, otherwise python files in this submodule/folder will be compiled and built to root folder.
+- Files passed through `--keep` are not compiled.
+- `Cython` must be installed first.
+- The command writes a temporary build tree under `/tmp/build/<project-name>` before moving the result to `--dist`.
+
 Available options:
 
 - `--base`: root folder that includes source code to build
 - `--dist`: (default=`build`) target folder for binary code
-- `--exclude`: files/folders to exclude (use multiple times for multiple paths)
-- `--keep`: source files to keep as-is instead of converting to dynamic libraries (use multiple times)
+- `--exclude`: files/folders to exclude; pass one or more paths after the flag
+- `--keep`: source files to keep as-is instead of converting to dynamic libraries; pass one or more paths after the flag

doc/en/README-develop.md

@@ -24,5 +24,5 @@ build_image app_common latest tool/app.Dockerfile
 ## Develop docs
 
 ```bash
-mkdocs serve -f mkdocs.yml -a 0.0.0.0:80
+mkdocs serve -f mkdocs.yml -a 0.0.0.0:3000
 ```

doc/en/README-get-start.md

@@ -6,8 +6,44 @@
 pip install aloha[all]
 ```
 
-## Step 2. Start your project based on the template
+## Step 2. Use this repository as a boilerplate
 
-You can refer to the `app` folder in the GitHub repository to start using `aloha` in your project:
+The `app/` folder in this repository is a boilerplate/template project built on top of `aloha`.
+It gives you a ready-to-use application layout, development scripts, and containerized tooling so you can start building instead of assembling the project skeleton yourself.
+
+### What this template gives you
+
+- A containerized development environment based on Docker and Docker Compose
+- Pre-installed Python and project dependencies
+- An application entry point you can extend directly
+- A conventional layout for source code, documentation, notebooks, and tooling
+
+### Recommended workflow
+
+1. Clone this repository.
+2. Open the `app/` directory to inspect the starter application structure.
+3. Use the scripts under `tool/cicd/` to start the development container when you want a reproducible environment.
+4. Put your own application code in the template structure and grow from there.
+
+### Launch the development environment
+
+If you want the full boilerplate experience, start the containerized DEV environment:
+
+```bash
+./tool/cicd/run-dev.sh up
+./tool/cicd/run-dev.sh enter
+```
+
+The `up` command creates or starts the development container. The `enter` command opens an interactive shell inside that container.
+
+### Project structure
+
+The template is organized around a few common folders:
+
+- `app/`: application code and entry points
+- `src/`: the `aloha` library source code
+- `doc/`: documentation source files
+- `notebook/`: Jupyter notebooks for experimentation
+- `tool/`: scripts and Docker assets for development and CI/CD
 
 [:octicons-mark-github-16: Go to Template Project](https://github.com/LabNow-ai/aloha-python/tree/main/app){ .md-button }

doc/en/api/core.md

@@ -0,0 +1,11 @@
+# Core and Configuration
+
+::: aloha
+
+::: aloha.base
+
+::: aloha.settings
+
+::: aloha.config.paths
+
+::: aloha.config.hocon

doc/en/api/db.md

@@ -0,0 +1,23 @@
+# Database
+
+::: aloha.db
+
+::: aloha.db.base
+
+::: aloha.db.duckdb
+
+::: aloha.db.elasticsearch
+
+::: aloha.db.kafka
+
+::: aloha.db.mongo
+
+::: aloha.db.mysql
+
+::: aloha.db.oracle
+
+::: aloha.db.postgres
+
+::: aloha.db.redis
+
+::: aloha.db.sqlite

doc/en/api/encrypt.md

@@ -0,0 +1,19 @@
+# Encryption
+
+::: aloha.encrypt
+
+::: aloha.encrypt.hash
+
+::: aloha.encrypt.jwt
+
+::: aloha.encrypt.aes
+
+::: aloha.encrypt.rsa
+
+::: aloha.encrypt.vault
+
+::: aloha.encrypt.vault.base
+
+::: aloha.encrypt.vault.plain
+
+::: aloha.encrypt.vault.cyberark

doc/en/api/index.md

@@ -0,0 +1,15 @@
+# API Reference
+
+The API documentation is split by package so each page stays focused and easier to maintain.
+
+Choose a section below:
+
+- Core and configuration
+- Logging
+- Command-line scripts
+- Service layer
+- Encryption
+- Database
+- Time helpers
+- Utilities
+- Testing utilities

doc/en/api/logging.md

@@ -0,0 +1,7 @@
+# Logging
+
+::: aloha.logger
+
+::: aloha.logger.logger
+
+::: aloha.logger.handler

doc/en/api/scripts.md

@@ -0,0 +1,9 @@
+# Command-Line Scripts
+
+::: aloha.script.base
+
+::: aloha.script.info
+
+::: aloha.script.start
+
+::: aloha.script.compile

doc/en/api/service.md

@@ -0,0 +1,23 @@
+# Service Layer
+
+::: aloha.service
+
+::: aloha.service.app
+
+::: aloha.service.web
+
+::: aloha.service.http.base_api_client
+
+::: aloha.service.http.base_api_handler
+
+::: aloha.service.http.plain_http_handler
+
+::: aloha.service.http.files
+
+::: aloha.service.openapi.client
+
+::: aloha.service.api.v0
+
+::: aloha.service.api.v1
+
+::: aloha.service.api.v2

doc/en/api/testing.md

@@ -0,0 +1,9 @@
+# Testing Utilities
+
+::: aloha.testing
+
+::: aloha.testing.unit
+
+::: aloha.testing.service_v1
+
+::: aloha.testing.service_v2

doc/en/api/time.md

@@ -0,0 +1,9 @@
+# Time Helpers
+
+::: aloha.time
+
+::: aloha.time.timeout_async
+
+::: aloha.time.timeout_asyncio
+
+::: aloha.time.timeout_signal

doc/en/api/util.md

@@ -0,0 +1,15 @@
+# Utilities
+
+::: aloha.util
+
+::: aloha.util.html
+
+::: aloha.util.json
+
+::: aloha.util.random
+
+::: aloha.util.sys_cuda
+
+::: aloha.util.sys_gpu
+
+::: aloha.util.sys_info

doc/mkdocs.yml

@@ -1,7 +1,8 @@
 site_name: Aloha - a versatile Python library to build microservice.
-repo_url: https://github.com/LabNow-ai/aloha
-edit_uri: blob/main/doc/
-docs_dir: ./
+repo_url: https://github.com/LabNow-ai/aloha-python
+edit_uri: blob/main/doc/en/
+site_url: !ENV READTHEDOCS_CANONICAL_URL
+docs_dir: ./en
 theme:
   name: material
   highlightjs: true
@@ -30,25 +31,6 @@ theme:
         name: Switch to light mode
 plugins:
   - search
-  - i18n:
-      docs_structure: folder
-      reconfigure_material: true
-      languages:
-        - locale: en
-          name: English
-          default: true
-          build: true
-        - locale: zh
-          name: 简体中文
-          build: true
-      nav_translations:
-        zh:
-          Introduction: 介绍
-          Get Started: 快速开始
-          CLI Commands: CLI 命令
-          Configs: 配置说明
-          Development Guide: 开发文档
-          API Reference: API 参考
   - mkdocstrings:
       handlers: # See: https://mkdocstrings.github.io/python/usage/
         python:
@@ -80,4 +62,14 @@ nav:
   - CLI Commands: "README-cli.md"
   - Configs: "README-config.md"
   - Development Guide: "README-develop.md"
-  - API Reference: "api.md"
+  - API Reference:
+      - Overview: "api/index.md"
+      - Core and Config: "api/core.md"
+      - Logging: "api/logging.md"
+      - CLI Scripts: "api/scripts.md"
+      - Service: "api/service.md"
+      - Encryption: "api/encrypt.md"
+      - Database: "api/db.md"
+      - Time: "api/time.md"
+      - Utilities: "api/util.md"
+      - Testing: "api/testing.md"