Slight docstring fixes

celery/app/base.py

@@ -283,13 +283,12 @@ class Celery(object):
         """Clean up after the application.
 
         Only necessary for dynamically created apps for which you can
-        use the :keyword:`with` statement instead:
+        use the :keyword:`with` statement instead
 
-        .. code-block:: python
-
-            with Celery(set_as_current=False) as app:
-                with app.connection_for_write() as conn:
-                    pass
+        Example:
+            >>> with Celery(set_as_current=False) as app:
+            ...     with app.connection_for_write() as conn:
+            ...         pass
         """
         self._pool = None
         _deregister_app(self)
@@ -498,8 +497,7 @@ class Celery(object):
         The value of the environment variable must be the name
         of a module to import.
 
-        .. code-block:: pycon
-
+        Example:
             >>> os.environ['CELERY_CONFIG_MODULE'] = 'myapp.celeryconfig'
             >>> celery.config_from_envvar('CELERY_CONFIG_MODULE')
         """
@@ -552,7 +550,7 @@ class Celery(object):
 
         If the name is empty, this will be delegated to fix-ups (e.g. Django).
 
-        For example if you have an (imagined) directory tree like this:
+        For example if you have an directory layout like this:
 
         .. code-block:: text
 
@@ -670,14 +668,16 @@ class Celery(object):
     def connection_for_read(self, url=None, **kwargs):
         """Establish connection used for consuming.
 
-        See :meth:`connection` for supported arguments.
+        See Also:
+            :meth:`connection` for supported arguments.
         """
         return self._connection(url or self.conf.broker_read_url, **kwargs)
 
     def connection_for_write(self, url=None, **kwargs):
         """Establish connection used for producing.
 
-        See :meth:`connection` for supported arguments.
+        See Also:
+            :meth:`connection` for supported arguments.
         """
         return self._connection(url or self.conf.broker_write_url, **kwargs)
 
@@ -694,7 +694,6 @@ class Celery(object):
 
         Arguments:
             url: Either the URL or the hostname of the broker to use.
-
             hostname (str): URL, Hostname/IP-address of the broker.
                 If a URL is used, then the other argument below will
                 be taken from the URL instead.
@@ -859,10 +858,7 @@ class Celery(object):
         self.on_after_fork.send(sender=self)
 
     def signature(self, *args, **kwargs):
-        """Return a new :class:`~celery.canvas.Signature` bound to this app.
-
-        See :meth:`~celery.signature`
-        """
+        """Return a new :class:`~celery.Signature` bound to this app."""
         kwargs['app'] = self
         return self.canvas.signature(*args, **kwargs)
 
@@ -983,19 +979,28 @@ class Celery(object):
 
     @cached_property
     def Worker(self):
-        """Worker application. See :class:`~@Worker`."""
+        """Worker application.
+
+        See Also:
+            :class:`~@Worker`.
+        """
         return self.subclass_with_self('celery.apps.worker:Worker')
 
     @cached_property
     def WorkController(self, **kwargs):
-        """Embeddable worker. See :class:`~@WorkController`."""
+        """Embeddable worker.
+
+        See Also:
+            :class:`~@WorkController`.
+        """
         return self.subclass_with_self('celery.worker:WorkController')
 
     @cached_property
     def Beat(self, **kwargs):
         """:program:`celery beat` scheduler application.
 
-        See :class:`~@Beat`.
+        See Also:
+            :class:`~@Beat`.
         """
         return self.subclass_with_self('celery.apps.beat:Beat')
 
@@ -1012,7 +1017,8 @@ class Celery(object):
     def AsyncResult(self):
         """Create new result instance.
 
-        See :class:`celery.result.AsyncResult`.
+        See Also:
+            :class:`celery.result.AsyncResult`.
         """
         return self.subclass_with_self('celery.result:AsyncResult')
 
@@ -1024,7 +1030,8 @@ class Celery(object):
     def GroupResult(self):
         """Create new group result instance.
 
-        See :class:`celery.result.GroupResult`.
+        See Also:
+            :class:`celery.result.GroupResult`.
         """
         return self.subclass_with_self('celery.result:GroupResult')
 
@@ -1032,7 +1039,8 @@ class Celery(object):
     def pool(self):
         """Broker connection pool: :class:`~@pool`.
 
-        This attribute is not related to the workers concurrency pool.
+        Note:
+            This attribute is not related to the workers concurrency pool.
         """
         if self._pool is None:
             self._ensure_after_fork()
@@ -1115,7 +1123,8 @@ class Celery(object):
     def tasks(self):
         """Task registry.
 
-        Accessing this attribute will also finalize the app.
+        Warning:
+            Accessing this attribute will also auto-finalize the app.
         """
         self.finalize(auto=True)
         return self._tasks

celery/canvas.py

@@ -1082,7 +1082,7 @@ class chord(Signature):
 
     Example:
 
-        The chrod:
+        The chord:
 
         .. code-block:: pycon
 

celery/contrib/migrate.py

@@ -174,11 +174,12 @@ def move(predicate, connection=None, exchange=None, routing_key=None,
 
         move(is_wanted_task, transform=transform)
 
-    The predicate may also return a tuple of ``(exchange, routing_key)``
-    to specify the destination to where the task should be moved,
-    or a :class:`~kombu.entitiy.Queue` instance.
-    Any other true value means that the task will be moved to the
-    default exchange/routing_key.
+    Note:
+        The predicate may also return a tuple of ``(exchange, routing_key)``
+        to specify the destination to where the task should be moved,
+        or a :class:`~kombu.entitiy.Queue` instance.
+        Any other true value means that the task will be moved to the
+        default exchange/routing_key.
     """
     app = app_or_default(app)
     queues = [_maybe_queue(app, queue) for queue in source or []] or None

celery/signals.py

@@ -7,7 +7,9 @@ both workers and clients.
 Functions can be connected to these signals, and connected
 functions are called whenever a signal is called.
 
-See :ref:`signals` for more information.
+.. seealso::
+
+    :ref:`signals` for more information.
 """
 from __future__ import absolute_import, unicode_literals
 

celery/task/base.py

@@ -184,15 +184,14 @@ class Task(BaseTask):
         Should be replaced with :meth:`@Celery.connection`
         instead, or by acquiring connections from the connection pool:
 
-        .. code-block:: python
-
-            # using the connection pool
-            with celery.pool.acquire(block=True) as conn:
-                ...
-
-            # establish fresh connection
-            with celery.connection_for_write() as conn:
-                ...
+        Examples:
+            >>> # using the connection pool
+            >>> with celery.pool.acquire(block=True) as conn:
+            ...     pass
+
+            >>> # establish fresh connection
+            >>> with celery.connection_for_write() as conn:
+            ...     pass
         """
         return self._get_app().connection_for_write()
 
@@ -208,7 +207,7 @@ class Task(BaseTask):
                 with app.amqp.Producer(conn) as prod:
                     my_task.apply_async(producer=prod)
 
-            or event better is to use the :class:`@amqp.producer_pool`:
+            or even better is to use the :class:`@amqp.producer_pool`:
 
             .. code-block:: python
 
@@ -230,7 +229,7 @@ class Task(BaseTask):
         """Deprecated method used to get consumer for the queue
         this task is sent to.
 
-        Should be replaced with :class:`@amqp.TaskConsumer` instead:
+        Should be replaced by :class:`@amqp.TaskConsumer`.
         """
         Q = self._get_app().amqp
         connection = connection or self.establish_connection()

celery/utils/imports.py

@@ -48,7 +48,8 @@ else:
 def instantiate(name, *args, **kwargs):
     """Instantiate class by name.
 
-    See :func:`symbol_by_name`.
+    See Also:
+        :func:`symbol_by_name`.
     """
     return symbol_by_name(name)(*args, **kwargs)