This is a unified documentation build template designed for the Data-Juicer ecosystem. Built on Sphinx and the bundled data_juicer_theme (a modern custom theme), it provides multi-version and multi-language documentation capabilities, ensuring consistent documentation appearance and user experience across all subprojects.
- Unified Appearance: All subprojects share the same documentation theme and styling.
- Multi-Version Support: Automatically builds documentation for multiple Git branches and tags, with incremental CI deployment (only the changed version is rebuilt; immutable tags are built once).
- Multi-Language Support: Supports both English and Chinese by default.
- Ecosystem Interconnectivity: Enables seamless navigation between different project documentations via header external links.
- Markdown-Friendly: Automatically discovers and integrates Markdown documents within the project.
- AI Assistant: Built-in "Ask Juicer" widget (floating input bar, select-to-ask, resizable side panel) with streaming responses, thinking-mode and tool-call display; activated automatically when
JUICER_API_URLis configured.
data-juicer-sphinx/
├── data_juicer_sphinx_theme/ # Custom Sphinx theme package
│ ├── theme.conf / layout.html / search.html # Theme definition and templates
│ └── static/ # Theme CSS/JS
├── docs/
│ └── sphinx_doc/ # Sphinx documentation build directory
│ ├── build_versions.py # Multi-version build script (main entry point)
│ ├── make.bat / Makefile # Build scripts
│ ├── redirect.html # Redirect page
│ └── source/ # Documentation source files
│ ├── conf.py # Sphinx configuration file
│ ├── custom_myst.py # Custom MyST extension
│ ├── external_links.yaml # External project link configuration
│ ├── index.rst / index_ZH.rst # Home page (customization recommended)
│ ├── api.rst # API documentation index (customization recommended)
│ └── _static/ # Static assets
│ ├── images/ # Logos and icons
│ ├── ask-ai-widget.js / .css # Bundled Ask-AI widget and styles
│ └── ask-ai-modules/ # Widget modular sources + rollup build
├── guides/ # Usage guides
├── pyproject.toml # Project configuration (registers the theme)
├── README.md
└── README_ZH.md
Build the simplest English Data-Juicer Sphinx documentation (without API docs):
git clone https://github.com/datajuicer/data-juicer-sphinx.git
uv pip install .
cd docs/sphinx_doc
export PROJECT="data-juicer-sphinx"
python build_versions.py -A -l enRead the docs online: datajuicer.github.io/data-juicer-sphinx
- Enable the Template — integrate, customize, and build locally
- Deploy with GitHub Actions — incremental CI deployment
- Writing Documentation — content, media assets, and link mapping
- FAQ
- How It Works — build internals and the incremental pipeline
Contributions and improvements to this template are warmly welcomed! ❤