Документирование задач с помощью Sphinx

В этом документе описано, как автоматически генерировать документацию для задач с помощью Sphinx.

celery.contrib.sphinx

Плагин документации Sphinx, используемый для документирования задач.

Введение

Использование

Для расширения Celery для Sphinx требуется Sphinx версии 2.0 или новее.

Добавьте расширение в модуль конфигурации docs/conf.py:

extensions = (...,
              'celery.contrib.sphinx')

Если вы хотите изменить префикс задач в справочной документации, измените значение конфигурации celery_task_prefix:

celery_task_prefix = '(task)'  # < default

После установки расширения autodoc автоматически найдет объекты, декорированные как задачи (например, при использовании директивы automodule), и сгенерирует правильную документацию (а также добавит префикс (task)). Кроме того, на задачи можно ссылаться с помощью синтаксиса :task:proj.tasks.add.

Чтобы документировать задачу вручную, используйте .. autotask::.

Совместимость с Sphinx 9.0+

В Sphinx 9.0 была представлена переработанная реализация autodoc. Для корректной работы расширению Celery требуется устаревший режим autodoc на основе классов. При использовании Sphinx версии 9.0 или новее добавьте следующее в conf.py:

autodoc_use_legacy_class_based = True

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

classcelery.contrib.sphinx.TaskDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Директива задачи Sphinx.

get_signature_prefix(sig): Может вернуть префикс, который будет помещен перед именем объекта в сигнатуре.

classcelery.contrib.sphinx.TaskDocumenter(directive:DocumenterBridge, name:str, indent:str='')

Документирование определений задач.

classmethodcan_document_member(member, membername, isattr, parent): Вызывается, чтобы проверить, может ли этот Documenter документировать элемент.

check_module(): Проверяет, действительно ли self.object определен в модуле, указанном в self.modname.

document_members(all_members=False)

Создает reST-разметку для документации элементов.

Если all_members имеет значение True, документируются все элементы, иначе — элементы, указанные в self.options.members.

format_args()

Форматирует сигнатуру аргументов self.object.

Должен возвращать None, если у объекта нет сигнатуры.

member_order=11: Порядок, если для autodoc_member_order задано значение ‘groupwise’

objtype='task': Имя, по которому вызывается директива (auto…), и имя директивы, генерируемое по умолчанию

celery.contrib.sphinx.autodoc_skip_member_handler(app, what, name, obj, skip, options): Обработчик события autodoc-skip-member.

celery.contrib.sphinx.setup(app): Настройка расширения Sphinx.

Copyright © 2017-2026 Asif Saif Uddin, core team & contributors. All rights reserved.
Celery is licensed under The BSD License (3 Clause, also known as the new BSD license). The license is an OSI approved Open Source license and is GPL-compatible.
https://docs.celeryq.dev/en/stable/userguide/sphinx.html