EVO X

Руководство по написанию документации

Руководство по написанию документации

Это руководство описывает лучшие практики написания и поддержки документации в кодовой базе и дополнительных файлах.

Документация в коде (Docstrings)

Строки документации необходимы для понимания назначения, использования и поведения вашего кода. Пожалуйста, придерживайтесь следующих соглашений:

Общие правила

  • Документируйте все публичные классы, методы и функции с помощью строк документации.
  • Используйте строки документации в стиле Sphinx.
  • Не включайте типы параметров в строку документации — они должны быть объявлены в сигнатуре функции с помощью аннотаций типов.

Формат и директивы

Используйте следующие директивы для описания различных элементов:

  • :param <name>: — Описание параметра.
  • :return: — Описание возвращаемого значения.
  • :raises <exception>: — Описание исключений, которые может вызвать функция.

Пример

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

Внешняя документация (каталог docs/)

Вся документация уровня проекта находится в каталоге docs/. Эти документы поддерживают как пользователей, так и разработчиков, предоставляя руководства, примеры и справочные материалы.

Формат

  • Используйте Markdown (.md) или Jupyter Notebooks (.ipynb) для документации.
  • Markdown предпочтителен для повествовательного контента и статической документации.
  • Используйте Jupyter Notebooks для исполняемого, интерактивного контента (например, учебных пособий или демонстраций).

Рекомендации по Jupyter Notebook

  • Убедитесь, что все ноутбуки полностью исполняемы.
  • Всегда запускайте все ячейки и сохраняйте вывод перед коммитом.
  • Наша среда CI/CD не поддерживает выполнение на GPU, поэтому ноутбуки должны быть предварительно выполнены локально.

Директивы Markdown и Notebook

Используйте следующие шаблоны для расширенного форматирования:

  • [name](#ref) — Внутренняя перекрёстная ссылка, например, [ModuleBase](#evox.core.module.ModuleBase) или [ModuleBase](#ModuleBase)
  • ![Alt Text](path) — Вставка изображений, например, ![Module base](/_static/modulebase.png)

Перевод

Документация поддерживает многоязычный контент. Следуйте приведённым ниже шагам для обновления или генерации переводов.

Обновление переводов (например, для zh_CN)

cd docs
make gettext
sphinx-intl update -p build/gettext -l zh_CN
cd ..
python docs/fix_output.py
← Вернуться к документации