Release of version 3.3.10

When fetching comments, likes, followees or followers, output a warning
that the used queries are rate limited.

.travis.yml

@@ -4,17 +4,26 @@ python:
  - "3.5-dev"
  - "3.6"
  - "3.6-dev"
- - "3.7-dev"
- - "nightly"
 install:
  - pip install pylint requests
+ - pip install -r docs/requirements.txt
 script:
- - python3 -m pylint -r n -d bad-whitespace,missing-docstring,too-many-arguments,locally-disabled,line-too-long,too-many-public-methods,too-many-lines,too-many-instance-attributes,too-many-locals,too-many-branches,too-many-statements instaloader
+ - python3 -m pylint -r n -d bad-whitespace,missing-docstring,too-many-arguments,locally-disabled,line-too-long,too-many-public-methods,too-many-lines,too-many-instance-attributes,too-many-locals,too-many-branches,too-many-statements,inconsistent-return-statements instaloader
+ - make -C docs html
 deploy:
-  provider: pypi
+  - provider: pypi
-  user: aandergr
+    user: aandergr
-  on:
+    on:
-    tags: true
+      tags: true
-    python: 3.6
+      python: 3.6
-  password:
+    password:
-    secure: KBsATtXNnEzqr0X2ALdyx2zaYj2EUfK8YjP4jEOilBELpJ4evHYXVgRkn9CKXGsD7LKbWmR3gz2rr8NZ6U42pHw0fpQHizz91MpJSKbNY7RZZh4UVWMDh81izeglchWAF+m3Wdpxpo/GBDbrZIbRQFhPgB+kjSzJo3uiCS+yVXtGG+6csJHzd0WkJjsVHz+XSdxyOiLy/qFF3nmY6ZrVrgw6WbX2YLbx9je6DxK3YRrnBqgMgH7Ui2xWWbgJCk3KKpQTMiMKnTa9mdeMJAd26YMCz1gG/X7ck6VNly/6bs5+Zq7/bU0dSolhPBhNthyccYdS0IeGPdPF3YqatblJ4fLGTfHn8oJs3/T11yIW9pvOT3UftEynPOUX+en2Qnb/3WfgwUfVts8i8DAYgEFLGEzbF5XMGy4gwAD/bZ0JW0pmgAG2PZsdOokAt+ydlNj/uxq1GFW2doZbul6k4t03p1mik6itYscvuhKoEm8Yw6wr1P9aDvMR6FFpSu4gDt2XrKmRmWkSXxpNeCfZujTjyAnISxLVQGSY7BG5K0Z2HbDtqqNz9nj4WgNGzZmngiRofCevWR+vPIDUDW7NCX03csfcFS9RRllBO/BrL7NVUV+Qp9dfTQYp+8SqYLWgHtDoXdgyMREjJaAmbx2u/TYTY8bADZ5F3vGUpv2j5hP3NTU=
+      secure: KBsATtXNnEzqr0X2ALdyx2zaYj2EUfK8YjP4jEOilBELpJ4evHYXVgRkn9CKXGsD7LKbWmR3gz2rr8NZ6U42pHw0fpQHizz91MpJSKbNY7RZZh4UVWMDh81izeglchWAF+m3Wdpxpo/GBDbrZIbRQFhPgB+kjSzJo3uiCS+yVXtGG+6csJHzd0WkJjsVHz+XSdxyOiLy/qFF3nmY6ZrVrgw6WbX2YLbx9je6DxK3YRrnBqgMgH7Ui2xWWbgJCk3KKpQTMiMKnTa9mdeMJAd26YMCz1gG/X7ck6VNly/6bs5+Zq7/bU0dSolhPBhNthyccYdS0IeGPdPF3YqatblJ4fLGTfHn8oJs3/T11yIW9pvOT3UftEynPOUX+en2Qnb/3WfgwUfVts8i8DAYgEFLGEzbF5XMGy4gwAD/bZ0JW0pmgAG2PZsdOokAt+ydlNj/uxq1GFW2doZbul6k4t03p1mik6itYscvuhKoEm8Yw6wr1P9aDvMR6FFpSu4gDt2XrKmRmWkSXxpNeCfZujTjyAnISxLVQGSY7BG5K0Z2HbDtqqNz9nj4WgNGzZmngiRofCevWR+vPIDUDW7NCX03csfcFS9RRllBO/BrL7NVUV+Qp9dfTQYp+8SqYLWgHtDoXdgyMREjJaAmbx2u/TYTY8bADZ5F3vGUpv2j5hP3NTU=
+  - provider: pages
+    skip-cleanup: true
+    github-token: $GITHUB_TOKEN
+    local-dir: docs/_build/html
+    repo: instaloader/instaloader.github.io
+    target-branch: master
+    on:
+      branch: master
+      python: 3.6

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Alexander Graf and André Koch-Kramer.
+Copyright (c) 2016-2018 Alexander Graf and André Koch-Kramer.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -1,5 +1,4 @@
-Instaloader
+.. image:: https://raw.githubusercontent.com/instaloader/instaloader/master/docs/logo_heading.png
-===========
 
 ::
 
