Fixes to Sphinx xref abbrs

celery/utils/__init__.py

@@ -172,6 +172,6 @@ from .imports import (          # noqa
         qualname as get_full_cls_name, symbol_by_name as get_cls_by_name,
         instantiate, import_from_cwd
 )
-from .functional import chunks, noop            # noqa
-from kombu.utils import cached_property, uuid   # noqa
+from .functional import chunks, noop                    # noqa
+from kombu.utils import cached_property, kwdict, uuid   # noqa
 gen_unique_id = uuid

docs/_ext/celerydocs.py

@@ -3,8 +3,7 @@ from docutils import nodes
 from sphinx.environment import NoUri
 from sphinx.util.nodes import make_refnode
 
-ABBR = {
-    "": "celery.app.base.Celery",
+APPATTRS = {
     "amqp": "celery.app.amqp.AMQP",
     "backend": "celery.backends.base.BaseBackend",
     "control": "celery.app.control.Control",
@@ -22,43 +21,79 @@ ABBR = {
     "Task": "celery.app.task.BaseTask",
 }
 
+ABBRS = {
+    "Celery": "celery.app.Celery",
+}
+
 ABBR_EMPTY = {
     "exc": "celery.exceptions",
 }
-DEFAULT_EMPTY = "celery.app.base.Celery"
+DEFAULT_EMPTY = "celery.app.Celery"
+
+
+def typeify(S, type):
+    if type in ("meth", "func"):
+        return S + '()'
+    return S
 
 
-def shorten(S, base):
+def shorten(S, newtarget, src_dict):
     if S.startswith('@-'):
         return S[2:]
     elif S.startswith('@'):
-        print("S: %r BASE: %r" % (S, base))
-        return '.'.join([base, S[1:]])
+        if src_dict is APPATTRS:
+            return '.'.join([pkg_of(newtarget), S[1:]])
+        return S[1:]
     return S
 
 
+def get_abbr(pre, rest, type):
+    if pre:
+        for d in APPATTRS, ABBRS:
+            try:
+                return d[pre], rest, d
+            except KeyError:
+                pass
+        raise KeyError(pre)
+    else:
+        for d in APPATTRS, ABBRS:
+            try:
+                return d[rest], '', d
+            except KeyError:
+                pass
+    return ABBR_EMPTY.get(type, DEFAULT_EMPTY), rest, ABBR_EMPTY
+
+
+
 def resolve(S, type):
-    X = S
+    is_appattr = False
     if S.startswith('@'):
         S = S.lstrip('@-')
         try:
             pre, rest = S.split('.', 1)
         except ValueError:
             pre, rest = '', S
-        return '.'.join([ABBR[pre] if pre
-                                   else ABBR_EMPTY.get(type, DEFAULT_EMPTY),
-                         rest])
+
+        target, rest, src = get_abbr(pre, rest, type)
+        return '.'.join([target, rest]) if rest else target, src
+    return S, None
 
 
 def pkg_of(module_fqdn):
     return module_fqdn.split('.', 1)[0]
 
 
-def modify_textnode(T, newtarget, node):
+def basename(module_fqdn):
+    return module_fqdn.lstrip('@').rsplit('.', -1)[-1]
+
+
+def modify_textnode(T, newtarget, node, src_dict, type):
     src = node.children[0].rawsource
     return nodes.Text(
-        T.lstrip('@') if '~' in src else shorten(T, pkg_of(newtarget)),
-        src
+        typeify(basename(T), type) if '~' in src
+                                   else typeify(shorten(T, newtarget,
+                                                        src_dict), type),
+        src,
     )
 
 
@@ -67,10 +102,12 @@ def maybe_resolve_abbreviations(app, env, node, contnode):
     target = node["reftarget"]
     type = node["reftype"]
     if target.startswith('@'):
-        newtarget = node["reftarget"] = resolve(target, type)
+        newtarget, src_dict = resolve(target, type)
+        node["reftarget"] = newtarget
         # shorten text if '~' is not enabled.
         if len(contnode) and isinstance(contnode[0], nodes.Text):
-                contnode[0] = modify_textnode(target, newtarget, node)
+                contnode[0] = modify_textnode(target, newtarget, node,
+                                              src_dict, type)
         if domainname:
             try:
                 domain = env.domains[node.get("refdomain")]

docs/getting-started/first-steps-with-celery.rst

@@ -71,7 +71,7 @@ Let's create the file :file:`tasks.py`:
     if __name__ == "__main__":
         celery.start()
 
-The first argument to :class:`Celery` is the name of the current module,
+The first argument to :class:`~celery.app.Celery` is the name of the current module,
 this is needed so that names can be automatically generated, the second
 argument is the broker keyword argument which specifies the URL of the
 message broker we want to use.
@@ -110,9 +110,9 @@ Executing the task
 ==================
 
 Whenever we want to execute our task, we use the
-:meth:`~celery.task.base.Task.delay` method of the task class.
+:meth:`~@Task.delay` method of the task.
 
-This is a handy shortcut to the :meth:`~celery.task.base.Task.apply_async`
+This is a handy shortcut to the :meth:`~@Task.apply_async`
 method which gives greater control of the task execution (see
 :ref:`guide-executing`).
 
@@ -122,7 +122,7 @@ method which gives greater control of the task execution (see
 The task should now be executed by the worker you started earlier,
 and you can verify that by looking at the workers console output.
 
-Applying a task returns an :class:`~celery.result.AsyncResult` instance,
+Applying a task returns an :class:`~@AsyncResult` instance,
 which can be used to check the state of the task, wait for the task to finish
 or get its return value (or if the task failed, the exception and traceback).
 But this isn't enabled by default, and you have to configure Celery to
@@ -151,7 +151,7 @@ you can configure::
 To read more about result backends please see :ref:`task-result-backends`.
 
 Now with the result backend configured, let's execute the task again.
-This time we'll hold on to the :class:`~celery.result.AsyncResult`::
+This time we'll hold on to the :class:`~@AsyncResult`::
 
     >>> result = add.delay(4, 4)
 
@@ -172,7 +172,7 @@ Here's some examples of what you can do when you have results::
     >>> result.successful() # returns True if the task didn't end in failure.
     True
 
-If the task raises an exception, the return value of `result.successful()`
+If the task raises an exception, the return value of :meth:`~@AsyncResult.successful`
 will be :const:`False`, and `result.result` will contain the exception instance
 raised by the task.
 

docs/reference/celery.app.rst

@@ -8,7 +8,7 @@
     Application
     -----------
 
-    .. autoclass:: App
+    .. autoclass:: Celery
 
         .. attribute:: main
 
@@ -30,14 +30,13 @@
 
         .. automethod:: task
         .. automethod:: create_task_cls
-        .. automethod:: TaskSet
         .. automethod:: send_task
-        .. automethod:: AsyncResult
-        .. automethod:: TaskSetResult
+        .. autoattribute:: AsyncResult
+        .. autoattribute:: TaskSetResult
 
         .. automethod:: worker_main
-        .. automethod:: Worker
-        .. automethod:: Beat
+        .. autoattribute:: Worker
+        .. autoattribute:: Beat
 
         .. automethod:: broker_connection
         .. automethod:: with_default_connection

docs/xreftest.rst

@@ -0,0 +1,38 @@
+xreftest
+========
+
+Must not be in public docs
+--------------------------
+
+
+``meth @Task.retry``: :meth:`@Task.retry`
+
+``meth @-Task.retry``: :meth:`@-Task.retry`
+
+``meth ~@Task.retry``: :meth:`~@Task.retry`
+
+
+``class @Celery``: :class:`@Celery`
+
+``class @-Celery``: :class:`@-Celery`
+
+``class ~@Celery``: :class:`~@Celery`
+
+
+``attr @amqp``:   :attr:`@amqp`
+
+``attr @-amqp``:   :attr:`@-amqp`
+
+``attr ~@amqp``:   :attr:`~@amqp`
+
+
+``meth @amqp.get_task_consumer``:  :meth:`@amqp.get_task_consumer`
+
+``meth @-amqp.get_task_consumer``: :meth:`@-amqp.get_task_consumer`
+
+``meth ~@amqp.get_task_consumer``: :meth:`~@amqp.get_task_consumer`
+
+
+``exc @NotRegistered``: :exc:`@NotRegistered`
+
+``exc @-NotRegistered``: :exc:`@-NotRegistered`