update and reconfigure docs
This commit is contained in:
Hugh Rundle
parent
371ed4f4e6
commit
0e1337b926
|
|
@ -7,16 +7,16 @@ You can contribute in many ways - improving the documentation, reporting bugs, s
|
|||
# Expectations
|
||||
|
||||
## Adhere to the Code of Conduct 🤗
|
||||
All contributors must adhere to the [Code of Conduct](../CODE_OF_CONDUCT.md) for this project. If you do not wish to follow this Code of Conduct, feel free to direct your energies towards a different project.
|
||||
All contributors must adhere to the [Code of Conduct](https://github.com/hughrun/ephemetoot/blob/poetry/CODE_OF_CONDUCT.md) for this project. If you do not wish to follow this Code of Conduct, feel free to direct your energies towards a different project.
|
||||
|
||||
## Do not log security problems as public issues
|
||||
If you have identified a security flaw in **ephemetoot**, please email `ephemetoot AT ausglam DOT space` to discuss this confidentially.
|
||||
If you have identified a security flaw in **ephemetoot**, please email `ephemetoot@hugh.run` to discuss this confidentially.
|
||||
|
||||
## Check existing issues 🧐
|
||||
Your bug or enhancement might already be listed in the [issues](../issues). It's a good idea to check existing issues before you log your own. If you like someone else's enhancement suggestion, please "upvote" it with a 👍 reaction. If you have also experienced the same bug as someone else, you can add any useful additional context to the existing issue.
|
||||
Your bug or enhancement might already be listed in the [issues](https://github.com/hughrun/ephemetoot/issues). It's a good idea to check existing issues before you log your own. If you like someone else's enhancement suggestion, please "upvote" it with a 👍 reaction. If you have also experienced the same bug as someone else, you can add any useful additional context to the existing issue.
|
||||
|
||||
## Always log an issue 📝
|
||||
If you would like to contribute code or documentation changes that do not already have an issue listed, you should always [log an issue](../issues) first. Please **do not add pull requests without prior discussion**. Whilst pull requests are very welcome and encouraged, if you don't log an issue for discussion first, you may end up wasting your time if someone else is already working on the same feature, or maintainers decide it isn't a good fit. This also allows for your proposed feature to be scoped before you get too deep in the weeds coding it.
|
||||
If you would like to contribute code or documentation changes that do not already have an issue listed, you should always [log an issue](https://github.com/hughrun/ephemetoot/issues) first. Please **do not add pull requests without prior discussion**. Whilst pull requests are very welcome and encouraged, if you don't log an issue for discussion first, you may end up wasting your time if someone else is already working on the same feature, or maintainers decide it isn't a good fit. This also allows for your proposed feature to be scoped before you get too deep in the weeds coding it.
|
||||
|
||||
Regardless of whether is is a bug report, feature request or code proposal, provide as much detail as possible in your issue, and give it a clear name.
|
||||
|
||||
|
|
@ -63,4 +63,10 @@ This is a pretty small project so there usually won't be a lot of issues waiting
|
|||
|
||||
# Help
|
||||
|
||||
You can get in touch with Hugh at [@hugh@ausglam.space](https://ausglam.space/@hugh) if you need help contributing or want to discuss something about **ephemetoot**.
|
||||
You can get in touch with Hugh at [@hugh@ausglam.space](https://ausglam.space/@hugh) if you need help contributing or want to discuss something about **ephemetoot**.
|
||||
|
||||
---
|
||||
* [Home](/)
|
||||
* [Installation](./install.md)
|
||||
* [Options](./options.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
|
|
@ -1,4 +1,3 @@
|
|||
# 🥳 ==> 🧼 ==> 😇
|
||||
[](http://makeapullrequest.com)
|
||||
|
||||
**ephemetoot** is a Python command line tool for deleting old toots.
|
||||
|
|
@ -6,6 +5,7 @@
|
|||
* [Installation](./install.md)
|
||||
* [Options](./options.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
* [Contributing](./contributing.md)
|
||||
|
||||
## Prior work
|
||||
The initial `ephemetoot` script was based on [this tweet-deleting script](https://gist.github.com/flesueur/bcb2d9185b64c5191915d860ad19f23f) by [@flesueur](https://github.com/flesueur)
|
||||
|
|
|
|||
|
|
@ -2,33 +2,20 @@
|
|||
|
||||
## Install Python 3 and pip
|
||||
|
||||
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. You will also need to check that `pip` is installed and pointing to Python3 (not Python2). On some systems this will mean using the command `pip3`.
|
||||
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.
|
||||
|
||||
## Install ephemetoot
|
||||
### Option 1 - get code with git
|
||||
If you already have `git` installed on the machine where you're running ephemetoot, you can download the latest release with:
|
||||
```shell
|
||||
git clone https://github.com/hughrun/ephemetoot.git
|
||||
cd ephemetoot
|
||||
git checkout [tagname]
|
||||
```
|
||||
### Option 2 - get the code by downloading the zip file
|
||||
If you don't have `git` or don't want to use it, you can download the zip file by clicking the green button above and selecting `Download ZIP`. You will then need to unzip the file into a new directory where you want to run it.
|
||||
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.
|
||||
|
||||
## Install ephemetoot from pypi
|
||||
|
||||
### Complete install with pip
|
||||
From a command line, move into the main `ephemetoot` directory (i.e. where the README file is) and run:
|
||||
```shell
|
||||
pip install .
|
||||
pip install ephemetoot
|
||||
```
|
||||
With some Python 3 installations (e.g on MacOS with Homebrew) you may need to use:
|
||||
```shell
|
||||
pip3 install .
|
||||
```
|
||||
If you do not have permission to install python modules, you may need to use the `--user` flag:
|
||||
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:
|
||||
|
||||
```shell
|
||||
pip install . --user
|
||||
```
|
||||
Note that you will need to run the script with the same user as ephemetoot will only be installed for that user and not globally.
|
||||
|
||||
## Obtain an access token
|
||||
|
||||
|
|
@ -55,7 +42,7 @@ As of version 2, you can use a single `ephemetoot` installation to delete toots
|
|||
|
||||
Copy `example-config.yaml` to a new file called `config.yaml`:
|
||||
```shell
|
||||
cp example-config.yam config.yaml
|
||||
cp example-config.yaml config.yaml
|
||||
```
|
||||
You can now enter the configuration details for each user:
|
||||
|
||||
|
|
@ -83,6 +70,7 @@ 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.
|
||||
|
||||
---
|
||||
|
||||
* [Home](/)
|
||||
* [Options](./options.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
* [Contributing](./contributing.md)
|
||||
|
|
@ -4,37 +4,42 @@ 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"!
|
||||
|
||||
## Running in test mode (--test)
|
||||
## Run in test mode (--test)
|
||||
|
||||
To do a test-run without actually deleting anything, run the script with the `--test` flag:
|
||||
```shell
|
||||
ephemetoot --test
|
||||
```
|
||||
|
||||
## Running in "live" mode
|
||||
## Run in "live" mode
|
||||
|
||||
To call the script call ephemetoot with no arguments:
|
||||
To call the script use the command `ephemetoot` without any other arguments:
|
||||
```shell
|
||||
ephemetoot
|
||||
```
|
||||
|
||||
Depending on how many toots you have and how long you want to keep them, it may take a minute or two before you see any results.
|
||||
|
||||
## Specifying the config location (--config)
|
||||
## 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:
|
||||
|
||||
```shell
|
||||
ephemetoot --config '~/directory/subdirectory/config.yaml'
|
||||
```
|
||||
## Manage timing
|
||||
|
||||
## Slow down deletes to match API limit (--pace)
|
||||
### Slow down deletes to match API limit (--pace)
|
||||
|
||||
With the `--pace` flag, delete actions are slowed so that the API limit is never reached, using [`Mastodon.py`'s 'pace' method](https://mastodonpy.readthedocs.io/en/stable/index.html?highlight=pace#mastodon.Mastodon.__init__). This is recommended for your first run, as unless you have tooted fewer than 30 times you are guaranteed to hit the API limit for deletions the first time you run `ephemetoot`. If you do not toot very often on most days, it is probably more efficient to use the default behaviour for daily runs after the first time, but you can use `--pace` every time if you prefer.
|
||||
With the `--pace` flag, delete actions are slowed so that the API limit is never reached, essentially borrowing the 'pace' method from the [`Mastodon.py`](https://mastodonpy.readthedocs.io/en/stable/index.html?highlight=pace#mastodon.Mastodon.__init__) module. This is **recommended for your first run**, as unless you have tooted fewer than 30 times you are guaranteed to hit the API limit for deletions the first time you run `ephemetoot`. If you do not toot very often on most days, it is probably more efficient to use the default behaviour for daily runs after the first time, but you can use `--pace` every time if you prefer.
|
||||
|
||||
## Increase the time between retry attempts when encountering errors (--retry-mins)
|
||||
### Increase the time between retry attempts when encountering errors (--retry-mins)
|
||||
|
||||
Use `--retry-mins` to increase the period between attempts to retry deletion after an error. The default value is one (1) minute, but you can make it anything you like. This is useful if your mastodon server is unreliable or frequently in "maintenance mode".
|
||||
Use `--retry-mins` to increase the period between attempts to retry deletion after an error. The default value is one (1) minute, but you can make it anything you like. This is useful if your mastodon server is unreliable or frequently in "maintenance mode". `ephemetoot` will make four additional attempts if it encounters an error, so the following command, for example, would wait 20 minutes between each retry, allowing the script to continue if there is an outage of 79 minutes or fewer:
|
||||
|
||||
```shell
|
||||
ephemetoot --retry-mins 20
|
||||
```
|
||||
|
||||
## Do more
|
||||
|
||||
|
|
@ -66,11 +71,7 @@ ephemetoot --config 'directory/config.yaml' --test --hide-skipped
|
|||
```
|
||||
Use them in any order:
|
||||
```shell
|
||||
ephemetoot --pace --datestamp --config 'directory/config.yaml'
|
||||
```
|
||||
Instead of coming back to this page when you forget the flags, you can just use the help option:
|
||||
```shell
|
||||
ephemetoot --help
|
||||
ephemetoot --pace --retry-mins 5 --datestamp --config 'directory/config.yaml'
|
||||
```
|
||||
|
||||
## Scheduling
|
||||
|
|
@ -85,7 +86,7 @@ To run automatically every day on a n*x server you could try using crontab:
|
|||
2. enter a new line: `@daily /path/to/ephemetoot --config /path/to/ephemetoot/config.yaml`
|
||||
3. exit with `:qw` (Vi/Vim) or `Ctrl + x` (nano)
|
||||
|
||||
### MacOS
|
||||
### MacOS (--schedule)
|
||||
|
||||
On **MacOS** you can use the `--schedule` flag to schedule a daily job with [launchd](https://www.launchd.info/). Note that this feature has not been widely tested so **please log an issue if you notice anything go wrong**.
|
||||
|
||||
|
|
@ -112,6 +113,7 @@ For example to run at 2.25pm every day:
|
|||
ephemetoot --schedule --time 14 25
|
||||
```
|
||||
---
|
||||
|
||||
* [Home](/)
|
||||
* [Installation](./install.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
* [Contributing](./contributing.md)
|
||||
|
|
@ -2,17 +2,24 @@
|
|||
|
||||
## Upgrading
|
||||
|
||||
### 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`):
|
||||
|
||||
```shell
|
||||
pip install --upgrade ephemetoot
|
||||
```
|
||||
|
||||
### Upgrading with git
|
||||
To upgrade to a new version using git, run the following from inside the `ephemetoot` directory:
|
||||
|
||||
```shell
|
||||
git fetch --tags
|
||||
git checkout [tagname]
|
||||
git checkout [latest-tagname]
|
||||
pip install .
|
||||
```
|
||||
|
||||
### Upgrading with a ZIP file
|
||||
To upgrade without using git:
|
||||
To upgrade without using git or pypi:
|
||||
|
||||
* put your config file somewhere safe
|
||||
* download and unzip the zip file into your `ephemetoot` directory over the top of your existing installation
|
||||
|
|
@ -32,6 +39,7 @@ launchctl unload ~/Library/LaunchAgents/ephemetoot.scheduler.plist
|
|||
rm ~/Library/LaunchAgents/ephemetoot.scheduler.plist
|
||||
```
|
||||
---
|
||||
|
||||
* [Home](/)
|
||||
* [Installation](./install.md)
|
||||
* [Options](./options.md)
|
||||
* [Options](./options.md)
|
||||
* [Contributing](./contributing.md)
|
||||
Loading…
Reference in New Issue