doc: Page intro improvements

The introductionary sections of as-module and cli-options have been
rewritten. Further, Instaloader's short-description is now included in
the sidebar.

docs/_templates/caption.html

@@ -1 +1,2 @@
 <h2><a href="index.html">Instaloader</a></h2>
+<p>Download pictures (or videos) along with their captions and other metadata from Instagram.</p>

docs/as-module.rst

@@ -5,68 +5,65 @@ Python Module :mod:`instaloader`
 
 .. highlight:: python
 
-You may also use parts of Instaloader as library to do other interesting
+Instaloader exposes its internally used methods as a Python module, making it a
-things.
+**powerful and easy-to-use Python API for Instagram**, allowing to further
+customize obtaining media and metadata.
 
-For example, to get a list of all followees and a list of all followers of a profile, do
+Start with getting an instance of :class:`Instaloader`::
-
-.. code:: python
 
     import instaloader
 
     # Get instance
-    loader = instaloader.Instaloader()
+    L = instaloader.Instaloader()
 
-    # Login
+    # Optionally, login or load session
-    loader.interactive_login(USERNAME)
+    L.login(USER, PASSWORD)        # (login)
+    L.interactive_login(USER)      # (ask password on terminal)
+    L.load_session_from_file(USER) # (load session created w/
+                                   #  `instaloader -l USERNAME`)
+
+:mod:`instaloader` provides the :class:`Post` structure, which represents a
+picture, video or sidecar (set of multiple pictures/videos) posted in a user's
+profile. :class:`Instaloader` provides methods to iterate over Posts from a
+certain source::
+
+    for post in L.get_hashtag_posts('cat'):
+        # post is an instance of instaloader.Post
+        L.download_post(post, target='#cat')
+
+Besides :func:`Instaloader.get_hashtag_posts`, there is
+:func:`Instaloader.get_feed_posts` and :func:`Instaloader.get_profile_posts`.
+Also, :class:`Post` instances can be created with :func:`Post.from_shortcode`
+and :func:`Post.from_mediaid`.
+
+Further, information about profiles can be easily obtained. For example, you may
+print a list of all followees and followers of a profile with::
 
     # Print followees
     print(PROFILE + " follows these profiles:")
-    for f in loader.get_followees(PROFILE):
+    for f in L.get_followees(PROFILE):
         print("\t%s\t%s" % (f['username'], f['full_name']))
 
     # Print followers
     print("Followers of " + PROFILE + ":")
-    for f in loader.get_followers(PROFILE):
+    for f in L.get_followers(PROFILE):
         print("\t%s\t%s" % (f['username'], f['full_name']))
 
-Then, you may download all pictures of all followees with
+Then, you may download all pictures of all followees with::
 
-.. code:: python
+    for f in L.get_followees(PROFILE):
+        L.download_profile(f['username'])
 
-    for f in loader.get_followees(PROFILE):
+Each Instagram profile has its own unique ID which stays unmodified even if a
-        loader.download_profile(f['username'])
+user changes his/her username. To get said ID, given the profile's name, you may
+call::
 
-You could also download your last 20 liked pics with
+    L.get_id_by_username(PROFILE_NAME)
-
-.. code:: python
-
-    loader.download_feed_posts(max_count=20, fast_update=True,
-                               filter_func=lambda post: post.viewer_has_liked)
-
-To download the last 20 pictures with hashtag #cat, do
-
-.. code:: python
-
-    loader.download_hashtag('cat', max_count=20)
-
-Generally, :class:`Instaloader` provides methods to iterate over the Posts from
-a certain source.
-
-.. code:: python
-
-    for post in loader.get_hashtag_posts('cat'):
-        # post is an instance of instaloader.Post
-        loader.download_post(post, target='#cat')
-
-Each Instagram profile has its own unique ID which stays unmodified even
-if a user changes his/her username. To get said ID, given the profile's
-name, you may call
-
-.. code:: python
-
-    loader.get_id_by_username(PROFILE_NAME)
 
+A reference of the many methods provided by the :mod:`instaloader` module is
+provided in the remainder of this document. Feel free to direct any issue or
+contribution to
+`Instaloader on Github <https://github.com/Thammus/instaloader>`__.
 
 ``Instaloader`` (Main Class)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/cli-options.rst

@@ -1,24 +1,26 @@
 Command Line Options
 ====================
 
-The following flags can be given to Instaloader to specify how profiles should
+Instaloader is invoked with::
-be downloaded.
 
-To get a list of all flags, their abbreviations and their descriptions,
+   $ instaloader [options] target [target ...]
-run ``instaloader --help``.
+
+where ``target`` is a ``profile``, a ``"#hashtag"``, ``@profile`` (all profiles
+that *profile* is following), or if logged in ``:feed`` (pictures from your
+feed) or ``:stories`` (stories of your followees).
+
+Here we explain the additional options that can be given to Instaloader to
+customize its behavior.  To get a list of all flags, their abbreviations and
+their descriptions, you may also run ``instaloader --help``.
 
 What to Download
 ^^^^^^^^^^^^^^^^
 
-Specify a list of profiles or #hashtags. For each of these, Instaloader
+Specify a list of targets (profiles, #hashtags, ``:feed`` or ``:stories``). For
-creates a folder and downloads all posts along with the pictures's
+each of these, Instaloader creates a folder and stores all posts along with the
-captions and the current **profile picture**. If an already-downloaded profile
+pictures's captions and the current **profile picture** there. If an
-has been renamed, Instaloader automatically **finds it by its unique ID** and
+already-downloaded profile has been renamed, Instaloader automatically **finds
-renames the folder likewise.
+it by its unique ID** and renames the folder likewise.
-
-Instead of a *profile* or a *#hashtag*, the special targets
-``:feed`` (pictures from your feed) and
-``:stories`` (stories of your followees) can be specified.
 
 .. option:: --profile-pic-only