From 795965f7540a26f45f6962d4ddc8ff6db5eba989 Mon Sep 17 00:00:00 2001 From: aliparlakci Date: Thu, 12 Jul 2018 12:25:09 +0300 Subject: [PATCH] Readme refactor (#35) * Shorten the README.md file * Added more information and guides * Typo fix * Rename sections --- README.md | 39 +++++++++---------- ...help_page.md => COMMAND_LINE_ARGUMENTS.md} | 39 ++++++++++--------- docs/COMPILE_FROM_SOURCE.md | 31 +++++++++++++++ 3 files changed, 70 insertions(+), 39 deletions(-) rename docs/{help_page.md => COMMAND_LINE_ARGUMENTS.md} (58%) create mode 100644 docs/COMPILE_FROM_SOURCE.md diff --git a/README.md b/README.md index 702a3e8..5af2112 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,27 @@ This program downloads imgur, gfycat and direct image and video links of saved p **PLEASE** post any issue you have with the script to [Issues](https://github.com/aliparlakci/bulk-downloader-for-reddit/issues) tab. Since I don't have any testers or contributers I need your feedback. -## What can it do? -### It... -- can get posts from: frontpage, subreddits, multireddits, redditor's submissions, upvoted and saved posts; search results or just plain reddit links -- sorts posts by hot, top, new and so on -- downloads imgur albums, gfycat links, [self posts](#i-cant-open-the-self-posts) and any link to a direct image -- skips the existing ones -- puts post titles to file's name -- puts every post to its subreddit's folder -- saves a reusable copy of posts' details that are found so that they can be re-downloaded again -- logs failed ones in a file to so that you can try to download them later -- can be run with double-clicking on Windows (but I don't recommend it) +## What it can do +- Can get posts from: frontpage, subreddits, multireddits, redditor's submissions, upvoted and saved posts; search results or just plain reddit links +- Sorts posts by hot, top, new and so on +- Downloads imgur albums, gfycat links, [self posts](#i-can-t-open-the-self-post-files-) and any link to a direct image +- Skips the existing ones +- Puts post titles to file's name +- Puts every post to its subreddit's folder +- Saves a reusable copy of posts' details that are found so that they can be re-downloaded again +- Logs failed ones in a file to so that you can try to download them later +- Can run with double-clicking on Windows ## [Download the latest release](https://github.com/aliparlakci/bulk-downloader-for-reddit/releases/latest) +## How it works + +For **Windows** users, there is an executable file to run easily without installing a third party program. But if you are a paranoid like me, you can **[compile it from source code](docs/COMPILE_FROM_SOURCE.md)**. + +**Linux** and **MacOS** users have to **[compile it from source code](docs/COMPILE_FROM_SOURCE.md)**. + +Script also accepts **command-line arguments**, get further information from **[`python script.py --help`](docs/COMMAND_LINE_ARGUMENTS.md)** + ## Setting up the script Because this is not a commercial app, you need to create an imgur developer app in order API to work. @@ -32,18 +39,10 @@ It should redirect to a page which shows your **imgur_client_id** and **imgur_cl \* Select **OAuth 2 authorization without a callback URL** first then select **Anonymous usage without user authorization** if it says *Authorization callback URL: required* -## Running the script - -For **Windows** users, there is an *EXE* file to run easily. - -**Linux** and **MacOS** users have to install Python 3 and run it from the *source code* through terminal. - -To get further information about that and **using command-line arguments to run the script**, see **[`python script.py --help`](docs/help_page.md)** - ## FAQ ### I can't open the self post files. - Self posts are held at reddit as styled with markdown. So, the script downloads them as they are in order not to lose their stylings. - However, there is a great Chrome extension [here](https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk) for viewing Markdown files with its styling. Install it and open the files with Chrome. + However, there is a [great Chrome extension](https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk) for viewing Markdown files with its styling. Install it and open the files with [Chrome](https://www.google.com/intl/tr/chrome/). ## Changelog ### [11/07/2018](https://github.com/aliparlakci/bulk-downloader-for-reddit/tree/a28a7776ab826dea2a8d93873a94cd46db3a339b) diff --git a/docs/help_page.md b/docs/COMMAND_LINE_ARGUMENTS.md similarity index 58% rename from docs/help_page.md rename to docs/COMMAND_LINE_ARGUMENTS.md index 2563485..e9905d5 100644 --- a/docs/help_page.md +++ b/docs/COMMAND_LINE_ARGUMENTS.md @@ -1,6 +1,10 @@ -## python script.py --help +# Using command-line arguments +See **[compiling from source](COMPILE_FROM_SOURCE.md)** page first unless you are using the .exe file. If you are using the .exe file, see [using terminal](COMPILE_FROM_SOURCE.md#using-terminal) and come back. + +***Use*** `.\script.exe` ***if you are using the executable***. ```console +$ python script.py --help usage: script.py [-h] [--directory DIRECTORY] [--link link] [--saved] [--submitted] [--upvoted] [--log LOG FILE] [--subreddit SUBREDDIT [SUBREDDIT ...]] @@ -37,7 +41,7 @@ optional arguments: downloading later ``` -## Examples +# Examples - **Use `python3` instead of `python` if you are using *MacOS* or *Linux*** @@ -46,40 +50,37 @@ python script.py ``` ```console -python script.py .\\NEW_FOLDER --sort new --time all --limit 10 --link "https://www.reddit.com/r/gifs/search?q=dogs&restrict_sr=on&type=link&sort=new&t=month" +.\script.exe .\\NEW_FOLDER --search cats --sort new --time all --subreddit gifs pics --NoDownload ``` ```console -python script.py .\\NEW_FOLDER --link "https://www.reddit.com/r/learnprogramming/comments/7mjw12/" +python script.py --directory .\\NEW_FOLDER --sort new --time all --limit 10 --link "https://www.reddit.com/r/gifs/search?q=dogs&restrict_sr=on&type=link&sort=new&t=month" ``` ```console -python script.py .\\NEW_FOLDER --search cats --sort new --time all --subreddit gifs pics --NoDownload +python script.py --directory .\\NEW_FOLDER --link "https://www.reddit.com/r/learnprogramming/comments/7mjw12/" ``` ```console -python script.py .\\NEW_FOLDER --user [USER_NAME] --submitted --limit 10 +python script.py --directory .\\NEW_FOLDER --search cats --sort new --time all --subreddit gifs pics --NoDownload ``` ```console -python script.py .\\NEW_FOLDER --multireddit good_subs --user [USER_NAME] --sort top --time week --limit 250 +python script.py --directory .\\NEW_FOLDER --user [USER_NAME] --submitted --limit 10 ``` ```console -python script.py .\\NEW_FOLDER\\ANOTHER_FOLDER --saved --limit 1000 +python script.py --directory .\\NEW_FOLDER --multireddit good_subs --user [USER_NAME] --sort top --time week --limit 250 ``` ```console -python script.py C:\\NEW_FOLDER\\ANOTHER_FOLDER --log UNNAMED_FOLDER\\FAILED.json +python script.py --directory .\\NEW_FOLDER\\ANOTHER_FOLDER --saved --limit 1000 ``` -## FAQ -### I can't startup the script no matter what. -- Try these: - - **`python`** - - **`python3`** - - **`python3.7`** - - **`python3.6`** - - **`py -3`** - - Python have real issues about naming their program +```console +python script.py --directory C:\\NEW_FOLDER\\ANOTHER_FOLDER --log UNNAMED_FOLDER\\FAILED.json +``` + +# FAQ +## I can't startup the script no matter what. +See **[finding the correct prefix for Python](COMPILE_FROM_SOURCE.md#finding-the-correct-prefix-for-python)** diff --git a/docs/COMPILE_FROM_SOURCE.md b/docs/COMPILE_FROM_SOURCE.md new file mode 100644 index 0000000..77a97e0 --- /dev/null +++ b/docs/COMPILE_FROM_SOURCE.md @@ -0,0 +1,31 @@ +# Compiling from source code +## Requirements +### Python 3 Interpreter +Latest* version of **Python 3** is needed. Download the matching release for your platform [here](https://www.python.org/downloads/) and install it. If you are a *Windows* user, selecting **Add Python 3 to PATH** option is mandatory. + +\* *Use Python 3.6.5 if you encounter an issue* +## Using terminal +### To open it... +- On Windows 8/8.1/10: Press the File tab on **Windows Explorer**, click on **Open Windows PowerShell** or **Open Windows Command Prompt** or look for *Command Prompt* or *PowerShell* in *Start Menu*. + +- On Windows 7: Press **WindowsKey+R**, type **cmd** and hit Enter or look for *Command Prompt* or *PowerShell* in *Start Menu*. + +- On Linux: Press **Ctrl+Alt+T** or look for **Terminal** in the programs. + +- On MacOS: Look for an app called **Terminal**. + +### Navigating to the directory where script is downloaded +Go inside the folder where script.py is located. If you are not familier with changing directories on command-prompt and terminal read *Changing Directories* in [this article](https://lifehacker.com/5633909/who-needs-a-mouse-learn-to-use-the-command-line-for-almost-anything) + +## Finding the correct prefix for Python +Enter these lines to terminal windows until it prints out the version you have downloaded and installed: +- `python --version` +- `python3 --version` +- `python3.7 --version` +- `python3.6 --version` +- `py --version` +- `py -3 --version` +- `py -3.6 --version` +- `py -3.7 --version` + +Once you find it, use it at [Using command-line arguments](COMMAND_LINE_ARGUMENTS.md) \ No newline at end of file