Release of version 3.3.8

Fixes #96.

.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
-  user: aandergr
-  on:
-    tags: true
-    python: 3.6
-  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=
+  - provider: pypi
+    user: aandergr
+    on:
+      tags: true
+      python: 3.6
+    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=
+  - 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,39 +1,36 @@
-Instaloader
-===========
-
-Installation
-------------
-
-.. installation-start
-
-Instaloader requires `Python <https://www.python.org/>`__, at least
-version 3.5.  If you have `pip <https://pypi.python.org/pypi/pip>`__
-installed, you may install Instaloader using
+.. image:: https://raw.githubusercontent.com/instaloader/instaloader/master/docs/logo_heading.png
 
 ::
 
-    pip3 install instaloader
+    $ pip3 install instaloader
 
-Alternatively, to get the most current version of Instaloader from our
-`Git repository <https://github.com/Thammus/instaloader>`__:
+    $ instaloader profile [profile ...]
+
+**Instaloader**
+
+- downloads **public and private profiles, hashtags, user stories,
+  feeds and saved media**,
+
+- downloads **comments, geotags and captions** of each post,
+
+- automatically **detects profile name changes** and renames the target
+  directory accordingly,
+
+- allows **fine-grained customization** of filters and where to store
+  downloaded media.
 
 ::
 
-    pip3 install git+https://github.com/Thammus/instaloader
+    instaloader [--comments] [--geotags] [--stories]
+                [--login YOUR-USERNAME] [--fast-update]
+                profile | "#hashtag" | :stories | :feed | :saved
 
-(pass ``--upgrade`` to upgrade if Instaloader is already installed)
+`Instaloader Documentation <https://instaloader.github.io/>`__
 
-Instaloader requires
-`requests <http://python-requests.org/>`__, which
-will be installed automatically, if it is not already installed.
-
-.. installation-end
 
 How to Automatically Download Pictures from Instagram
 -----------------------------------------------------
 
-.. basic-usage-start
-
 To **download all pictures and videos of a profile**, as well as the
 **profile picture**, do
 
@@ -52,8 +49,8 @@ To later **update your local copy** of that profiles, you may run
 
 If ``--fast-update`` is given, Instaloader stops when arriving at the
 first already-downloaded picture. When updating profiles, Instaloader
-automatically **detects profile name changes** and renames the target
-directory accordingly.
+automatically **detects profile name changes** and renames the target directory
+accordingly.
 
 Instaloader can also be used to **download private profiles**. To do so,
 invoke it with
@@ -62,291 +59,13 @@ invoke it with
 
     instaloader --login=your_username profile [profile ...]
 
-When logging in, Instaloader **stores the session cookies** in a file in
-your 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.
+When logging in, Instaloader **stores the session cookies** in a file in your
+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.
 
-What to Download
-^^^^^^^^^^^^^^^^
+`Instaloader Documentation <https://instaloader.github.io/basic-usage.html>`__
 
