update README.rst

more needs to be done, but at least it's a start
2 years ago · d4a461387f
parent 50d89d4acb
commit d4a461387f
1 changed files with 61 additions and 38 deletions
--- a/README.rst
+++ b/README.rst
@ -2,13 +2,16 @@
 gallery-dl
 ==========

-*gallery-dl* is a command-line program to download image galleries and
-collections from several image hosting sites (see `Supported Sites`_).
-It is a cross-platform tool with many configuration options
-and powerful `filenaming capabilities <Formatting_>`_.
+*gallery-dl* is a command-line program
+to download image galleries and collections
+from several image hosting sites
+(see `Supported Sites <docs/supportedsites.md>`__).
+It is a cross-platform tool
+with many `configuration options <docs/configuration.rst>`__
+and powerful `filenaming capabilities <docs/formatting.md>`__.


-|pypi| |build| |gitter|
+|pypi| |build|

 .. contents::

@ -22,7 +25,7 @@ Dependencies
 Optional
 --------

- FFmpeg_: Pixiv Ugoira to WebM conversion
+- FFmpeg_: Pixiv Ugoira conversion
 - yt-dlp_ or youtube-dl_: Video downloads
 - PySocks_: SOCKS proxy support
 - brotli_ or brotlicffi_: Brotli compression support
@ -70,6 +73,10 @@ required Python packages included are available for
  (Requires `Microsoft Visual C++ Redistributable Package (x86) <https://aka.ms/vs/17/release/vc_redist.x86.exe>`__)
 - `Linux   <https://github.com/mikf/gallery-dl/releases/download/v1.24.2/gallery-dl.bin>`__

+
+Nightly Builds
+--------------
+
 | Executables build from the latest commit can be found at
 | https://github.com/mikf/gallery-dl/actions/workflows/executables.yml

@ -122,9 +129,10 @@ from:

 .. code:: bash

-    gallery-dl [OPTION]... URL...
+    gallery-dl [OPTIONS]... URLS...

-See also :code:`gallery-dl --help`.
+Use :code:`gallery-dl --help` or see `<docs/options.md>`__
+for a full list of all command-line options.


 Examples
@ -172,13 +180,22 @@ Configuration

 Configuration files for *gallery-dl* use a JSON-based file format.

-| For a (more or less) complete example with options set to their default values,
-  see gallery-dl.conf_.
-| For a configuration file example with more involved settings and options,
-  see gallery-dl-example.conf_.
-| A list of all available configuration options and their
-  descriptions can be found in configuration.rst_.
-|
+
+Documentation
+-------------
+
+A list of all available configuration options and their descriptions
+can be found in `<docs/configuration.rst>`__.
+
+| For a default configuration file with available options set to their
+  default values, see `<docs/gallery-dl.conf>`__.
+
+| For a commented example with more involved settings and option usage,
+  see `<docs/gallery-dl-example.conf>`__.
+
+
+Locations
+---------

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

@ -187,7 +204,7 @@ Windows:
    * ``%USERPROFILE%\gallery-dl\config.json``
    * ``%USERPROFILE%\gallery-dl.conf``

