Adds Sphinx extension for autodoc documentation of tasks: celery.contrib.sphinx. Closes celery#1833

Author: ask

celery/contrib/sphinx.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""
+celery.contrib.sphinx
+=====================
+
+Sphinx documentation plugin
+
+**Usage**
+
+Add the extension to your :file:`docs/conf.py` configuration module:
+
+.. code-block:: python
+
+    extensions = (...,
+                  'celery.contrib.sphinx')
+
+If you would like to change the prefix for tasks in reference documentation
+then you can change the ``celery_task_prefix`` configuration value:
+
+.. code-block:: python
+
+    celery_task_prefix = '(task)'  # < default
+
+
+With the extension installed `autodoc` will automatically find
+task decorated objects 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 manually document a task.
+
+"""
+from __future__ import absolute_import
+
+from inspect import ArgSpec, formatargspec, getargs, getargspec
+
+from sphinx.domains.python import PyModulelevel
+from sphinx.ext.autodoc import FunctionDocumenter
+
+from celery.app.task import BaseTask
+
+
+class TaskDocumenter(FunctionDocumenter):
+    objtype = 'task'
+    member_order = 11
+
+    @classmethod
+    def can_document_member(cls, member, membername, isattr, parent):
+        return isinstance(member, BaseTask) and getattr(member, '__wrapped__')
+
+    def format_args(self):
+        wrapped = getattr(self.object, '__wrapped__')
+        if wrapped is not None:
+            argspec = getargspec(wrapped)
+            fmt = formatargspec(*argspec)
+            fmt = fmt.replace('\\', '\\\\')
+            return fmt
+        return ''
+
+    def document_members(self, all_members=False):
+        pass
+
+
+class TaskDirective(PyModulelevel):
+
+    def get_signature_prefix(self, sig):
+        return self.env.config.celery_task_prefix
+
+
+def setup(app):
+    app.add_autodocumenter(TaskDocumenter)
+    app.domains['py'].directives['task'] = TaskDirective
+    app.add_config_value('celery_task_prefix', '(task)', True)

docs/conf.py

@@ -21,6 +21,7 @@
               'sphinx.ext.viewcode',
               'sphinx.ext.coverage',
               'sphinx.ext.intersphinx',
+              'celery.contrib.sphinx',
               'sphinxcontrib.issuetracker',
               'celerydocs']
 

docs/reference/celery.contrib.sphinx.rst

@@ -0,0 +1,4 @@
+.. currentmodule:: celery.contrib.sphinx
+
+.. automodule:: celery.contrib.sphinx
+    :members:

docs/reference/index.rst

@@ -37,6 +37,7 @@
     celery.contrib.abortable
     celery.contrib.batches
     celery.contrib.migrate
+    celery.contrib.sphinx
     celery.contrib.rdb
     celery.contrib.methods
     celery.events