-Instaloader does not only download media by-profile. More generally, you
-may specify the following targets:
-
-- ``profile``: Public profile, or private profile with ``--login``,
-
-- ``"#hashtag"``: Posts with a certain **hashtag** (the quotes are
-  usually neccessary),
-
-- ``:stories``: The currently-visible **stories** of your followees
-  (requires ``--login``),
-
-- ``:feed``: Your **feed** (requires ``--login``),
-
-- ``@profile``: All profiles that are followed by ``profile``, i.e. the
-  *followees* of ``profile`` (requires ``--login``).
-
-Instaloader goes through all media matching the specified targets and
-downloads the pictures and videos and their captions. You can specify
-``--comments`` to also **download comments** of each post and
-``--geotags`` to **download geotags** of each post and save them as
-Google Maps link.  For each profile you download, ``--stories``
-instructs Instaloader to **download the user's stories**.
-
-Filename Specification
-^^^^^^^^^^^^^^^^^^^^^^
-
-For each target, Instaloader creates a directory named after the target,
-i.e. ``profile``, ``#hashtag``, ``:feed``, etc. and therein saves the
-posts in files named after the post's timestamp.
-
-``--dirname-pattern`` allows to configure the directory name of each
-target. The default is ``--dirname-pattern={target}``. In the dirname
-pattern, the token ``{target}`` is replaced by the target name, and
-``{profile}`` is replaced by the owner of the post which is downloaded.
-
-``--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
-defined.
-
-For example, encode the poster's profile name in the filenames with:
-
-::
-
-    instaloader --filename-pattern={date}_{profile} "#hashtag"
-
-The pattern string is formatted with Python's string formatter. This
-gives additional flexibilty for pattern specification. For example,
-`strftime-style formatting options <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`__
-are supported for the post's
-timestamp. The default for ``{date}`` is ``{date:%Y-%m-%d_%H-%M-%S}``.
-
-Filter Posts
-^^^^^^^^^^^^
-
-The ``--only-if`` option allows to specify criterias that posts have to
-meet to be downloaded. If not given, all posts are downloaded. It must
-be a boolean Python expression where the variables ``likes``,
-``comments``, ``viewer_has_liked``, ``is_video``, and many
-more are defined.
-
-A few examples:
-
-To **download the pictures from your feed that you have liked**:
-
-::
-
-    instaloader --login=your_username --only-if=viewer_has_liked :feed
-
-Or you might only want to download **posts that either you liked or were
-liked by many others**:
-
-::
-
-    instaloader --login=your_username --only-if="likes>100 or viewer_has_liked" profile
-
-Or you may **skip videos**:
-
-::
-
-    instaloader --only-if="not is_video" target
-
-Or you may filter by hashtags that occur in the Post's caption. For
-example, to download posts of kittens that are cute: ::
-
-    instaloader --only-if="'cute' in caption_hashtags" "#kitten"
-
-.. basic-usage-end
-
-(For a more complete description of the ``-only-if`` option, refer to
-the `Instaloader Documentation <https://instaloader.readthedocs.io/basic-usage.html#filter-posts>`__)
-
-
-Advanced Options
-----------------
-
-.. cli-options-start
-
-The following flags can be given to Instaloader to specify how profiles should
-be downloaded.
-
-To get a list of all flags, their abbreviations and their descriptions, you may
-run ``instaloader --help``.
-
-What to Download
-^^^^^^^^^^^^^^^^
-
-Specify a list of profiles or #hashtags. For each of these, Instaloader
-creates a folder and downloads all posts along with the pictures's
-captions and the current **profile picture**. If an already-downloaded profile
-has been renamed, Instaloader 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.
-
---profile-pic-only         Only download profile picture.
---no-videos                Do not download videos.
---geotags                  **Download geotags** when available. Geotags are stored as
-                           a text file with the location's name and a Google Maps
-                           link. This requires an additional request to the
-                           Instagram server for each picture, which is why it is
-                           disabled by default.
---no-geotags               Do not store geotags, even if they can be obtained
-                           without any additional request.
---comments                 Download and update comments for each post. This
-                           requires an additional request to the Instagram server
-                           for each post, which is why it is disabled by default.
---no-captions              Do not store media captions, although no additional
-                           request is needed to obtain them.
---stories                  Also **download stories** of each profile that is
-                           downloaded. Requires ``--login``.
---stories-only             Rather than downloading regular posts of each
-                           specified profile, only download stories.
-                           Requires ``--login``.
---only-if filter           Expression that, if given, must evaluate to True for each post to
-                           be downloaded. Must be a syntactically valid python
-                           expression. Variables are evaluated to
-                           ``instaloader.Post`` attributes.
-                           Example: ``--only-if=viewer_has_liked``.
-
-
-When to Stop Downloading
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If none of these options are given, Instaloader goes through all pictures
-matching the specified targets.
-
---fast-update              For each target, stop when encountering the first
-                           already-downloaded picture. This flag is recommended
-                           when you use Instaloader to update your personal
-                           Instagram archive.
---count COUNT              Do not attempt to download more than COUNT posts.
-                           Applies only to ``#hashtag``, ``:feed-all`` and ``:feed-liked``.
-
-
-Login (Download Private Profiles)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Instaloader can **login to Instagram**. This allows downloading private
-profiles. To login, pass the ``--login`` option. Your session cookie (not your
-password!) will be saved to a local file to be reused next time you want
-Instaloader to login.
-
---login YOUR-USERNAME      Login name (profile name) for your Instagram account.
---sessionfile SESSIONFILE  Path for loading and storing session key file.
-                           Defaults to a path
-                           within your temporary directory, encoding your local
-                           username and your Instagram profile name.
---password YOUR-PASSWORD   Password for your Instagram account. Without this
-                           option, you'll be prompted for your password
-                           interactively if there is not yet a valid session
-                           file.
-
-How to Download
-^^^^^^^^^^^^^^^
-
---dirname-pattern DIRNAME_PATTERN
-                           Name of directory where to store posts. ``{profile}``
-                           is replaced by the profile name, ``{target}`` is replaced
-                           by the target you specified, i.e. either ``:feed``,
-                           ``#hashtag`` or the profile name. Defaults to ``{target}``.
---filename-pattern FILENAME_PATTERN
-                           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 ``{shortcode}`` can be specified.
-                           Defaults to ``{date:%Y-%m-%d_%H-%M-%S}``.
---user-agent USER_AGENT    User Agent to use for HTTP requests. Per default,
-                           Instaloader pretends being Chrome/51.
-
-Miscellaneous Options
-^^^^^^^^^^^^^^^^^^^^^
-
---quiet                    Disable user interaction, i.e. do not print messages
-                           (except errors) and fail if login credentials are
-                           needed but not given. This makes Instaloader
-                           **suitable as a cron job**.
-
-.. cli-options-end
-
-Usage as Python module
-----------------------
-
-.. as-module-intro-start
-
-You may also use parts of Instaloader as library to do other interesting
-things.
-
-For example, to get a list of all followees and a list of all followers of a profile, do
-
-.. code:: python
-
-    import instaloader
-
-    # Get instance
-    loader = instaloader.Instaloader()
-
-    # Login
-    loader.interactive_login(USERNAME)
-
-    # Print followees
-    print(PROFILE + " follows these profiles:")
-    for f in loader.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):
-        print("\t%s\t%s" % (f['username'], f['full_name']))
-
-Then, you may download all pictures of all followees with
-
-.. code:: python
-
-    for f in loader.get_followees(PROFILE):
-        loader.download_profile(f['username'])
-
-You could also download your last 20 liked pics with
-
-.. 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, 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)
-
-.. as-module-intro-end
-
-Refer to the
-`Instaloader Documentation <https://instaloader.readthedocs.io/as-module.html>`__ for
-more information.
 
 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,26 +1,117 @@
