Update Documentation

README.rst

@@ -64,6 +64,7 @@ Command line
 ------------
 
 .. code:: console
+
     usage: chat_downloader [-h] [--version] [--start_time START_TIME]
                            [--end_time END_TIME]
                            [--message_types MESSAGE_TYPES | --message_groups MESSAGE_GROUPS]

chat_downloader/sites/common.py

@@ -24,6 +24,17 @@
 
 class Image():
     def __init__(self, url, width=None, height=None, image_id=None):
+        """Create an Image object
+
+        :param url: The URL of the actual image
+        :type url: str
+        :param width: The width of the image, defaults to None
+        :type width: int, optional
+        :param height: The height of the image, defaults to None
+        :type height: int, optional
+        :param image_id: A identifier for the image, usually of the form: {width}x{height}, defaults to None
+        :type image_id: str, optional
+        """
         self.url = url
 
         if self.url.startswith('//'):
@@ -38,6 +49,11 @@ def __init__(self, url, width=None, height=None, image_id=None):
             self.id = image_id
 
     def json(self):
+        """Return the JSON representation of an Image
+
+        :return: JSON representation of the object
+        :rtype: dict
+        """
         return {k: v for k, v in self.__dict__.items() if v is not None}
 
 

docs/cli.rst

@@ -19,8 +19,25 @@ The output of which is as follows:
 Examples
 --------
 
+#. Message groups and types
+
+   Options are specified by a space- or comma-separated list. If you specify more than one item, enclose the argument in quotation marks.
+
+   - Using message groups:
+
+   .. code:: console
+
+       $ chat_downloader https://www.youtube.com/watch?v=n5aQeLwwEns --message_groups "messages superchat"
+
+   -  Using message types:
+
+   .. code:: console
+
+       $ chat_downloader https://www.youtube.com/watch?v=n5aQeLwwEns --message_types membership_item
+
+
 #. Output to file
 
 .. code:: console
 
-   $ chat_downloader -h
+   $ chat_downloader https://www.youtube.com/watch?v=n5aQeLwwEns --output chat.json

docs/generate_readme.py

@@ -21,7 +21,7 @@ def replace_cmd_output(match):
     text = output[0].decode()
 
 
-    return '.. code:: console\n' + ''.join(map(lambda x: padding + x, text.splitlines(True)))
+    return '.. code:: console\n\n' + ''.join(map(lambda x: padding + x, text.splitlines(True)))
 
 substitution = re.sub(cmd_regex, replace_cmd_output, readme)
 

docs/index.rst

@@ -11,6 +11,7 @@ Overview
    cli
    source/index
    items
+   options
    contributing
    changelog
 

docs/items.rst

@@ -39,15 +39,17 @@ the relevant documentation in a pull request.
      - Message type of the item.
    * - author
      - dictionary
-     - A dictionary containing information about the user who sent the message. For author fields, see here.
+     - A dictionary containing information about the user who sent the message. For author fields, see :ref:`here <Author fields table>`.
    * - time_in_seconds
      - float
      - The number of seconds after the video began, that the message was sent.  This is only present for replays/vods/clips (i.e. a video which is not live).
    * - time_text
      - string
      - Human-readable format for `time_in_seconds`.
 
-Documentation for other (less common) fields can be found here.
+Documentation for other (less common) fields can be found :ref:`here <Other fields table>`.
+
+.. _Author fields table:
 
 .. list-table:: Author fields
    :widths: 20 10 70
@@ -76,10 +78,10 @@ Documentation for other (less common) fields can be found here.
      - URL of the author's channel/page.
    * - images
      - list
-     - A list which contains different sizes of the author's profile picture. See here for the fields that an image may have.
+     - A list which contains different sizes of the author's profile picture. See :ref:`here <Image fields table>` for the fields that an image may have.
    * - badges
      - list
-     - A list of the author's badges. See here for the fields that a badge may have.
+     - A list of the author's badges. See :ref:`here <Badge fields table>` for the fields that a badge may have.
    * - gender
      - string
      - Gender of the author.
@@ -99,6 +101,7 @@ Documentation for other (less common) fields can be found here.
      - boolean
      - `True` if the user is verified, `False` otherwise.
 
