Add documentation

README.rst

+==============
+Mailman3 tools
+==============
+
+This is a collection of MM3 tools to aid in daily administration of
+Mailman3 (MM3) installations. Main goal was not to replicate existing
+functionality but mainly augument existing toolkit with missing
+functions.
+
+.. ..contents:: Table of contents
+  :depth: 2
+
+overall this toolkit is aimed at Docker-based mailman installations
+using maxking's docker-compose project.
+
+Easiest way to use those tools is to mount them inside mailman-web container
+which already contains mailmanclient library and is running::
+
+  mailman-web:
+    image: maxking/mailman-web:0.1.7
+    container_name: mailman-web
+    ...
+    volumes:
+      ...
+      - $MAILMAN_WEB_DIR:/opt/mailman-web-data
+      - /opt/Mailman-tools:/opt/mailman-tools
+      ...
+
+this way tools are accessible from host environment via "docker exec" or
+"docker-compose exec" invocations::
+
+  $ docker exec -it mailman-web python /opt/mailman-tools/list_stats.py --all > stats.json
+
+Tools
+=====
+
+list_stats.py
+-------------
+
+obtain list statistics::
+
+  "mylist": {
+    "owners": 2,
+    "messages_held": 0,
+    "members": 7,
+    "list_fqdn_name": "mylist@lists.stanford.edu",
+    "last_digest": "2018-02-09T19:09:55.256954",
+    "nonmembers": 26,
+    "subscription_requests": 0,
+    "last_post": "2017-10-20T16:34:20.959539",
+    "moderators": 3
+  }
+
+One can use jq to format output into something more concise::
+
+  $ docker exec -it mailman-web python /opt/mailman-tools/list_stats.py --all > stats.json
+  $ jq -cr 'to_entries[]| { (.key): {"held": (.value | .messages_held), "requests": (.value | .subscription_requests)} }' stats.json
+
+manage_list.py
+==============
+
+this is the command-line interface for interaction with mailing list
+operational functions: moderate requests/messages.
+
+this tool utilizes following subcommand structure:
+
+* held
+  * list
+  * approve
+  * reject
+  * discard
+  * delete
+  * defer
+* requests
+  * list
+  * approve
+  * discard
+  * defer
+
+for example moderate messages::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME held list > held.json
+  $ jq -r .[].request_id held.json  # print all request_id's
+  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME held discard --id=1234
+
+subscription request moderation is handled in a similar fashion::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME requests list > requests.json
+  $ jq -r .[].token requests.json  # print all tokens currently active
+  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME requests discard --token=abcd123xyz
+
+manage_settings.py
+==================
+
+this script helps to dump/restore/update list settings::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ docker exec -i mailman-web python /opt/mailman-tools/manage_settings.py --dump $LIST_NAME > /${LIST_NAME}.json
+  $ vi ${LIST_NAME}.json
+  ...edit out all the fields that you do not intend to modify
+  ...and leave only ones that you want modify
+  $ cat %{LIST_NAME}.json | docker exec -t mailman-web python /opt/mailman-tools/manage_settings.py --update $LIST_NAME
+  $ # Or simply update settings right from CLI:
+  $ docker exec -t mailman-web python /opt/mailman-tools/manage_settings.py --set autoresponse_request_text="your request awaits approval" $LIST_NAME
+
+manage_users.py
+===============
+
+dump/restore User subscriptions for specific mailing list
+
+member_settings.py
+==================
+
+dump member subscription preferences for specified mailing list::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ docker exec -t mailman-web python /opt/mailman-tools/member_settings.py --member=me@stanford.edu --member=him@stanford.edu $LIST_NAME
+
+remove_user.py
+==============
+
+unsubscribes users from ML::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ docker exec -t mailman-web python /opt/mailman-tools/remove_user.py --member=me@stanford.edu --member=him@stanford.edu $LIST_NAME
+
+stats2omd.py
+============
+
+Helper script for processing bulk list stats (produced by list_stats.py) into
+OMD (Check_mk) digestable format::
+
+  $ docker-compose -f mailman-docker-compose.yml exec -T mailman-web python /opt/mailman-tools/list_stats.py > stats.json
+  $ python stats2omd.py < stats.json
+
+note that one doesn't have to run it within container as it doesn't use
+any of the mailman APIs it's just a post-processing tool
+
+sync_users.py
+=============
+
+synchronize list subscribers with a given list::
+
+  $ LIST_NAME=mylist@lists.stanford.edu
+  $ cat desired_member_list | docker exec -i mailman-web python /opt/mailman-tools/sync_users.py $LIST_NAME
+
+this will remove users that are not in specified member list file and add the ones
+that are.