-Usage as Python Module
-----------------------
+.. meta::
+   :description:
+      Documentation of Instaloader module, a powerful and easy-to-use
+      Python library to download Instagram media and metadata.
 
-Introduction
-^^^^^^^^^^^^
+Python Module :mod:`instaloader`
+--------------------------------
 
-.. include:: ../README.rst
-   :start-after: as-module-intro-start
-   :end-before: as-module-intro-end
+.. module:: instaloader
 
+.. highlight:: python
+
+Instaloader exposes its internally used methods as a Python module, making it a
+**powerful and easy-to-use Python API for Instagram**, allowing to further
+customize obtaining media and metadata.
+
+Start with getting an instance of :class:`Instaloader`::
+
+    import instaloader
+
+    # Get instance
+    L = instaloader.Instaloader()
+
+    # Optionally, login or load session
+    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 L.get_followees(PROFILE):
+        print("\t%s\t%s" % (f['username'], f['full_name']))
+
+    # Print followers
+    print("Followers of " + 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::
+
+    for f in L.get_followees(PROFILE):
+        L.download_profile(f['username'])
+
+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::
+
+    L.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)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. autoclass:: instaloader.Instaloader
-   :members:
-   :undoc-members:
-
-.. _post-class:
+.. autoclass:: Instaloader
+   :no-show-inheritance:
 
 ``Post`` Class
 ^^^^^^^^^^^^^^
 
-.. autoclass:: instaloader.Post
-   :members:
-   :undoc-members:
+.. autoclass:: Post
+   :no-show-inheritance:
+
+Miscellaneous Functions
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: shortcode_to_mediaid
+
+.. autofunction:: mediaid_to_shortcode
+
+.. autoclass:: Tristate
+
+Exceptions
+^^^^^^^^^^
+
+.. autoexception:: InstaloaderException
+   :no-show-inheritance:
+
+.. autoexception:: QueryReturnedNotFoundException
+
+.. autoexception:: ProfileNotExistsException
+
+.. autoexception:: ProfileHasNoPicsException
+
+.. autoexception:: PrivateProfileNotFollowedException
+
+.. autoexception:: LoginRequiredException
+
+.. autoexception:: InvalidArgumentException
+
+.. autoexception:: BadResponseException
+
+.. autoexception:: BadCredentialsException
+
+.. autoexception:: ConnectionException

