update docs for version 3

README.md

@@ -3,6 +3,7 @@
 
 **ephemetoot** is a Python command line tool for deleting old toots.
 
+## Documentation
 * [Installation](./docs/install.md)
 * [Options](./docs/options.md)
 * [Upgrading and uninstalling](./docs/upgrade.md)
@@ -13,29 +14,14 @@ The initial `ephemetoot` script was based on [this tweet-deleting script](https:
 `ephemetoot` relies heavily on the Mastodon.py package by [@halcy](https://github.com/halcy)
 
 ## Usage
-
 You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/mastodon) toots that are older than a certain number of days (default is 365). Toots can optionally be saved from deletion if:
 * they are pinned; or
 * they include certain hashtags; or
 * they have certain visibility; or
 * they are individually listed to be kept
 
-## Rate limits
-
-As of Mastodon v2.7.2 the Mastodon API has a rate limit of 30 deletions per 30 minutes. `mastodon.py` automatically handles this. If you are running `ephemetoot` for the first time and/or have a lot of toots to delete, it may take a while as the script will pause when it hits a rate limit, until the required time has expired. You can use the `--pace` flag to slow down ephemetoot so that it never hits the limit - this is recommended on your first run. It will not speed up the process but will smooth it out.
-
-Note that the rate limit is per access token, so using ephemetoot for multiple accounts on the same server shouldn't be a big problem, however one new user may delay action on subsequent accounts in the config file.
-
-## ASCII / utf-8 errors
-
-Prior to Python 3.7, running a Python script on some BSD and Linux systems may throw an error. This can be resolved by:
-* setting a _locale_ that encodes utf-8, by using the environment setting `PYTHONIOENCODING=utf-8` when running the script, or 
-* upgrading your Python version to 3.7 or higher. See [Issue 11](https://github.com/hughrun/ephemetoot/issues/11) for more information.
-
 ## Contributing
-
 For all bugs, suggestions, pull requests or other contributions, please check the [contributing guide](./docs/contributing.md).
 
 ## License
-
 This project and all contributions are [licensed](./LICENSE) under the GPL 3.0 or future version

docs/index.md

@@ -2,6 +2,8 @@
 
 **ephemetoot** is a Python command line tool for deleting old toots.
 
+These docs apply to Version 3.
+
 * [Installation](./install.md)
 * [Options](./options.md)
 * [Upgrading and uninstalling](./upgrade.md)
@@ -13,7 +15,6 @@ The initial `ephemetoot` script was based on [this tweet-deleting script](https:
 `ephemetoot` relies heavily on the Mastodon.py package by [@halcy](https://github.com/halcy)
 
 ## Usage
-
 You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/mastodon) toots that are older than a certain number of days (default is 365). Toots can optionally be saved from deletion if:
 * they are pinned; or
 * they include certain hashtags; or
@@ -21,21 +22,17 @@ You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/masto
 * they are individually listed to be kept
 
 ## Rate limits
-
 As of Mastodon v2.7.2 the Mastodon API has a rate limit of 30 deletions per 30 minutes. `mastodon.py` automatically handles this. If you are running `ephemetoot` for the first time and/or have a lot of toots to delete, it may take a while as the script will pause when it hits a rate limit, until the required time has expired. You can use the `--pace` flag to slow down ephemetoot so that it never hits the limit - this is recommended on your first run. It will not speed up the process but will smooth it out.
 
 Note that the rate limit is per access token, so using ephemetoot for multiple accounts on the same server shouldn't be a big problem, however one new user may delay action on subsequent accounts in the config file.
 
 ## ASCII / utf-8 errors
-
 Prior to Python 3.7, running a Python script on some BSD and Linux systems may throw an error. This can be resolved by:
 * setting a _locale_ that encodes utf-8, by using the environment setting `PYTHONIOENCODING=utf-8` when running the script, or 
 * upgrading your Python version to 3.7 or higher. See [Issue 11](https://github.com/hughrun/ephemetoot/issues/11) for more information.
 
 ## Contributing
-
 For all bugs, suggestions, pull requests or other contributions, please check the [contributing guide](./docs/contributing.md).
 
 ## License
-
 This project and all contributions are [licensed](https://github.com/hughrun/ephemetoot/blob/master/LICENSE) under the GPL 3.0 or future version

docs/install.md

@@ -4,17 +4,17 @@
 
 You need to [install Python 3](https://wiki.python.org/moin/BeginnersGuide/Download) to use `ephemetoot`. Python 2 is now end-of-life, however it continued to be installed as the default Python on MacOS and many Linux distributions until very recently, so you should check. 
 
-These instructions use the command `pip` but note that on many systems you may need to use `pip3`, as pip will be pointing to Python 2.
+These instructions use the command `pip3` since it is very likely you will need to use that instead of `pip` (which usually points to Python 2). On some systems you may need to use `pip` instead, if `pip` is pointing to Python 3.
 
 ## Install ephemetoot from pypi
 
 ```shell
-pip install ephemetoot
+pip3 install ephemetoot
 ```
-If you do not have permission to install python modules, you may need to use the `--user` flag. Generally this is not advisable, since you will need to run the script with the same user as ephemetoot will only be installed for that user and not globally:
+If you do not have permission to install python modules, you may need to use the `--user` flag. Generally this is not advisable, since you will need to run ephemetoot with the same user since it will only be installed for that user and not globally:
 
 ```shell
-pip install . --user
+pip3 install . --user
 ```
 
 ## Obtain an access token
@@ -38,13 +38,15 @@ Now you've installed `ephemetoot`, in order to actually use it you will need an
 
 ## Configuration file
 
-As of version 2, you can use a single `ephemetoot` installation to delete toots from multiple accounts. Configuration for each user is set up in the `config.yaml` file. This uses [yaml syntax](https://yaml.org/spec/1.2/spec.html) and can be updated at any time without having to reload `ephemetoot`.
+Configuration for each user is set up in the `config.yaml` file. This uses [yaml syntax](https://yaml.org/spec/1.2/spec.html) and can be updated at any time without having to reload `ephemetoot`.
+
+You can create a config file by hand, but the easiest way to do it is with the `--init` flag:
 
-Copy `example-config.yaml` to a new file called `config.yaml`:
 ```shell
-cp example-config.yaml config.yaml
+ephemetoot --init
 ```
-You can now enter the configuration details for each user:
+
+This will ask you to fill in information for each part of the file:
 
 | setting | description   |
 | ---:  |   :---        |
@@ -67,7 +69,7 @@ hashtags_to_keep:
 visibility_to_keep: [ ] # this empty list is also ok
 ```
 
-If you want to use `ephemetoot` for multiple accounts, separate the config for each user with a single dash (`-`), as shown in the example file.
+As of version 2, you can use a single `ephemetoot` installation to delete toots from multiple accounts. If you want to use `ephemetoot` for multiple accounts, separate the config for each user with a single dash (`-`), and add the additional details, as shown in [the example file](https://github.com/hughrun/ephemetoot/blob/master/example-config.yaml).
 
 ---
 * [Home](/)

docs/options.md

@@ -4,6 +4,16 @@ For a short description of all available options, run `ephemetoot --help` from t
 
 It is **strongly recommended** that you do a test run before using `ephemetoot` live. There is no "undo"!
 
+## Create your config file (--init)
+
+Before you can use `ephemetoot` you need a `config.yaml` file. You can create this yourself, but `--init` will walk you through the values you need and save your `config.yaml` file in the directory from which you run the command:
+
+```shell
+ephemetoot --init
+```
+
+More information about the config file can be found on teh _[Installation](./install.md)_ page, and an [example file](https://github.com/hughrun/ephemetoot/blob/master/example-config.yaml) is available on GitHub.
+
 ## Run in test mode (--test)
 
 To do a test-run without actually deleting anything, run the script with the `--test` flag:
@@ -22,7 +32,7 @@ Depending on how many toots you have and how long you want to keep them, it may
 
 ## Specify the config location (--config)
 
-By default ephemetoot expects there to be a config file called `config.yaml` in the directory from where you run the `ephemetoot` command. If you want to call it from elsewhere (e.g. with `cron`), you need to specify where your config file is:
+By default ephemetoot expects there to be a config file called `config.yaml` in the directory from where you run the `ephemetoot` command. If you want to call it from elsewhere (e.g. when using `cron`), you need to specify where your config file is:
 
 ```shell
 ephemetoot --config '~/directory/subdirectory/config.yaml'

docs/upgrade.md

@@ -2,11 +2,20 @@
 
 ## Upgrading
 
+### Note for users upgrading from Version 2 to Version 3
+
+To upgrade from Version 2.x to Version 3.x you should be able to simply follow the _Upgrading with pypi_ instructions below. However the safest procedure is:
+
+1. save a copy of your `config.yaml` file somewhere safe
+2. run `pip uninstall ephemetoot`
+3. run `pip install ephemetoot`
+4. do a test run with `ephemetoot --test`
+
 ### Upgrading with pypi
-To upgrade to a new version, the easiest way is to use pip to download the latest version from pypi (remembering that for your machine you may need to substitute `pip3` for `pip`):
+To upgrade to a new version, the easiest way is to use pip to download the latest version from pypi (remembering that for your machine you may need to substitute `pip` for `pip3`):
 
 ```shell
-pip install --upgrade ephemetoot
+pip3 install --upgrade ephemetoot
 ```
 
 ### Upgrading with git
@@ -15,7 +24,7 @@ To upgrade to a new version using git, run the following from inside the `epheme
 ```shell
 git fetch --tags
 git checkout [latest-tagname]
-pip install .
+pip3 install .
 ```
 
 ### Upgrading with a ZIP file
@@ -30,7 +39,7 @@ To upgrade without using git or pypi:
 
 Uninstall using pip:
 ```shell
-pip uninstall ephemetoot
+pip3 uninstall ephemetoot
 ```
 
 If you scheduled a `launchd` job on MacOS using `--schedule`, you will also need to unload and remove the scheduling file: