This document describes the current stable version of Celery (5.6). For development docs, go here.

# Documenting Tasks with Sphinx

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

## celery.contrib.sphinx

Sphinx documentation plugin used to document tasks.

### Introduction

#### Usage

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.

#### Sphinx 9.0+ Compatibility

Sphinx 9.0 introduced a rewritten autodoc implementation. The Celery extension requires the legacy class-based autodoc mode to function correctly. When using Sphinx 9.0 or later, add the following to your `conf.py`:

    autodoc_use_legacy_class_based = True

The extension will automatically enable this setting if not configured, but it is recommended to set it explicitly to avoid warnings.

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.