EVO X
Open menu

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

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

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

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

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

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

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

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

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

  • :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
← Вернуться к документации