docs/basic-usage.rst

@@ -1,15 +1,162 @@
+.. 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
 ---------------------------------
 
+.. highlight:: none
+
+.. NOTE that Section "Basic Usage" is duplicated in README.rst.
+
 Basic Usage
 ^^^^^^^^^^^
 
-.. include:: ../README.rst
-   :start-after: basic-usage-start
-   :end-before: basic-usage-end
+To **download all pictures and videos of a profile**, as well as the
+**profile picture**, do
 
-.. (continuation of --only-if explanation)
+::
+
+    instaloader profile [profile ...]
+
+where ``profile`` is the name of a profile you want to download. Instead
+of only one profile, you may also specify a list of profiles.
+
+To later **update your local copy** of that profiles, you may run
+
+::
+
+    instaloader --fast-update profile [profile ...]
+
+If :option:`--fast-update` is given, Instaloader stops when arriving at the
+first already-downloaded picture. When updating profiles, Instaloader
+automatically **detects profile name changes** and renames the target directory
+accordingly.
+
+Instaloader can also be used to **download private profiles**. To do so,
+invoke it with
+
+::
+
+    instaloader --login=your_username profile [profile ...]
+
+When logging in, Instaloader **stores the session cookies** in a file in your
+temporary directory, which will be reused later the next time :option:`--login`
+is given.  So you can download private profiles **non-interactively** when you
+already have a valid session cookie file.
+
+.. _what-to-download:
+
+What to Download
+^^^^^^^^^^^^^^^^
+
+Instaloader supports the following targets:
+
+``profile``
+   Public profile, or private profile with :option:`--login`. For each profile
+   you download, :option:`--stories` instructs Instaloader to also
+   **download the user's stories**.
+
+``"#hashtag"``
+   Posts with a certain **hashtag** (the quotes are usually neccessary),
+
+``:stories``
+   The currently-visible **stories** of your followees (requires
+   :option:`--login`),
+
+``: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`).
+
+Instaloader goes through all media matching the specified targets and
+downloads the pictures and videos and their captions. You can specify
+
+- :option:`--comments`, to also **download comments** of each post,
+
+- :option:`--geotags`, to **download geotags** of each post and save them as
+  Google Maps link,
+
+- :option:`--metadata-json`, to store further post metadata in a separate JSON
+  file.
+
+.. _filename-specification:
+
+Filename Specification
+^^^^^^^^^^^^^^^^^^^^^^
+
+For each target, Instaloader creates a directory named after the target,
+i.e. ``profile``, ``#hashtag``, ``:feed``, etc. and therein saves the
+posts in files named after the post's timestamp.
+
+:option:`--dirname-pattern` allows to configure the directory name of each
+target. The default is ``--dirname-pattern={target}``. In the dirname
+pattern, the token ``{target}`` is replaced by the target name, and
+``{profile}`` is replaced by the owner of the post which is downloaded.
+
+: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}``, ``{date_utc}`` and ``{shortcode}`` are
+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:
+
+::
+
+    instaloader --filename-pattern={date}_{profile} "#hashtag"
+
+The pattern string is formatted with Python's string formatter. This
+gives additional flexibilty for pattern specification. For example,
+`strftime-style formatting options <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`__
+are supported for the post's
+timestamp. The default for ``{date}`` is ``{date:%Y-%m-%d_%H-%M-%S}``.
+
+.. _filter-posts:
+
+Filter Posts
+^^^^^^^^^^^^
+
+The :option:`--only-if` option allows to specify criterias that posts have to
+meet to be downloaded. If not given, all posts are downloaded. It must be a
+boolean Python expression where the variables :attr:`.likes`, :attr:`.comments`,
+:attr:`.viewer_has_liked`, :attr:`.is_video`, and many more are defined.
+
+A few examples:
+
+To **download the pictures from your feed that you have liked**:
+
+::
+
+    instaloader --login=your_username --only-if=viewer_has_liked :feed
+
+Or you might only want to download **posts that either you liked or were
+liked by many others**:
+
+::
+
+    instaloader --login=your_username --only-if="likes>100 or viewer_has_liked" profile
+
+Or you may **skip videos**:
+
+::
+
+    instaloader --only-if="not is_video" target
+
+Or you may filter by hashtags that occur in the Post's caption. For
+example, to download posts of kittens that are cute: ::
+
+    instaloader --only-if="'cute' in caption_hashtags" "#kitten"
 
 The given string is evaluated as a
 `Python boolean expression <https://docs.python.org/3/reference/expressions.html#boolean-operations>`__,