@@ -9,8 +8,8 @@ Instaloader
 
 **Instaloader**
 
-- downloads **public and private profiles, hashtags, user stories and
+- downloads **public and private profiles, hashtags, user stories,
-  feeds**,
+  feeds and saved media**,
 
 - downloads **comments, geotags and captions** of each post,
 
@@ -20,7 +19,13 @@ Instaloader
 - allows **fine-grained customization** of filters and where to store
   downloaded media.
 
-`Instaloader Documentation <https://instaloader.readthedocs.io/>`__
+::
+
+    instaloader [--comments] [--geotags] [--stories]
+                [--login YOUR-USERNAME] [--fast-update]
+                profile | "#hashtag" | :stories | :feed | :saved
+
+`Instaloader Documentation <https://instaloader.github.io/>`__
 
 
 How to Automatically Download Pictures from Instagram
@@ -59,7 +64,7 @@ temporary directory, which will be reused later the next time ``--login``
 is given.  So you can download private profiles **non-interactively** when you
 already have a valid session cookie file.
 
-`Instaloader Documentation <https://instaloader.readthedocs.io/basic-usage.html>`__
+`Instaloader Documentation <https://instaloader.github.io/basic-usage.html>`__
 
 
 Disclaimer

docs/Makefile

@@ -50,7 +50,7 @@ clean:
 
 .PHONY: html
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	LC_ALL=C $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -223,3 +223,9 @@ dummy:
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
+
+favicon.ico: logo.svg
+	convert -density 384 -background transparent -define icon:auto-resize -colors 256 logo.svg favicon.ico
+
+logo.png: logo.svg
+	inkscape -z -e logo.png -w 100 -h 100 logo.svg

docs/README.md