-    (``%USERPROFILE%`` usually refers to the user's home directory,
+    (``%USERPROFILE%`` usually refers to a user's home directory,
    i.e. ``C:\Users\<username>\``)

 Linux, macOS, etc.:
@ -196,12 +213,13 @@ Linux, macOS, etc.:
    * ``${HOME}/.config/gallery-dl/config.json``
    * ``${HOME}/.gallery-dl.conf``

-Values in later configuration files will override previous ones.
+When run as `executable <Standalone Executable_>`__,
+*gallery-dl* will also look for a ``gallery-dl.conf`` file
+in the same directory as said executable.

-Command line options will override all related settings in the configuration file(s),
-e.g. using ``--write-metadata`` will enable writing metadata using the default values
-for all ``postprocessors.metadata.*`` settings, overriding any specific settings in
-configuration files.
+It is possible to use more than one configuration file at a time.
+In this case, any values from files after the first will get merged
+into the already loaded settings and potentially override previous ones.


 Authentication
@ -231,8 +249,8 @@ and optional for
 ``twitter``,
 and ``zerochan``.

-You can set the necessary information in your configuration file
-(cf. gallery-dl.conf_)
+You can set the necessary information in your
+`configuration file <Configuration_>`__

 .. code:: json

@ -251,8 +269,8 @@ or you can provide them directly via the

 .. code:: bash

-    gallery-dl -u <username> -p <password> URL
-    gallery-dl -o username=<username> -o password=<password> URL
+    gallery-dl -u "<username>" -p "<password>" "URL"
+    gallery-dl -o "username=<username>" -o "password=<password>" "URL"


 Cookies
@ -263,7 +281,7 @@ CAPTCHA or similar, or has not been implemented yet, you can use the
 cookies from a browser login session and input them into *gallery-dl*.

 This can be done via the
-`cookies <https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst#extractorcookies>`__
+`cookies <docs/configuration.rst#extractorcookies>`__
 option in your configuration file by specifying

 - | the path to a Mozilla/Netscape format cookies.txt file exported by a browser addon
@ -274,6 +292,9 @@ option in your configuration file by specifying
  | (in `Chrome <https://developers.google.com/web/tools/chrome-devtools/storage/cookies>`__,
     in `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Storage_Inspector>`__)

+- | the name of a browser to extract cookies from
+  | (supported browsers are Chromium-based ones, Firefox, and Safari)
+
 For example:

 .. code:: json
@ -287,24 +308,34 @@ For example:
                "cookies": {
                    "session_id": "K1T57EKu19TR49C51CDjOJoXNQLF7VbdVOiBrC9ye0a"
                }
+            },
+            "twitter": {
+                "cookies": ["firefox"]
            }
        }
    }

-You can also specify a cookies.txt file with
-the :code:`--cookies` command-line option:
+| You can also specify a cookies.txt file with
+  the :code:`--cookies` command-line option
+| or a browser to extract cookies from with :code:`--cookies-from-browser`:

 .. code:: bash

-    gallery-dl --cookies "$HOME/path/to/cookies.txt" URL
+    gallery-dl --cookies "$HOME/path/to/cookies.txt" "URL"
+    gallery-dl --cookies-from-browser firefox "URL"


 OAuth
 -----

 *gallery-dl* supports user authentication via OAuth_ for
-``deviantart``, ``flickr``, ``reddit``, ``smugmug``, ``tumblr``,
+``deviantart``,
+``flickr``,
+``reddit``,
+``smugmug``,
+``tumblr``,
 and ``mastodon`` instances.
+
 This is mostly 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.
@ -329,13 +360,6 @@ To authenticate with a ``mastodon`` instance, run *gallery-dl* with
    gallery-dl oauth:mastodon:https://mastodon.social/


-
-.. _gallery-dl.conf:         https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl.conf
-.. _gallery-dl-example.conf: https://github.com/mikf/gallery-dl/blob/master/docs/gallery-dl-example.conf
-.. _configuration.rst:       https://github.com/mikf/gallery-dl/blob/master/docs/configuration.rst
-.. _Supported Sites:         https://github.com/mikf/gallery-dl/blob/master/docs/supportedsites.md
-.. _Formatting:              https://github.com/mikf/gallery-dl/blob/master/docs/formatting.md
-
 .. _Python:     https://www.python.org/downloads/
 .. _PyPI:       https://pypi.org/
 .. _pip:        https://pip.pypa.io/en/stable/
@ -346,7 +370,6 @@ To authenticate with a ``mastodon`` instance, run *gallery-dl* with
 .. _PySocks:    https://pypi.org/project/PySocks/
 .. _brotli:     https://github.com/google/brotli
 .. _brotlicffi: https://github.com/python-hyper/brotlicffi
-.. _pyOpenSSL:  https://pyopenssl.org/
 .. _Snapd:      https://docs.snapcraft.io/installing-snapd
 .. _OAuth:      https://en.wikipedia.org/wiki/OAuth
 .. _Chocolatey: https://chocolatey.org/install