-where all occuring variables are properties of the :ref:`post-class`.
+where all occuring variables are attributes of the :class:`.Post` class.

docs/cli-options.rst

@@ -1,6 +1,173 @@
 Command Line Options
 ====================
 
-.. include:: ../README.rst
-   :start-after: cli-options-start
-   :end-before: cli-options-end
+Instaloader is invoked with::
+
+   $ instaloader [options] target [target ...]
+
+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 targets (profiles, #hashtags, ``:feed``, ``:stories`` or
+``:saved``). For each of these, Instaloader creates a folder and stores all
+posts along with the pictures's captions and the current **profile picture**
+there. If an already-downloaded profile has been renamed, Instaloader
+automatically **finds it by its unique ID** and renames the folder likewise.
+
+.. 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
+   the location's name and a Google Maps link. This requires an additional
+   request to the Instagram server for each picture, which is why it is disabled
+   by default.
+
+.. option:: --no-geotags
+
+   Do not store geotags, even if they can be obtained without any additional
+   request.
+
+.. option:: --comments
+
+   Download and update comments for each post. This requires an additional
+   request to the Instagram server for each post, which is why it is disabled by
+   default.
+
+.. option:: --no-captions
+
+   Do not store media captions, although no additional request is needed to
+   obtain them.
+
+.. option:: --stories
+
+   Also **download stories** of each profile that is downloaded. Requires
+   :option:`--login`.
+
+.. option:: --metadata-json
+
+   Create a JSON file containing the metadata of each post. This does not
+   include comments (see :option:`--comments`) nor geotags (see
+   :option:`--geotags`). The JSON files contain the properties of
+   :class:`instaloader.Post`.
+
+.. option:: --stories-only
+
+   Rather than downloading regular posts of each specified profile, only
+   download stories.  Requires :option:`--login`. Does not imply
+   :option:`--no-profile-pic`.
+
+.. option:: --only-if filter
+
+   Expression that, if given, must evaluate to True for each post to be
+   downloaded.  Must be a syntactically valid Python expression. Variables are
+   evaluated to :class:`instaloader.Post` attributes.  Example:
+   ``--only-if=viewer_has_liked``. See :ref:`filter-posts` for more
+   examples.
+
+
+When to Stop Downloading
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If none of these options are given, Instaloader goes through all pictures
+matching the specified targets.
+
+.. option:: --fast-update
+
+   For each target, stop when encountering the first already-downloaded picture.
+   This flag is recommended when you use Instaloader to update your personal
+   Instagram archive.
+
+.. option:: --count COUNT
+
+   Do not attempt to download more than COUNT posts.  Applies only to
+   ``#hashtag`` and ``:feed``.
+
+
+Login (Download Private Profiles)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instaloader can **login to Instagram**. This allows downloading private
+profiles. To login, pass the :option:`--login` option. Your session cookie (not your
+password!) will be saved to a local file to be reused next time you want
+Instaloader to login.
+
+.. option:: --login YOUR-USERNAME
+
+   Login name (profile name) for your Instagram account.
+
+.. option:: --sessionfile SESSIONFILE
+
+   Path for loading and storing session key file.  Defaults to a path within
+   your temporary directory, encoding your local username and your Instagram
+   profile name.
+
+.. option:: --password YOUR-PASSWORD
+
+   Password for your Instagram account.  Without this option, you'll be prompted
+   for your password interactively if there is not yet a valid session file.
+
+How to Download
+^^^^^^^^^^^^^^^
+
+.. option:: --dirname-pattern DIRNAME_PATTERN
+
+   Name of directory where to store posts. ``{profile}`` is replaced by the
+   profile name, ``{target}`` is replaced by the target you specified, i.e.
+   either ``:feed``, ``#hashtag`` or the profile name. Defaults to ``{target}``.
+   See :ref:`filename-specification`.
+
+.. option:: --filename-pattern FILENAME_PATTERN
+
+   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}``, ``{date_utc}`` and
+   ``{shortcode}`` can be specified.  In case of not downloading stories, the
+   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
+
+   User Agent to use for HTTP requests. Per default, Instaloader pretends being
+   Chrome/51.
+
+.. option:: --max-connection-attempts N
+
+   Maximum number of connection attempts until a request is aborted. Defaults
+   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
+^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --quiet
+
+   Disable user interaction, i.e. do not print messages (except errors) and fail
+   if login credentials are needed but not given. This makes Instaloader
+   **suitable as a cron job**.

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 ------------------------------------------------
@@ -34,8 +38,16 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx_autodoc_typehints',
     'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx'
 ]
 
