From d4a461387f27b4dba02e19b4b3f1cf4da562d40a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= Date: Tue, 3 Jan 2023 16:47:57 +0100 Subject: [PATCH] update README.rst more needs to be done, but at least it's a start --- README.rst | 99 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 38 deletions(-) diff --git a/README.rst b/README.rst index 80862526..3a09e3e9 100644 --- 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 `_. +*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 `__. -|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) `__) - `Linux `__ + +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 ``__ +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 ``__. + +| For a default configuration file with available options set to their + default values, see ``__. + +| For a commented example with more involved settings and option usage, + see ``__. + + +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\\``) 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 `__, +*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 `__ .. code:: json @@ -251,8 +269,8 @@ or you can provide them directly via the .. code:: bash - gallery-dl -u -p URL - gallery-dl -o username= -o password= URL + gallery-dl -u "" -p "" "URL" + gallery-dl -o "username=" -o "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 `__ +`cookies `__ 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 `__, in `Firefox `__) +- | 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