使用 Sphinx 文档化任务

Documenting Tasks with Sphinx

本文档介绍如何使用 Sphinx 自动生成任务文档。

This document describes how auto-generate documentation for Tasks using Sphinx.

celery.contrib.sphinx

中文

Sphinx 文档插件用于为任务生成文档。

英文

Sphinx documentation plugin used to document tasks.

简介

Introduction

用法

Usage

中文

Celery 的 Sphinx 扩展要求 Sphinx 版本为 2.0 或更高。

在你的 docs/conf.py 配置模块中添加该扩展：

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

如果你希望在参考文档中更改任务的前缀，可以设置 celery_task_prefix 配置项：

celery_task_prefix = '(task)'  # < 默认值

安装该扩展后，autodoc 会自动识别使用装饰器标记的任务对象（例如在使用 automodule 指令时）， 并正确生成文档（同时添加 (task) 前缀）。你也可以使用 :task:proj.tasks.add 语法引用任务。

你也可以使用 .. autotask:: 来手动为某个任务编写文档。

英文

The Celery extension for Sphinx requires Sphinx 2.0 or later.

Add the extension to your docs/conf.py configuration module:

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

If you'd like to change the prefix for tasks in reference documentation then you can change the celery_task_prefix configuration value:

celery_task_prefix = '(task)'  # < default

With the extension installed autodoc will automatically find task decorated objects (e.g. when using the automodule directive) and generate the correct (as well as add a (task) prefix), and you can also refer to the tasks using :task:proj.tasks.add syntax.

Use .. autotask:: to alternatively manually document a task.

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

Sphinx task directive.

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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

Document task definitions.

classmethod can_document_member(member, membername, isattr, parent)

Called to see if a member can be documented by this Documenter.

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

format_args()

Format the argument signature of self.object.

Should return None if the object does not have a signature.

member_order = 11

order if autodoc_member_order is set to 'groupwise'

objtype = 'task'

name by which the directive is called (auto...) and the default generated directive name

celery.contrib.sphinx.autodoc_skip_member_handler(app, what, name, obj, skip, options)

Handler for autodoc-skip-member event.

celery.contrib.sphinx.setup(app)

Setup Sphinx extension.