+autodoc_default_flags = ['show-inheritance', 'members', 'undoc-members']
+
+autodoc_member_order = 'bysource'
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
+                       'requests': ('http://docs.python-requests.org/en/master', None)}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -124,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,
-    'sidebar_width': '290px',
-    'page_width': '935px' }
+    'navbar_site_name': 'Site Contents',
+    'navbar_pagenav_name': 'Page Contents',
+    'navbar_pagenav': True,
+    'navbar_sidebarrel': True,
+    'nosidebar': True,
+     }
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -150,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,
@@ -182,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.
@@ -195,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.
 #
@@ -344,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,12 +1,21 @@
+.. 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.
 
-With `Python <https://www.python.org/>`__ installed, do:
-
-::
+With `Python <https://www.python.org/>`__ installed, do::
 
     $ pip3 install instaloader
 
@@ -14,23 +23,30 @@ With `Python <https://www.python.org/>`__ installed, do:
 
 **Instaloader**
 
-- downloads **public and private profiles, hashtags, user stories and
-  feeds**,
-  
+- downloads **public and private profiles, hashtags, user stories,
+  feeds and saved media**,
+
 - downloads **comments, geotags and captions** of each post,
 
 - automatically **detects profile name changes** and renames the target
   directory accordingly,
-  
+
 - 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
@@ -39,14 +55,15 @@ Table of Contents
    basic-usage
    cli-options
    as-module
+   contributing
 
 Useful Links
 ------------
 
-- `Git Repository (on GitHub) <https://github.com/Thammus/instaloader>`__
-- `PyPI Project Page <https://pypi.python.org/pypi/instaloader>`__
-- `Issue Tracker / Bug Tracker <https://github.com/Thammus/instaloader/issues>`__
-- `Version History <https://github.com/Thammus/instaloader/releases>`__
+- `Git Repository (on GitHub) <https://github.com/instaloader/instaloader>`__
+- `PyPI Project Page <https://pypi.org/project/instaloader/>`__
+- `Issue Tracker / Bug Tracker <https://github.com/instaloader/instaloader/issues>`__
+- `Version History <https://github.com/instaloader/instaloader/releases>`__
 
 .. include:: ../README.rst
    :start-after: disclaimer-start

docs/installation.rst

@@ -1,11 +1,41 @@
 Installation
 ============
 
-.. include:: ../README.rst
-   :start-after: installation-start
-   :end-before: installation-end
+.. highlight:: none
 
-If you do not want to use pip, even though it is highly recommended,
-and prefer installing Instaloader manually,
-`Download the Source <https://github.com/Thammus/instaloader/releases>`__,
-extract the Zip or Tarball and execute ``instaloader.py`` from there.
+Instaloader requires `Python <https://www.python.org/>`__, at least
+version 3.5.  If you have `pip <https://pypi.python.org/pypi/pip>`__
+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/instaloader/instaloader>`__:
+
+::
+
+    pip3 install git+https://github.com/instaloader/instaloader
+
+(pass ``--upgrade`` to upgrade if Instaloader is already installed)
+
+Instaloader requires
+`requests <http://python-requests.org/>`__, which
+will be installed automatically, if it is not already installed.
+
+**Alternative methods for installing Instaloader:**
+
+- If you do not want to use pip, even though it is highly recommended,
+  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',