Update docs and docstrings concerning highlights

docs/cli-options.rst

@@ -115,6 +115,13 @@ What to Download of each Profile
    Also **download stories** of each profile that is downloaded. Requires
    :option:`--login`.
 
+.. option:: --highlights
+
+   Also **download highlights** of each profile that is downloaded. Requires
+   :option:`--login`.
+
+   .. versionadded:: 4.1
+
 .. option:: --tagged
 
    Also download posts where each profile is tagged.

instaloader/instaloader.py

@@ -494,7 +494,9 @@ class Instaloader:
     @_requires_login
     def get_highlights(self, user: Union[int, Profile]) -> Iterator[Highlight]:
         """Get all highlights from a user.
-        To use this, one needs to be logged in
+        To use this, one needs to be logged in.
+
+        .. versionadded:: 4.1
 
         :param user: ID or Profile of the user whose highlights should get fetched.
         """
@@ -517,7 +519,9 @@ class Instaloader:
                             storyitem_filter: Optional[Callable[[StoryItem], bool]] = None) -> None:
         """
         Download available highlights from a user whose ID is given.
-        To use this, one needs to be logged in
+        To use this, one needs to be logged in.
+
+        .. versionadded:: 4.1
 
         :param user: ID or Profile of the user whose highlights should get downloaded.
         :param fast_update: If true, abort when first already-downloaded picture is encountered

instaloader/structures.py

@@ -869,6 +869,28 @@ class Story:
 
 
 class Highlight(Story):
+    """
+    Structure representing a user's highlight with its associated story items.
+
+    Provides methods for accessing highlight properties, as well as :meth:`Highlight.get_items` to request associated
+    :class:`StoryItem` nodes. Highlights are returned by :meth:`Instaloader.get_highlights`.
+
+    With a logged-in :class:`Instaloader` instance `L`, you may download all highlights of a :class:`Profile` instance
+    USER with::
+
+       for highlight in L.get_highlights(USER):
+           # highlight is a Highlight object
+           for item in highlight.get_items():
+               # item is a StoryItem object
+               L.download_storyitem(item, '{}/{}'.format(highlight.owner_username, highlight.title))
+
+    This class implements == and is hashable.
+
+    :param context: :class:`InstaloaderContext` instance used for additional queries if necessary.
+    :param node: Dictionary containing the available information of the highlight as returned by Instagram.
+    :param owner: :class:`Profile` instance representing the owner profile of the highlight.
+
+    .. versionadded:: 4.1"""
 
     def __init__(self, context: InstaloaderContext, node: Dict[str, Any], owner: Optional[Profile] = None):
         super().__init__(context, node)