+.. _Image fields table:
 
 .. list-table:: Image fields
    :widths: 20 10 70
@@ -120,6 +123,7 @@ Documentation for other (less common) fields can be found here.
      - string
      - A identifier for the image, usually of the form: {width}x{height}
 
+.. _Badge fields table:
 
 .. list-table:: Badge fields
    :widths: 20 10 70
@@ -145,7 +149,7 @@ Documentation for other (less common) fields can be found here.
      - Name of the badge icon.
    * - icons
      - list
-     - A list of images for the badge icons. See here for potential fields.
+     - A list of images for the badge icons. See :ref:`here <Image fields table>` for potential fields.
    * - description
      - string
      - The description of the badge.
@@ -159,36 +163,7 @@ Documentation for other (less common) fields can be found here.
      - string
      - URL to visit if the badge is clicked.
 
-
-.. list-table:: Common fields
-   :widths: 20 10 70
-   :header-rows: 1
-
-   * - Field
-     - Type
-     - Description
-   * - timestamp
-     - float
-     - UNIX time (in microseconds) of when the message was sent.
-   * - message
-     - string
-     - Actual content/text of the chat item.
-   * - message_id
-     - string
-     - Identifier for the chat item.
-   * - message_type
-     - string
-     - Message type of the item.
-   * - author
-     - dictionary
-     - A dictionary containing information about the user who sent the message. For author fields, see here.
-   * - time_in_seconds
-     - float
-     - The number of seconds after the video began, that the message was sent.  This is only present for replays/vods/clips (i.e. a video which is not live).
-   * - time_text
-     - string
-     - Human-readable format for `time_in_seconds`.
-
+.. _Other fields table:
 
 .. list-table:: Other fields
    :widths: 20 10 70
@@ -223,13 +198,13 @@ Documentation for other (less common) fields can be found here.
      - Whether the viewer is the creator or not.
    * - sticker_images
      - list
-     - A list of the sticker image in different sizes. See here for the fields which an image may have.
+     - A list which contains different sizes of the sticker image. See :ref:`here <Image fields table>` for image fields.
    * - sponsor_icons
      - list
-     - A list of the sponsor image in different sizes. See here for potential fields.
+     - A list which contains different sizes of the sponsor image. See :ref:`here <Image fields table>` for image fields.
    * - ticker_icons
      - list
-     - A list of the ticker image in different sizes. See here for potential fields.
+     - A list which contains different sizes of the ticker image. See :ref:`here <Image fields table>` for image fields.
    * - ticker_duration
      - float
      - How long the ticker message is displayed for.

docs/options.rst

@@ -0,0 +1,24 @@
+General Options
+===============
+
+This page provides descriptions for the different available options. For the most part, there are two types of
+
+For implementation details, see the corresponding Command-line or Python usage guide.
+
+Message groups and types
+------------------------
+
+There are two ways to specify what types of chat messages will be included:
+
+1. Message types - The value of `message_type` for the chat object
+
+2. Message groups - A site-specific collection of message types. One message group contains a list of message types, and each site has a number of message groups which can be used. See below for message groups (and their associated message types) for the supported sites.
+
+Please note that these two options are **mutually exclusive**. So, you may only specify one at a time.
+
+For examples, see Command-line or Python Usage
+
+
+
+Outputting to a file
+--------------------

docs/source/chat_downloader.rst

@@ -6,7 +6,31 @@
 :py:class:`ChatDownloader`
 **************************
 
+
 .. autoclass:: chat_downloader.ChatDownloader
     :members:
     :undoc-members:
     :show-inheritance:
+
+Examples
+--------
+
+#. Message groups and types
+
+   Options are specified as a list of strings.
+
+   .. code:: python
+
+       from chat_downloader import ChatDownloader
+
+       downloader = ChatDownloader()
+
+       url = 'https://www.youtube.com/watch?v=n5aQeLwwEns'
+
+       # 1. Using message groups:
+       groups_example = downloader.get_chat(url, message_groups=['messages', 'superchat'])
+
+       # 2. Using message types:
+       types_example = downloader.get_chat(url, message_types=['membership_item'])
+
+#. 2