Update and improve documentation for API.media_upload

Automatically use docstring for documentation
Improve documentation order
Improve formatting

diff --git a/docs/api.rst b/docs/api.rst
index 8d79727ba13cad0fedc0c311446839359ace7b49..2423e170be49e7630b6e69306d9a8e348d28c22e 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -213,6 +213,8 @@ Upload media
 
 .. automethod:: API.create_media_metadata
 
+.. automethod:: API.media_upload
+
 
 Account Methods
 ---------------
@@ -430,27 +432,6 @@ Utility methods
 Media methods
 -------------
 
-.. method:: API.media_upload(filename, [file], [chunked], [media_category], \
-                             [additional_owners])
-
-   Use this to upload media to Twitter.
-   This calls either :func:`API.simple_upload` or :func:`API.chunked_upload`.
-   Chunked media upload is automatically used for videos.
-   If ``chunked`` is set or the media is a video, ``wait_for_async_finalize``
-   can be specified as a keyword argument to be passed to
-   :func:`API.chunked_upload`.
-
-   :param filename: |filename|
-   :param file: |file|
-   :param chunked: Whether or not to use chunked media upload. Videos use
-                   chunked upload regardless of this parameter. Defaults to
-                   False.
-   :param media_category: |media_category|
-   :param additional_owners: |additional_owners|
-
-   :rtype: :class:`Media` object
-
-
 .. method:: API.simple_upload(filename, [file], [media_category], \
                               [additional_owners])
 

diff --git a/tweepy/api.py b/tweepy/api.py
index 1dd0ce962b7ac23d1d51893dfc46de03aa9a7537..252e1fb2a24b494387ef25236cc755d6c739915f 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -2346,7 +2346,26 @@ class API:
 
     def media_upload(self, filename, *, file=None, chunked=False,
                      media_category=None, additional_owners=None, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
+        """media_upload(filename, *, file, chunked, media_category, \
+                        additional_owners)
+
+        Use this to upload media to Twitter. This calls either
+        :func:`API.simple_upload` or :func:`API.chunked_upload`. Chunked media
+        upload is automatically used for videos. If ``chunked`` is set or the
+        media is a video, ``wait_for_async_finalize`` can be specified as a
+        keyword argument to be passed to :func:`API.chunked_upload`.
+
+        :param filename: |filename|
+        :param file: |file|
+        :param chunked: Whether or not to use chunked media upload. Videos use
+                        chunked upload regardless of this parameter. Defaults
+                        to ``False``.
+        :param media_category: |media_category|
+        :param additional_owners: |additional_owners|
+
+        :rtype: :class:`Media` object
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
         """
         h = None
         if file is not None: