Document Writing Guide#

This guide outlines best practices for writing and maintaining documentation across the codebase and supplementary files.

In-Code Documentation (Docstrings)#

Docstrings are essential for understanding the purpose, usage, and behavior of your code. Please adhere to the following conventions:

General Rules#

  • Document all public classes, methods, and functions using docstrings.

  • Use Sphinx-style docstrings.

  • Do not include parameter types in the docstring—they are expected to be declared in the function signature using type hints.

Format and Directives#

Use the following directives to describe different elements:

  • :param <name>: — Describe a parameter.

  • :return: — Describe the return value.

  • :raises <exception>: — Describe exceptions the function might raise.

Example#

def add(a: int, b: int) -> int:
    """
    Add two integers.

    :param a: The first integer.
    :param b: The second integer.
    :return: The sum of the two integers.
    :raises ValueError: If either input is not an integer.
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError("Inputs must be integers.")
    return a + b

External Documentation (docs/ Directory)#

All project-level documentation is located in the docs/ directory. These documents support both users and developers by providing guides, examples, and references.

Format#

  • Use Markdown (.md) or Jupyter Notebooks (.ipynb) for documentation.

  • Markdown is preferred for narrative content and static documentation.

  • Use Jupyter Notebooks for executable, interactive content (e.g., tutorials or demos).

Jupyter Notebook Guidelines#

  • Ensure all notebooks are fully executable.

  • Always run all cells and save the output before committing.

  • Our CI/CD environment does not support GPU execution, so notebooks must be pre-executed locally.

Markdown & Notebook Directives#

Use the following patterns for rich formatting:

  • [name](#ref) — Internal cross-reference, e.g., [ModuleBase](#evox.core.module.ModuleBase) or [ModuleBase](#ModuleBase)

  • ![Alt Text](path) — Embed images, e.g., ![Module base](/_static/modulebase.png)

Translation#

The documentation supports multilingual content. Follow the steps below to update or generate translations.

Updating Translations (e.g., for zh_CN)#

cd docs
make gettext
sphinx-intl update -p build/gettext -l zh_CN
cd ..
python docs/fix_output.py