@@ -0,0 +1,15 @@
+# Instaloader Documentation
+
+This directory contains sources for the Instaloader documentation.
+
+The documentation is hosted at:
+https://instaloader.github.io/
+
+## Build
+
+The documentation is created with [Sphinx](http://www.sphinx-doc.org/). To build it, use
+
+```
+pip3 install -r requirements.txt
+make html
+```

docs/_static/style.css

@@ -0,0 +1,12 @@
+code {
+    color: #222;
+    background-color: #f5f5f5;
+}
+
+dd {
+    padding-left: 8px;
+}
+
+dl.option dd {
+    padding-left: 12px;
+}

docs/_templates/caption.html

@@ -1 +0,0 @@
-<h2>Instaloader</h2>

docs/_templates/globaltoc.html

@@ -0,0 +1,14 @@
+<li class="dropdown globaltoc-container">
+  <a role="button"
+     id="dLabelGlobalToc"
+     data-toggle="dropdown"
+     data-target="#"
+     href="{{ pathto(master_doc) }}">{{ theme_navbar_site_name }} <b class="caret"></b></a>
+  <ul class="dropdown-menu globaltoc"
+      role="menu"
+      aria-labelledby="dLabelGlobalToc">
+    {{ toctree(maxdepth=theme_globaltoc_depth|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }}
+    <li role="separator" class="divider"></li>
+    <li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
+  </ul>
+</li>

docs/_templates/layout.html

@@ -1,4 +1,18 @@
 {% extends "!layout.html" %}
+{% block htmltitle %}
+  {% if pagename == "index" %}
+  <title>{{ title|striptags|e }}</title>
+  {% else %}
+  <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+  {% endif %}
+{% endblock %}
 {% block extrahead %}
-<script async defer src="https://buttons.github.io/buttons.js"></script>
+{{ super() }}
+  <meta name="google-site-verification" content="FNUsDdkOJM9obm9QEdrNBVd9AtAzHzA-aaSMCUrS6C8" />
+  {% if pagename == "index" %}
+  <link rel="canonical" href="https://instaloader.github.io/" />
+  {% else %}
+  <link rel="canonical" href="https://instaloader.github.io/{{ pagename }}.html" />
+  {% endif %}
+  <script async defer src="https://buttons.github.io/buttons.js"></script>
 {% endblock %}

docs/_templates/links.html

@@ -1,18 +0,0 @@
-{% if next %}
-<h3>Next</h3>
-<ul>
-  <li class="toctree-l1"><a class="reference internal" href="{{ next.link|e }}">{{ next.title }}</a></li>
-</ul>
-{% endif %}
-<h3>Links</h3>
-<ul>
-  <li><a href="https://github.com/Thammus/instaloader/issues">Issue Tracker</a></li>
-  <li><a href="https://github.com/Thammus/instaloader/releases">Version History</a></li>
-  <li><a href="https://pypi.python.org/pypi/instaloader">Instaloader on PyPI</a></li>
-  <li><a href="https://github.com/Thammus/instaloader">Instaloader on GitHub</a></li>
-</ul>
-<ul>
-  <li>
-    <a class="github-button" href="https://github.com/Thammus/Instaloader" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star Thammus/Instaloader on GitHub">Star</a>
-  </li>
-</ul>

docs/_templates/navbar.html

@@ -0,0 +1,58 @@
+  <div id="navbar" class="{{ theme_navbar_class }} navbar-default {% if theme_navbar_fixed_top|tobool -%} navbar-fixed-top{%- endif -%}">
+    <div class="container">
+      <div class="navbar-header">
+        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
+        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+        </button>
+        <a class="navbar-brand" href="{{ pathto(master_doc) }}">
+          {%- block sidebarlogo %}
+            {%- if logo %}<span><img src="{{ pathto('_static/' + logo, 1) }}"></span>{%- endif %}
+          {%- endblock %}
+          {% if theme_navbar_title -%}{{ theme_navbar_title|e }}{%- else -%}{{ project|e }}{%- endif -%}
+        </a>
+        <span class="navbar-text navbar-version pull-left">
+          <a href="https://github.com/instaloader/instaloader/releases/tag/v{{current_release}}" title="Released on {{current_release_date}}">v<b>{{current_release}}</b></a>
+        </span>
+      </div>
+
+        <div class="collapse navbar-collapse nav-collapse">
+          <ul class="nav navbar-nav">
+            {% if theme_navbar_links %}
+              {%- for link in theme_navbar_links %}
+                <li><a href="{{ pathto(*link[1:]) }}">{{ link[0] }}</a></li>
+              {%- endfor %}
+            {% endif %}
+            {% block navbartoc %}
+              {% include "globaltoc.html" %}
+              {% if theme_navbar_pagenav and pagename not in ("index", "genindex", "installation") %}
+                {% include "navbartoc.html" %}
+              {% endif %}
+            {% endblock %}
+            {% if theme_navbar_sidebarrel %}
+              {% block sidebarrel %}
+                {% include "relations.html" %}
+              {% endblock %}
+            {% endif %}
+            </ul>
+            <ul class="nav navbar-nav navbar-right">
+              <li class="dropdown">
+                <a role="button" id="dLabelUsefulLinks" data-toggle="dropdown" data-target="#" href="#">
+                  Useful Links
+                  <b class="caret"></b>
+                </a>
+                <ul class="dropdown-menu" role="menu" aria-labelledby="dLabelUsefulLinks">
+                  <li><a href="https://github.com/instaloader/instaloader/issues">Issue Tracker</a></li>
+                  <li><a href="https://github.com/instaloader/instaloader/releases">Version History</a></li>
+                  <li><a href="https://pypi.org/project/instaloader/">Instaloader on PyPI</a></li>
+                  <li><a href="https://github.com/instaloader/instaloader">Instaloader on GitHub</a></li>
+                  <li role="separator" class="divider"></li>
+                  <li style="padding-left: 20px;"><a class="github-button" href="https://github.com/instaloader/instaloader" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star Instaloader on GitHub">Star</a></li>
+                </ul>
+              </li>
+            </ul>
+        </div>
+    </div>
+  </div>

docs/_templates/page.html

@@ -0,0 +1,10 @@
+{% extends "!page.html" %}
+{% block body %}
+{{ super() }}
+{% if next and prev %}
+<h2>Next Section</h2>
+<p>
+  <a class="reference internal" href="{{ next.link|e }}">{{ next.title }}</a>
+</p>
+{% endif %}
+{% endblock %}

docs/as-module.rst

@@ -1,3 +1,8 @@
+.. meta::
+   :description:
+      Documentation of Instaloader module, a powerful and easy-to-use
+      Python library to download Instagram media and metadata.
+
 Python Module :mod:`instaloader`
 --------------------------------
 
@@ -5,68 +10,66 @@ 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`, :func:`Instaloader.get_profile_posts` and
+:func:`Instaloader.get_saved_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/instaloader/instaloader>`__.
 
 ``Instaloader`` (Main Class)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/basic-usage.rst

@@ -1,3 +1,10 @@
+.. meta::
+   :description:
+      How to download pictures from Instagram. Description of basic
+      usage of Instaloader, free tool to download photos from public
+      and private profiles, hashtags, stories, feeds, saved media, and
+      their metadata, comments and captions.
+
 Download Pictures from Instagram
 ---------------------------------
 
@@ -63,6 +70,9 @@ Instaloader supports the following targets:
 ``:feed``
    Your **feed** (requires :option:`--login`),
 
+``:saved``
+   Posts which are marked as **saved** (requires :option:`--login`),
+
 ``@profile``
    All profiles that are followed by ``profile``, i.e. the *followees* of
    ``profile`` (requires :option:`--login`).
@@ -95,8 +105,9 @@ pattern, the token ``{target}`` is replaced by the target name, and
 :option:`--filename-pattern` configures the path of the post's files relative
 to the target directory. The default is ``--filename-pattern={date}``.
 The tokens ``{target}`` and ``{profile}`` are replaced like in the
-dirname pattern. Further, the tokens ``{date}`` and ``{shortcode}`` are
+dirname pattern. Further, the tokens ``{date}``, ``{date_utc}`` and ``{shortcode}`` are
-defined.
+defined. Additionally, in case of not downloading stories, the attributes of
+:class:`.Post` can be used, e.g. ``{post.owner_id}`` or ``{post.mediaid}``.
 
 For example, encode the poster's profile name in the filenames with:
 

docs/cli-options.rst

@@ -1,33 +1,44 @@
 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), ``:stories`` (stories of your followees) or ``:saved`` (collection of
+posts marked as saved).
+
+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``, ``:stories`` or
-creates a folder and downloads all posts along with the pictures's
+``:saved``). For each of these, Instaloader creates a folder and stores all
-captions and the current **profile picture**. If an already-downloaded profile
+posts along with the pictures's captions and the current **profile picture**
-has been renamed, Instaloader automatically **finds it by its unique ID** and
+there. If an already-downloaded profile has been renamed, Instaloader
-renames the folder likewise.
+automatically **finds 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
 
    Only download profile picture.
 
+.. option:: --no-profile-pic
+
+   Do not download profile picture.
+
 .. option:: --no-videos
 
    Do not download videos.
 
+.. option:: --no-video-thumbnails
+
+   Do not download thumbnails of videos.
+
 .. option:: --geotags
 
    **Download geotags** when available. Geotags are stored as a text file with
@@ -66,7 +77,8 @@ Instead of a *profile* or a *#hashtag*, the special targets
 .. option:: --stories-only
 
    Rather than downloading regular posts of each specified profile, only
-   download stories.  Requires :option:`--login`.
+   download stories.  Requires :option:`--login`. Does not imply
+   :option:`--no-profile-pic`.
 
 .. option:: --only-if filter
 
@@ -92,7 +104,7 @@ matching the specified targets.
 .. option:: --count COUNT
 
    Do not attempt to download more than COUNT posts.  Applies only to
-   ``#hashtag``, ``:feed-all`` and ``:feed-liked``.
+   ``#hashtag`` and ``:feed``.
 
 
 Login (Download Private Profiles)
@@ -133,9 +145,12 @@ How to Download
    Prefix of filenames. Posts are stored in the directory whose pattern is given
    with ``--dirname-pattern``.  ``{profile}`` is replaced by the profile name,
    ``{target}`` is replaced by the target you specified, i.e.  either ``:feed``,
-   ``#hashtag`` or the profile name.  Also, the fields ``{date}`` and
+   ``#hashtag`` or the profile name.  Also, the fields ``{date}``, ``{date_utc}`` and
-   ``{shortcode}`` can be specified.  Defaults to ``{date:%Y-%m-%d_%H-%M-%S}``.
+   ``{shortcode}`` can be specified.  In case of not downloading stories, the
-   See :ref:`filename-specification`.
+   attributes of the :class:`.Post` class can be used in addition, e.g.
+   ``{post.owner_id}`` or ``{post.mediaid}``.
+   Defaults to
+   ``{date:%Y-%m-%d_%H-%M-%S}``.  See :ref:`filename-specification`.
 
 .. option:: --user-agent USER_AGENT
 
@@ -145,7 +160,7 @@ How to Download
 .. option:: --max-connection-attempts N
 
    Maximum number of connection attempts until a request is aborted. Defaults
-   to ``3``. If a connection fails, it can by manually skipped by hitting
+   to ``3``. If a connection fails, it can be manually skipped by hitting
    :kbd:`Control-c`. Set this to ``0`` to retry infinitely.
 
 Miscellaneous Options

docs/conf.py

@@ -18,7 +18,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import subprocess
 import sys
+
+import sphinx_bootstrap_theme
+
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
@@ -132,16 +136,20 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'bootstrap'
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
-    'show_powered_by': False,
+    'navbar_site_name': 'Site Contents',
-    'sidebar_width': '290px',
+    'navbar_pagenav_name': 'Page Contents',
-    'page_width': '935px' }
+    'navbar_pagenav': True,
+    'navbar_sidebarrel': True,
+    'nosidebar': True,
+     }
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -158,13 +166,13 @@ html_theme_options = {
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = "logo.png"
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #
-# html_favicon = None
+html_favicon = "favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -190,7 +198,8 @@ html_static_path = ['_static']
 
 # Custom sidebar templates, maps document names to template names.
 #
-html_sidebars = {'**': ["caption.html", "globaltoc.html", "relations.html", "links.html"] }
+#html_sidebars = {'**': ["relations.html", "links.html"] }
+html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -203,7 +212,7 @@ html_domain_indices = False
 
 # If false, no index is generated.
 #
-html_use_index = False
+html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 #
@@ -352,3 +361,12 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+
+
+current_release = subprocess.check_output(["git", "describe", "--abbrev=0"]).decode("ascii")[1:-1]
+current_release_date = subprocess.check_output(["git", "log", "-1", "--tags", "--format=%ad", "--date=format:%e %b %Y"]).decode("ascii")[:-1]
+
+html_context = {'current_release': current_release, 'current_release_date': current_release_date}
+
+def setup(app):
+    app.add_stylesheet("style.css")

docs/contributing.rst

@@ -0,0 +1,83 @@
+Contributing to Instaloader
+===========================
+
+As an open source project, Instaloader heavily depends on the contributions from
+its community.  In this document, we advise on how you may help Instaloader to
+become an even greater tool.
+
+Instaloader's development is organized on 
+`GitHub <https://github.com/instaloader/instaloader>`__, where Issues and Pull
+Requests are discussed.
+
+Reporting Bugs
+--------------
+
+If you encounter a bug, do not hesitate to report it in our
+`Issue Tracker <https://github.com/instaloader/instaloader/issues>`__. Since
+Instaloader is actively developed, the majority of bugs is fixed within only
+**4 days** after being reported. When reporting a problem, please keep the
+following in mind:
+
+- Ensure you **use the latest version** of Instaloader. The currently-installed
+  version can be found out with ``instaloader --version``.
+
+- Briefly **check whether the bug has already been reported**. If you find an
+  issue reporting the same bug you encountered, comment there rather than
+  opening a new issue. However, if unsure, it is advised to create a new issue.
+
+- State **how the bug can be reproduced**, i.e. how Instaloader was invoked
+  when the problem occured (of course, you may anonymize profile names etc.).
+
+- Include all **error messages and tracebacks** in the report.
+
+- If not obvious, describe **which behavior you expected**
+  instead of what actually happened.
+
+- If you think an issue has been closed accidentally or inappropriately, feel
+  free to reopen it.
+
+Writing Code or Improving the Documentation
+-------------------------------------------
+
+Changes of the Instaloader source can be proposed as a
+`Pull Request <https://github.com/instaloader/instaloader/pulls>`__. There are only
+few things to consider:
+
+- Sometimes, the most current code is not in the ``master`` branch. Check that
+  you forked from the most recent branch.
+
+- We use `Pylint <https://www.pylint.org/>`__ for error and syntax checking of
+  ``instaloader.py``. The file ``.travis.yml`` in the project's root directory
+  shows how it is invoked. Note that sometimes it might be better to disable a
+  warning rather than adapting the code to Pylint's desires.
+
+- The documentation source is located in the ``docs`` folder. The file
+  ``cli-options.rst`` is merely an RST-formatted copy of ``ìnstaloader --help``
+  output, of which the source is near the bottom of ``instaloader.py``.
+
+- Feel free to contact us, even if you "only" have Proof-of-Concepts or
+  not-fully integrated changes. They already might be an advance for the
+  project.
+
+Suggesting Features
+-------------------
+
+If you have an idea of how Instaloader should be enhanced, but do not want to
+implement the feature yourself, feel free to open a ticket in our 
+`Issue Tracker <https://github.com/instaloader/instaloader/issues>`__.
+Please consider the following:
+
+- Instaloader already has plenty of features. **Check the documentation**
+  beforehand to ensure your desired suggestion is not already implemented.
+
+- Briefly **ensure that your idea has not already been suggested**. If you find
+  an issue suggesting the same or a similar feature, share your thoughts in a
+  comment there, instead of opening a new issue.
+
+- If possible, provide us a **use case of the feature**: How could the user
+  invoke the new function? Which problem would it solve? If new information is
+  obtained, how would it be further processed?
+
+- **Be patient**. Naturally, bugs and pull requests have a higher priority than
+  feature suggestions. Keep in mind that this is a free software project, and
+  unfortunately we only have limited time to work on it.

docs/index.rst

@@ -1,6 +1,17 @@
+.. meta::
+   :description:
+      Free command line tool to download photos from Instagram.
+      Scrapes public and private profiles, hashtags, stories, feeds,
+      saved media, and their metadata, comments and captions.
+      Written in Python.
+
+.. title:: Instaloader — Download Instagram Photos and Metadata
+
 Instaloader
 ===========
 
+.. highlight:: none
+
 **Instaloader** is a tool to download pictures (or videos) along with
 their captions and other metadata from Instagram.
 
@@ -12,8 +23,8 @@ With `Python <https://www.python.org/>`__ installed, do::
 
 **Instaloader**
 
-- downloads **public and private profiles, hashtags, user stories and
+- downloads **public and private profiles, hashtags, user stories,
-  feeds**,
+  feeds and saved media**,
 
 - downloads **comments, geotags and captions** of each post,
 
@@ -23,12 +34,19 @@ With `Python <https://www.python.org/>`__ installed, do::
 - allows **fine-grained customization** of filters and where to store
   downloaded media,
 
-- is free `open source <https://github.com/Thammus/instaloader>`__
+- is free `open source <https://github.com/instaloader/instaloader>`__
   software written in Python.
 
+::
 
-Table of Contents
+    instaloader [--comments] [--geotags] [--stories]
------------------
+                [--login YOUR-USERNAME] [--fast-update]
+                profile | "#hashtag" |
+                :stories | :feed | :saved
+
+
+Instaloader Documentation
+-------------------------
 
 .. toctree::
    :maxdepth: 2
@@ -37,14 +55,15 @@ Table of Contents
    basic-usage
    cli-options
    as-module
+   contributing
 
 Useful Links
 ------------
 
-- `Git Repository (on GitHub) <https://github.com/Thammus/instaloader>`__
+- `Git Repository (on GitHub) <https://github.com/instaloader/instaloader>`__
-- `PyPI Project Page <https://pypi.python.org/pypi/instaloader>`__
+- `PyPI Project Page <https://pypi.org/project/instaloader/>`__
-- `Issue Tracker / Bug Tracker <https://github.com/Thammus/instaloader/issues>`__
+- `Issue Tracker / Bug Tracker <https://github.com/instaloader/instaloader/issues>`__
-- `Version History <https://github.com/Thammus/instaloader/releases>`__
+- `Version History <https://github.com/instaloader/instaloader/releases>`__
 
 .. include:: ../README.rst
    :start-after: disclaimer-start

docs/installation.rst

@@ -12,11 +12,11 @@ installed, you may install Instaloader using
     pip3 install instaloader
 
 Alternatively, to get the most current version of Instaloader from our
-`Git repository <https://github.com/Thammus/instaloader>`__:
+`Git repository <https://github.com/instaloader/instaloader>`__:
 
 ::
 
-    pip3 install git+https://github.com/Thammus/instaloader
+    pip3 install git+https://github.com/instaloader/instaloader
 
 (pass ``--upgrade`` to upgrade if Instaloader is already installed)
 
@@ -24,7 +24,18 @@ Instaloader requires
 `requests <http://python-requests.org/>`__, which
 will be installed automatically, if it is not already installed.
 
-If you do not want to use pip, even though it is highly recommended,
+**Alternative methods for installing Instaloader:**
-and prefer installing Instaloader manually,
+
-`Download the Source <https://github.com/Thammus/instaloader/releases>`__,
+- If you do not want to use pip, even though it is highly recommended,
-extract the Zip or Tarball and execute ``instaloader.py`` from there.
+  and prefer to **install Instaloader manually**,
+  `Download the Source <https://github.com/instaloader/instaloader/releases/latest>`__,
+  extract the Zip or Tarball and execute ``instaloader.py`` from there.
+
+- On **Arch Linux**, you may install Instaloader using the
+  `Instaloader AUR package <https://aur.archlinux.org/packages/instaloader/>`__.
+
+- On **Gentoo Linux**, you may install Instaloader using the
+  `Instaloader Ebuild <https://bugs.gentoo.org/642100>`__.
+
+- On **Windows 10**, you may download the standalone executable from the
+  `current release page <https://github.com/instaloader/instaloader/releases/latest>`__.

docs/requirements.txt

@@ -1 +1,4 @@
+requests
+sphinx
 sphinx-autodoc-typehints
+sphinx-bootstrap-theme

setup.py

@@ -38,7 +38,7 @@ setup(
     name='instaloader',
     version=get_version(),
     py_modules=['instaloader'],
-    url='https://instaloader.readthedocs.io/',
+    url='https://instaloader.github.io/',
     license='MIT',
     author='Alexander Graf, André Koch-Kramer',
     author_email='mail@agraf.me, koch-kramer@web.de',