Add some documentation

This commit is contained in:
moanos [he/him] 2023-01-12 08:40:25 +01:00
parent c1e4770b0e
commit 80d66b1919
3 changed files with 74 additions and 3 deletions

View File

@ -14,6 +14,77 @@ and [remove](https://docs.joinmastodon.org/methods/admin/domain_blocks/#delete)
and [add](https://docs.joinmastodon.org/methods/admin/domain_blocks/#create) newly added.
Since we have several attributes for a domain blog, a simple `.txt` file might not be sufficient. We probably want to
set the severity, reject_media, reject_reports and comments. This means we need a human readable, easily python-readable
set the severity, reject_media, reject_reports and comments. This means we need a human-readable, easily python-readable
and structured file format. Since Python 3.11 got native support for [toml](https://toml.io/) and it
supports [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables), I'd prefer to use this.
# Basic usage
##
```
$ mastodon_blocklist_deploy -h
usage: mastodon_blocklist_deploy [-h] [-s SERVER] [-t TOKEN] [-i INPUT_FILE] [-r REMOTE_BLOCKLIST] [-o OUTPUT] [-v] [-n] {diff,deploy,export}
Deploy blocklist updates to a mastodon server
positional arguments:
{diff,deploy,export} Either use 'diff' to check the difference between local blockĺist and the blocklist on the server, 'deploy' to apply the current local blocklist or 'export' to export the remote blocklist into a local file.
options:
-h, --help show this help message and exit
-s SERVER, --server SERVER
The address of the server where you want to deploy (e.g. mastodon.social)
-t TOKEN, --token TOKEN
Authorization token
-i INPUT_FILE, --input-file INPUT_FILE
The blocklist to use
-r REMOTE_BLOCKLIST, --remote-blocklist REMOTE_BLOCKLIST
The remote blocklist as json for debugging reasons
-o OUTPUT, --output OUTPUT
Filename where to export the blocklist
-v, --verbose
-n, --no-delete Do not delete existing blocks
```
## Obtain a server token
1. Be an admin on the server.
2. Add an application in the Mastodon Web Client (https://yourdomain.org/settings/applications/new. Make sure to select the permissions `admin:read` and `admin:write`.
3. Copy the Token (last value in the table) ![](assets/obtain_token.png)
# Typical workflow
1. **Export the current blocklist from the server**
```
mastodon_blocklist_deploy export -s yourserver -t yourtoken -o blocklist.toml
```
2. **Manually add something to the blocklist**
```toml
[[instances]]
name = "instance-to-block.com"
domain = "instance-to-block.com"
severity = "suspend"
reject_media = true
reject_reports = true
public_comment = "X, Y and Z"
private_comment = "We discussed this after X and Y and now that Z happend we decided to block"
```
3. **Check the difference between the local and remote blocklist**
```
mastodon_blocklist_deploy diff -s yourserver -t yourtoken -i blocklist.toml
```
4. **Apply the local blocklist to the server**
```
mastodon_blocklist_deploy apply -s yourserver -t yourtoken -i blocklist.toml
```

BIN
assets/obtain_token.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

View File

@ -59,8 +59,8 @@ def load_remote_blocklist(server: str, token: str):
def cli():
parser = argparse.ArgumentParser(description='Deploy blocklist updates to a mastodon server')
parser.add_argument('action', choices=['diff', 'deploy', 'export'],
help="Either use 'diff' to check the difference between current blocks and future blocks, "
"'deploy' to apply the current local blocklist or 'export' to export the remote "
help="Either use 'diff' to check the difference between local blockĺist and the blocklist on "
"the server, 'deploy' to apply the current local blocklist or 'export' to export the remote "
"blocklist into a local file.")
parser.add_argument('-s', '--server', help="The address of the server where you want to deploy (e.g. "
"mastodon.social)")