Checklist

• I have verified that the issue exists against the main branch of Celery.
• This has already been asked to the discussions forum first.
• I have read the relevant section in the
  contribution guide
  on reporting bugs.
• I have checked the issues list
  for similar or identical bug reports.
• I have checked the pull requests list
  for existing proposed fixes.
• I have checked the commit log
  to find out if the bug was already fixed in the main branch.
• I have included all related issues and possible duplicate issues
  in this issue (If there are none, check this box anyway).
• I have tried to reproduce the issue with pytest-celery and added the reproduction script below.

Mandatory Debugging Information

• I have included the output of celery -A proj report in the issue.
  (if you are not able to do this, then at least specify the Celery
  version affected).
• I have verified that the issue exists against the main branch of Celery.
• I have included the contents of pip freeze in the issue.
• I have included all the versions of all the external dependencies required
  to reproduce this bug.

Optional Debugging Information

• I have tried reproducing the issue on more than one Python version
  and/or implementation.
• I have tried reproducing the issue on more than one message broker and/or
  result backend.
• I have tried reproducing the issue on more than one version of the message
  broker and/or result backend.
• I have tried reproducing the issue on more than one operating system.
• I have tried reproducing the issue on more than one workers pool.
• I have tried reproducing the issue with autoscaling, retries,
  ETA/Countdown & rate limits disabled.
• I have tried reproducing the issue after downgrading
  and/or upgrading Celery and its dependencies.

Related Issues and Possible Duplicates

Related Issues

• None

Possible Duplicates

• None

Environment & Settings

Celery version:

software -> celery:5.5.3 (immunity) kombu:5.5.4 py:3.13.7
            billiard:4.2.1 py-amqp:5.3.1
platform -> system:Linux arch:64bit, ELF
            kernel version:6.5.0-45-generic imp:CPython
loader   -> celery.loaders.default.Loader
settings -> transport:amqp results:disabled

deprecated_settings: None

Steps to Reproduce

Required Dependencies

• Minimal Python Version: All
• Minimal Celery Version: All
• Minimal Kombu Version: N/A
• Minimal Broker Version: N/A
• Minimal Result Backend Version: N/A
• Minimal OS and/or Kernel Version: N/A
• Minimal Broker Client Version: N/A
• Minimal Result Backend Client Version: N/A

Python Packages

celery==5.5.3

Other Dependencies

Minimally Reproducible Test Case

• Document a Celery task with Sphinx
• Attempt to link to the task as described in the docs with:

:task:`my.task.function`

Expected Behavior

An automatic link is generated

Actual Behavior

Sphinx build logs produce the error

Unknown interpreted text role "task". [docutils]

This is because celery.contrib.sphinx doesn't actually register the task role, only the directives to render a task.

In its setup it should also do

from sphinx.domains.python import PyXRefRole

def setup(app):
    # ...

    app.add_object_type(
        directivename="task",
        rolename="task",
        objname="task",
        indextemplate="pair: %s; task",
    )

    app.add_role_to_domain('py', 'task', PyXRefRole(fix_parens=True))

Note that fix_parens=True causes references to tasks to render in the same way functions do i.e. path.to.task()`). I've checked and this also works with the ~ notation so you can just render the task name.

As a stopgap, these can be added to your own setup() function in your docs config. I've done this in my project and it's then successfully able to generate links.

Note: I haven't made a discussion first as this is a simple bug, and I haven't done most of the debug steps since it's not related to the version or config of Celery. It's literally just that these lines are missing from the sphinx extension.