update README

- mention and link to docs/configuration.rst - add OAuth section
7 years ago · fbe8c519e2
parent e1d82af5e0
commit fbe8c519e2
3 changed files with 66 additions and 11 deletions
--- a/README.rst
+++ b/README.rst
@ -130,7 +130,9 @@ Configuration
 =============

 Configuration files for *gallery-dl* use a JSON-based file format.
-For a (more or less) complete example, see gallery-dl.conf_.
+For a (more or less) complete example of a configuration file, see
+gallery-dl.conf_. A list of all available configuration options and their
+descriptions can be found in configuration.rst_.

 *gallery-dl* searches for configuration files in the following paths:

@ -151,9 +153,13 @@ Values in later configuration files will override previous ones.
 Authentication
 ==============

-Some extractors require you to provide valid login-credentials.
-This currently includes ``pixiv``, ``exhentai``, ``nijie``, ``seiga``
-and ``batoto``.
+Username & Password
+-------------------
+
+Some extractors require you to provide valid login-credentials in the form of
+a username & password pair.
+This is necessary for ``pixiv``, ``nijie`` and ``seiga`` and optional
+(but strongly recommended) for ``exhentai`` and ``batoto``.

 You can set the necessary information in your configuration file
 (cf. gallery-dl.conf_)
@ -180,8 +186,28 @@ or you can provide them directly via the
    $ gallery-dl -u <username> -p <password> URL
    $ gallery-dl -o username=<username> -o password=<password> URL

+OAuth
+-----
+
+*gallery-dl* supports user authentication via OAuth_ for ``flickr`` and
+``reddit``. This is entirely optional, but grants *gallery-dl* the ability
+to issue requests on your account's behalf and enables it to access resources
+which would otherwise be unavailable to a public user.
+
+To link your account to *gallery-dl*, start by invoking it with
+``oauth:<site-name>`` as an argument. For example:
+
+.. code:: bash
+
+    $ gallery-dl oauth:flickr
+
+You will be sent to the site's authorization page and asked to grant read
+access to *gallery-dl*. Authorize it and you will he shown one or more
+"tokens", which should be added to your configuration file.
+

 .. _gallery-dl.conf:       https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl.conf
+.. _configuration.rst:     https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst
 .. _Complete List:         https://github.com/mikf/gallery-dl/blob/master/docs/supportedsites.rst
 .. _standalone executable: https://github.com/mikf/gallery-dl/releases/download/v0.8.4/gallery-dl.exe
 .. _Python:   https://www.python.org/downloads/
@ -190,6 +216,7 @@ or you can provide them directly via the
 .. _pip:      https://pip.pypa.io/en/stable/
 .. _stable:   https://github.com/mikf/gallery-dl/archive/v0.8.4.zip
 .. _dev:      https://github.com/mikf/gallery-dl/archive/master.zip
+.. _OAuth:    https://en.wikipedia.org/wiki/OAuth

 .. |pypi| image:: https://img.shields.io/pypi/v/gallery-dl.svg
    :target: https://pypi.python.org/pypi/gallery-dl
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@ -27,9 +27,9 @@ cache.file
 ----------
 =========== =====
 Type        ``string``
-Default     ``tempfile.gettempdir() + ".gallery-dl.cache"``
+Default     |tempfile.gettempdir()|_ + ``".gallery-dl.cache"``
 Description Path of the SQLite3 database used to cache login sessions,
-            smaller cookies and API tokens.
+            cookies and API tokens.

            Set this value to an invalid path or simply ``null`` to disable
            this cache.
@ -101,7 +101,7 @@ Description Amount of time (in seconds) to wait for a successful connection
            and a response from a remote server.

            This value gets internally used as the ``timeout`` parameter for the
-            `requests.get()`_ method.
+            |requests.get()|_ method.
 =========== =====


@ -177,7 +177,7 @@ Type        ``bool``
 Default     ``true``
 Description Enable mature content.

-            This option simply sets the ``mature_content`` parameter for API
+            This option simply sets the |mature_content|_ parameter for API
            calls to either ``"true"`` or ``"false"`` and does not do any other
            form of content filtering.
 =========== =====
@ -294,7 +294,7 @@ Type        ``bool``
 Default     ``true``
 Description Controls how a user is directed to a OAuth authorization site.

-            * ``true``: Use Python's `webbrowser.open()`_ method to automatically
+            * ``true``: Use Python's |webbrowser.open()|_ method to automatically
              open the URL in the user's browser.
            * ``false``: Ask the user to copy & paste an URL from the terminal.
 =========== =====
@ -330,6 +330,18 @@ Description The value of the ``limit`` parameter when loading
 =========== =====


+extractor.reddit.morecomments
+-------------------------
+=========== =====
+Type        ``bool``
+Default     ``false``
+Description Retrieve additional comments by resolving the ``more`` comment
+            stubs in the base commment tree.
+
+            This requires 1 additional API call for every 100 extra comments.
+=========== =====
+
+
 extractor.reddit.date-min
 -------------------------
 =========== =====
@ -371,11 +383,24 @@ Type        ``string``
 Default     ``null``
 Description The ``refresh_token`` value you get from linking your Reddit account
            to ``gallery-dl``.
+
+            Using the ``refresh_token`` allows you to access private or otherwise
+            not publicly available subreddits, given that your account is
+            authorized to do so,
+            but requests to the reddit API are going to be rate limited
+            at 600 requests every 10 minutes/600 seconds.
 =========== =====


-.. _requests.get():    http://docs.python-requests.org/en/latest/user/advanced/#timeouts
+.. |tempfile.gettempdir()| replace:: ``tempfile.gettempdir()``
+.. |requests.get()| replace:: ``requests.get()``
+.. |mature_content| replace:: ``mature_content``
+.. |webbrowser.open()| replace:: ``webbrowser.open()``
+
+.. _tempfile.gettempdir(): https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir
+.. _requests.get():    https://docs.python-requests.org/en/latest/user/advanced/#timeouts
 .. _format string:     https://docs.python.org/3/library/string.html#formatstrings
 .. _format strings:    https://docs.python.org/3/library/string.html#formatstrings
+.. _mature_content:    https://www.deviantart.com/developers/http/v1/20160316/object/deviation
 .. _webbrowser.open(): https://docs.python.org/3/library/webbrowser.html
 .. _Authentication:    https://github.com/mikf/gallery-dl#5authentication
--- a/docs/gallery-dl.conf
+++ b/docs/gallery-dl.conf
@ -55,6 +55,7 @@
        {
            "refresh-token": null,
            "comments": 500,
+            "morecomments": false,
            "date-min": 0,
            "date-max": 253402210800,
            "recursion": 0
@ -62,7 +63,9 @@
        "flickr":
        {
            "access-token": null,
-            "access-token-secret": null
+            "access-token-secret": null,
+            "metadata": false,
+            "size-max": null
        }
    },
    "output":