Skip to content

Documentation & Building

This documentation is built with MkDocs + the Material theme + the i18n plugin. The source is the docs/ folder.

Local preview

pip install mkdocs mkdocs-material "mkdocs-static-i18n"
mkdocs serve        # default http://127.0.0.1:8000, with live reload

Build the static site

mkdocs build        # output to site/; --strict fails on broken links / missing translations

Directory convention

docs/
├── zh/             # Chinese (default language)
└── en/             # English
    Each language folder shares the same structure: index.md, about.md, guide/, dev/, api/
  • Adding a page: create a same-named file in both zh/ and en/, then register it in the nav of mkdocs.yml.
  • Chinese → English navigation mappings live in nav_translations.

Code conventions (for contributors)

  • File names: UI feature pages use Chinese pinyin (e.g. qiudao.py = Derivative); library modules such as core/, functions/ use English.
  • Layering: computation logic goes in functions/ (pure functions, no Qt); UI goes in ui/; shared services go in core/.
  • Docstrings: public functions / classes should have docstrings to support the API reference.
  • Lazy loading: new UI modules must be registered in _submodules of ui/__init__.py to benefit from faster startup.

Documentation categories

This help site is split into three categories for different readers:

  • User Guide (guide/): for end users — installation, configuration, and how to use each feature.
  • Developer Guide (dev/): for contributors — architecture, how to add a feature, internationalization, and building docs.
  • API Reference (api/): for integrators — the public functions of each core/ and functions/ module.

Contribution workflow

  1. Fork the repository and create a branch.
  2. Update docs in both docs/zh and docs/en.
  3. Run mkdocs build --strict locally to confirm no broken links / missing translations.
  4. Open a Pull Request.