From 7de6b7f489490940aae0750d3265871c97bf0c04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= Date: Mon, 2 Jan 2023 19:14:16 +0100 Subject: [PATCH] add list of command-line options as docs/options.md (#3464) --- Makefile | 9 +- docs/options.md | 363 +++++++++++++++++++++++++++++++++++++++++++++ scripts/options.py | 77 ++++++++++ 3 files changed, 447 insertions(+), 2 deletions(-) create mode 100644 docs/options.md create mode 100755 scripts/options.py diff --git a/Makefile b/Makefile index 10b10aec..a83b57de 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ SHAREDIR ?= $(PREFIX)/share PYTHON ?= /usr/bin/env python3 -all: man completion supportedsites +all: man completion supportedsites options clean: $(RM) -r build/ @@ -30,11 +30,16 @@ man: data/man/gallery-dl.1 data/man/gallery-dl.conf.5 supportedsites: docs/supportedsites.md -.PHONY: all clean install release test executable completion man supportedsites +options: docs/options.md + +.PHONY: all clean install release test executable completion man supportedsites options docs/supportedsites.md: gallery_dl/*/*.py scripts/supportedsites.py $(PYTHON) scripts/supportedsites.py +docs/options.md: gallery_dl/option.py scripts/options.py + $(PYTHON) scripts/options.py + data/man/gallery-dl.1: gallery_dl/option.py gallery_dl/version.py scripts/man.py $(PYTHON) scripts/man.py diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 00000000..fb96ce8b --- /dev/null +++ b/docs/options.md @@ -0,0 +1,363 @@ +# Command-Line Options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
General Options
-h--helpPrint this help message and exit
--versionPrint program version and exit
-i--input-fileDownload URLs found in FILE (- for stdin). More than one --input-file can be specified
-d--destinationTarget location for file downloads
-D--directoryExact location for file downloads
-f--filenameFilename format string for downloaded files (/O for "original" filenames)
--proxyUse the specified proxy
--source-addressClient-side IP address to bind to
--user-agentUser-Agent request header
--clear-cacheDelete cached login sessions, cookies, etc. for MODULE (ALL to delete everything)
--cookiesFile to load additional cookies from
--cookies-from-browserName of the browser to load cookies from, with optional keyring name prefixed with +, profile prefixed with :, and container prefixed with :: (none for no container)
Output Options
-q--quietActivate quiet mode
-v--verbosePrint various debugging information
-g--get-urlsPrint URLs instead of downloading
-G--resolve-urlsPrint URLs instead of downloading; resolve intermediary URLs
-j--dump-jsonPrint JSON information
-s--simulateSimulate data extraction; do not download anything
-E--extractor-infoPrint extractor defaults and settings
-K--list-keywordsPrint a list of available keywords and example values for the given URLs
--list-modulesPrint a list of available extractor modules
--list-extractorsPrint a list of extractor classes with description, (sub)category and example URL
--write-logWrite logging output to FILE
--write-unsupportedWrite URLs, which get emitted by other extractors but cannot be handled, to FILE
--write-pagesWrite downloaded intermediary pages to files in the current directory to debug problems
Downloader Options
-r--limit-rateMaximum download rate (e.g. 500k or 2.5M)
-R--retriesMaximum number of retries for failed HTTP requests or -1 for infinite retries (default: 4)
--http-timeoutTimeout for HTTP connections (default: 30.0)
--sleepNumber of seconds to wait before each download. This can be either a constant value or a range (e.g. 2.7 or 2.0-3.5)
--sleep-requestNumber of seconds to wait between HTTP requests during data extraction
--sleep-extractorNumber of seconds to wait before starting data extraction for an input URL
--filesize-minDo not download files smaller than SIZE (e.g. 500k or 2.5M)
--filesize-maxDo not download files larger than SIZE (e.g. 500k or 2.5M)
--chunk-sizeSize of in-memory data chunks (default: 32k)
--no-partDo not use .part files
--no-skipDo not skip downloads; overwrite existing files
--no-mtimeDo not set file modification times according to Last-Modified HTTP response headers
--no-downloadDo not download any files
--no-postprocessorsDo not run any post processors
--no-check-certificateDisable HTTPS certificate validation
Configuration Options
-c--configAdditional configuration files
-o--optionAdditional = option values
--ignore-configDo not read default configuration files
Authentication Options
-u--usernameUsername to login with
-p--passwordPassword belonging to the given username
--netrcEnable .netrc authentication data
Selection Options
--download-archiveRecord all downloaded or skipped files in FILE and skip downloading any file already in it
-A--abortStop current extractor run after N consecutive file downloads were skipped
-T--terminateStop current and parent extractor runs after N consecutive file downloads were skipped
--rangeIndex range(s) specifying which files to download. These can be either a constant value, range, or slice (e.g. 5, 8-20, or 1:24:3)
--chapter-rangeLike --range, but applies to manga chapters and other delegated URLs
--filterPython expression controlling which files to download. Files for which the expression evaluates to False are ignored. Available keys are the filename-specific ones listed by -K. Example: --filter "image_width >= 1000 and rating in (s, q)"
--chapter-filterLike --filter, but applies to manga chapters and other delegated URLs
Post-processing Options
--zipStore downloaded files in a ZIP archive
--ugoira-convConvert Pixiv Ugoira to WebM (requires FFmpeg)
--ugoira-conv-losslessConvert Pixiv Ugoira to WebM in VP9 lossless mode
--ugoira-conv-copyConvert Pixiv Ugoira to MKV without re-encoding any frames
--write-metadataWrite metadata to separate JSON files
--write-info-jsonWrite gallery metadata to a info.json file
--write-tagsWrite image tags to separate text files
--mtime-from-dateSet file modification times according to date metadata
--execExecute CMD for each downloaded file. Example: --exec convert {} {}.png && rm {}
--exec-afterExecute CMD after all files were downloaded successfully. Example: --exec-after cd {} && convert * ../doc.pdf
-P--postprocessorActivate the specified post processor
diff --git a/scripts/options.py b/scripts/options.py new file mode 100755 index 00000000..b3b676e4 --- /dev/null +++ b/scripts/options.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +# Copyright 2023 Mike Fährmann +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 as +# published by the Free Software Foundation. + +"""Generate a Markdown document listing gallery-dl's command-line arguments""" + +import os +import re + +import util +from gallery_dl import option + + +TEMPLATE = """# Command-Line Options + + + + + + + + + + + + +{} + +
+""" + + +tbody = [] +append = tbody.append +sub = re.compile(r"'([^']+)'").sub + +for group in option.build_parser()._action_groups[2:]: + + append('\n\n ' + + group.title + '\n') + + for action in group._group_actions: + help = action.help + if help == "==SUPPRESS==": + continue + + try: + short, long = action.option_strings + except ValueError: + try: + long = action.option_strings[0] + except IndexError: + continue + short = "" + + if short: + short = "" + short + "" + if long: + long = '' + long + "" + + append("") + append(" " + short + "") + append(" " + long + "") + append(" " + sub("\\1", help) + "") + append("") + + +with open(util.path("docs", "options.md"), "w", encoding="utf-8") as fp: + fp.write(TEMPLATE.format( + "/".join(os.path.normpath(__file__).split(os.sep)[-2:]), + "\n".join(tbody), + ))