Add an API vs command overview in table form to docs

doc/source/conf.py

@@ -71,7 +71,7 @@
     'collapse_navigation': True,
     'navigation_depth': 8,
     'sticky_navigation': False,
-    'prev_next_buttons_location': 'both'
+    'prev_next_buttons_location': 'bottom'
 }
 
 

doc/source/features.rst

@@ -0,0 +1,152 @@
+Synapse Admin API Coverage
+==========================
+
+The tables below show which Synapse Admin APIs are used by their corresponding ``synadm`` commands.
+The left column's entries link to the official Synapse Admin API documentation, the right column's entries point to the ``synadm`` CLI reference.
+To add missing entries to a table edit one of the CSV files in our `documentation source directory`_ and submit a `pull request`_.
+
+Account Validity
+----------------
+
+.. csv-table::
+   :file: features_account_validity.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Background Updates
+------------------
+
+.. csv-table::
+   :file: features_background_updates.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Delete Group
+------------
+
+.. csv-table::
+   :file: features_delete_group.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Event Reports
+-------------
+
+.. csv-table::
+   :file: features_event_reports.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Experimental Features
+---------------------
+
+.. csv-table::
+   :file: features_experimental_features.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Media
+-----
+
+.. csv-table::
+   :file: features_media.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+   :keepspace:
+
+Purge History
+-------------
+
+.. csv-table::
+   :file: features_purge_history.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Register Users
+--------------
+
+.. csv-table::
+   :file: features_register_users.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Registration Tokens
+-------------------
+
+.. csv-table::
+   :file: features_registration_tokens.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Manipulate Room Membership
+--------------------------
+
+.. csv-table::
+   :file: features_manipulate_room_membership.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Rooms
+-----
+
+.. csv-table::
+   :file: features_rooms.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Server Notices
+--------------
+
+.. csv-table::
+   :file: features_server_notices.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Statistics
+----------
+
+.. csv-table::
+   :file: features_statistics.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Users
+-----
+
+.. csv-table::
+   :file: features_users.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Server Version
+--------------
+
+.. csv-table::
+   :file: features_server_version.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Federation
+----------
+
+.. csv-table::
+   :file: features_federation.csv
+   :header: "Synapse Admin API","synadm command(s)"
+   :widths: 1 1
+
+Miscellaneous
+-------------
+
+.. csv-table::
+   :file: features_miscellaneous.csv
+   :header: "Description","synadm command(s)"
+   :widths: 1 1
+
+
+.. _documentation source directory:
+   https://github.com/JOJ0/synadm/tree/master/doc/source/features.csv
+.. _feature request issue:
+   https://github.com/JOJ0/synadm/issues/new
+.. _pull request:
+   https://github.com/JOJ0/synadm/blob/dev/CONTRIBUTING.md#submitting-your-work
+.. |indent| unicode:: U+00A0 U+00A0 .. non-breaking two-space indentation

doc/source/features_account_validity.csv

@@ -0,0 +1 @@
+"`Renew account <https://element-hq.github.io/synapse/latest/admin_api/account_validity.html#renew-account>`_",

doc/source/features_background_updates.csv

@@ -0,0 +1,3 @@
+"`Status <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#status>`_",
+"`Enabled <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#enabled>`_",
+"`Run <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#run>`_",

doc/source/features_delete_group.csv

@@ -0,0 +1 @@
+"`Delete a local group <https://element-hq.github.io/synapse/v1.61/admin_api/delete_group.html#delete-a-local-group>`_",:option:`synadm group delete GROUP_ID`

doc/source/features_event_reports.csv

@@ -0,0 +1,3 @@
+"`Show reported events <https://element-hq.github.io/synapse/latest/admin_api/event_reports.html#show-reported-events>`_",
+"`Show details of a specific event report <https://element-hq.github.io/synapse/latest/admin_api/event_reports.html#show-details-of-a-specific-event-report>`_",
+"`Delete a specific event report <https://element-hq.github.io/synapse/latest/admin_api/event_reports.html#delete-a-specific-event-report>`_",

doc/source/features_experimental_features.csv

@@ -0,0 +1,2 @@
+"`Enabling/Disabling Features <https://element-hq.github.io/synapse/latest/admin_api/experimental_features.html#enablingdisabling-features>`_",
+"`Listing Enabled Features <https://element-hq.github.io/synapse/latest/admin_api/experimental_features.html#listing-enabled-features>`_",

doc/source/features_federation.csv

@@ -0,0 +1,4 @@
+"`List of destinations <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/federation.html#list-of-destinations>`_",
+"`Destination Details API <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/federation.html#destination-details-api>`_",
+"`Destination rooms <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/federation.html#destination-rooms>`_",
+"`Reset connection timeout <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/federation.html#reset-connection-timeout>`_",

doc/source/features_manipulate_room_membership.csv

@@ -0,0 +1 @@
+"`Edit Room Membership API <https://element-hq.github.io/synapse/latest/admin_api/room_membership.html#edit-room-membership-api>`_",:option:`synadm room join ROOM_ID_OR_ALIAS`

doc/source/features_media.csv

@@ -0,0 +1,15 @@
+"`Querying media <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#querying-media>`_","---"
+"|indent| `List all media in a room <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#list-all-media-in-a-room>`_",:option:`synadm media list -r`
+"|indent| `List all media uploaded by a user <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#delete-media-uploaded-by-a-user>`_",:option:`synadm media list -u` :option:`synadm user media -f`
+"`Quarantine media <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#quarantine-media>`_","---"
+"|indent| `Quarantining media by ID <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#quarantining-media-by-id>`_",:option:`synadm media quarantine -i`
+"|indent| `Remove media from quarantine by ID <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#remove-media-from-quarantine-by-id>`_",:option:`synadm media unquarantine -i`
+"|indent| `Quarantining media in a room <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#quarantining-media-in-a-room>`_",:option:`synadm media quarantine -r`
+"|indent| `Quarantining all media of a user <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#quarantining-all-media-of-a-user>`_",:option:`synadm media quarantine -u`
+"|indent| `Protecting media from being quarantined <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#protecting-media-from-being-quarantined>`_",:option:`synadm media protect MEDIA_ID`
+"|indent| `Unprotecting media from being quarantined <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#unprotecting-media-from-being-quarantined>`_",
+"`Delete local media <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#delete-local-media>`_","---"
+"|indent| `Delete a specific local media <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#delete-a-specific-local-media>`_",:option:`synadm media delete -i`
+"|indent| `Delete local media by date or size <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#delete-local-media-by-date-or-size>`_",:option:`synadm media delete -d` :option:`synadm media delete --size`
+"|indent| `Delete media uploaded by a user <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#delete-media-uploaded-by-a-user>`_",
+"`Purge Remote Media API <https://element-hq.github.io/synapse/latest/admin_api/media_admin_api.html#purge-remote-media-api>`_",:option:`synadm media purge -d`

doc/source/features_miscellaneous.csv

@@ -0,0 +1,5 @@
+"The Configurator",:option:`synadm config -u`
+"Any Synapse Admin API",:option:`synadm raw ENDPOINT`
+"Native Matrix API Helpers","---"
+"|indent| Matrix User Login",:option:`synadm matrix login USER_ID`
+"|indent| Any Matrix API",:option:`synadm matrix raw ENDPOINT`

doc/source/features_purge_history.csv

@@ -0,0 +1,2 @@
+"`Purge history <https://element-hq.github.io/synapse/latest/admin_api/purge_history_api.html>`_",:option:`synadm history purge -i`
+"`Purge status query <https://element-hq.github.io/synapse/latest/admin_api/purge_history_api.html#purge-status-query>`_",:option:`synadm history purge-status PURGE_ID`

doc/source/features_register_users.csv

@@ -0,0 +1 @@
+"`Shared-Secret Registration <https://element-hq.github.io/synapse/latest/admin_api/register_api.html#shared-secret-registration>`_",

doc/source/features_registration_tokens.csv

@@ -0,0 +1,6 @@
+"`Registration token objects <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#registration-token-objects>`_","---"
+"`List all tokens <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#list-all-tokens>`_",:option:`synadm regtok list -v`
+"`Get one token <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#get-one-token>`_",:option:`synadm regtok details TOKEN`
+"`Create token <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#create-token>`_",:option:`synadm regtok new -n`
+"`Update token <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#update-token>`_",:option:`synadm regtok update TOKEN`
+"`Delete token <https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html#delete-token>`_",:option:`synadm regtok delete TOKEN`

doc/source/features_rooms.csv

@@ -0,0 +1,21 @@
+"`List Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#list-room-api>`_",:option:`synadm room list -f`
+"`Room Details API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-details-api>`_",:option:`synadm room details ROOM_ID`
+"`Room Members API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-members-api>`_",:option:`synadm room members ROOM_ID`
+"`Room State API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-state-api>`_",:option:`synadm room state ROOM_ID`
+"`Room Messages API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-messages-api>`_",
+"`Room Timestamp to Event API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#room-timestamp-to-event-api>`_",
+"`Block Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-room-api>`_","---"
+"|indent| `Block or unblock a room <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#block-or-unblock-a-room>`_",:option:`synadm room block -b` :option:`synadm room block -u`
+"|indent| `Get block status <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#get-block-status>`_",:option:`synadm room block-status ROOM_ID`
+"`Delete Room API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#delete-room-api>`_","---"
+"|indent| `Version 1 (old version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-1-old-version>`_",:option:`synadm room delete --v1`
+"|indent| `Version 2 (new version) <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#version-2-new-version>`_",:option:`synadm room delete ROOM_ID`
+"|indent| `Status of deleting rooms <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#status-of-deleting-rooms>`_","---"
+"|indent| |indent| `Query by room_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-room_id>`_",:option:`synadm room delete-status -r`
+"|indent| |indent| `Query by delete_id <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#query-by-delete_id>`_",:option:`synadm room delete-status -d`
+"|indent| `Undoing room deletions <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#undoing-room-deletions>`_",
+"`Make Room Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api>`_",:option:`synadm room make-admin -u`
+"`Forward Extremities Admin API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#forward-extremities-admin-api>`_",
+"|indent| `Check for forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#check-for-forward-extremities>`_",
+"|indent| `Deleting forward extremities <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#deleting-forward-extremities>`_",
+"`Event Context API <https://element-hq.github.io/synapse/latest/admin_api/rooms.html#event-context-api>`_",

doc/source/features_server_notices.csv

@@ -0,0 +1 @@
+"`Server Notices <https://element-hq.github.io/synapse/latest/admin_api/server_notices.html>`_",:option:`synadm notice send TO`

doc/source/features_server_version.csv

@@ -0,0 +1 @@
+"`Version API <https://element-hq.github.io/synapse/latest/admin_api/version_api.html>`_",:option:`synadm version`

doc/source/features_statistics.csv

@@ -0,0 +1,2 @@
+"`Users' media usage statistics <https://element-hq.github.io/synapse/latest/admin_api/statistics.html#users-media-usage-statistics>`_",
+"`Get largest rooms by size in database <https://element-hq.github.io/synapse/latest/admin_api/statistics.html#get-largest-rooms-by-size-in-database>`_",

doc/source/features_users.csv

@@ -0,0 +1,33 @@
+"`Query User Account <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#query-user-account>`_",:option:`synadm user details USER_ID`
+"`Create or modify account <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#create-or-modify-account>`_",:option:`synadm user modify USER_ID`
+"`List Accounts <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-accounts>`_","---"
+"|indent| `List Accounts (V2) <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-accounts-v2>`_",:option:`synadm user list -f`
+"|indent| `List Accounts (V3) <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-accounts-v3>`_",
+"`Query current sessions for a user <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#query-current-sessions-for-a-user>`_",:option:`synadm user whois USER_ID`
+"`Deactivate Account <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#deactivate-account>`_",:option:`synadm user deactivate USER_ID`
+"`Reset password <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#reset-password>`_",:option:`synadm user password USER_ID`
+"`Get whether a user is a server administrator or not <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#get-whether-a-user-is-a-server-administrator-or-not>`_",
+"`Change whether a user is a server administrator or not <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#change-whether-a-user-is-a-server-administrator-or-not>`_",
+"`List room memberships of a user <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-room-memberships-of-a-user>`_",:option:`synadm user membership USER_ID`
+"`Account Data <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#account-data>`_",
+"`User media <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#user-media>`_","---"
+"|indent| `List media uploaded by a user <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-media-uploaded-by-a-user>`_",:option:`synadm user media -f` :option:`synadm media list -u`
+"|indent| `Delete media uploaded by a user <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#delete-media-uploaded-by-a-user>`_",
+"`Login as a user <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user>`_",:option:`synadm user login USER_ID`
+"`Allow replacing master cross-signing key without... <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#allow-replacing-master-cross-signing-key-without-user-interactive-auth>`_",
+"`User devices <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#user-devices>`_","---"
+"|indent| `List all devices <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-all-devices>`_",:option:`synadm user prune-devices --list-only`
+"|indent| `Create a device <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#create-a-device>`_",
+"|indent| `Delete multiple devices <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#delete-multiple-devices>`_",:option:`synadm user prune-devices -d` :option:`synadm user prune-devices -s`
+"|indent| `Show a device <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#show-a-device>`_",:option:`synadm user prune-devices --list-only` (-i)
+"|indent| `Update a device <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#update-a-device>`_",
+"|indent| `Delete a device <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#delete-a-device>`_",:option:`synadm user prune-devices -i`
+"`List all pushers <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-all-pushers>`_",
+"`Controlling whether a user is shadow-banned <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#controlling-whether-a-user-is-shadow-banned>`_",:option:`synadm user shadow-ban USER_ID` :option:`synadm user shadow-ban --unban`
+"`Override ratelimiting for users <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users>`_","---"
+"|indent| `Get status of ratelimit <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#get-status-of-ratelimit>`_",
+"|indent| `Set ratelimit <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#set-ratelimit>`_",
+"|indent| `Delete ratelimit <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#delete-ratelimit>`_",
+"`Check username availability <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#check-username-availability>`_",
+"`Find a user based on their ID in an auth provider <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#find-a-user-based-on-their-id-in-an-auth-provider>`_",:option:`synadm user 3pid ADDRESS`
+"`Find a user based on their Third Party ID <https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#find-a-user-based-on-their-third-party-id-threepid-or-3pid>`_",:option:`synadm user auth-provider EXTERNAL_USER_ID`

doc/source/index.rst

@@ -8,9 +8,9 @@ Welcome to synadm's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    index_cli_reference
+   features
    examples
    index_modules
 

doc/source/index_cli_reference.rst

@@ -2,8 +2,7 @@ Command Line Reference
 ======================
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :maxdepth: 3
 
    synadm.cli.root
    synadm.cli.config

doc/source/synadm.cli.config.rst

@@ -1,5 +1,5 @@
-Config
-======
+Config Command
+==============
 
 .. click:: synadm.cli:config_cmd
    :prog: synadm config

doc/source/synadm.cli.group.rst

@@ -1,6 +1,6 @@
-Group
-=====
+Group Commands
+==============
 
 .. click:: synadm.cli.group:group
    :prog: synadm group
-   :nested: full
+   :nested: full

doc/source/synadm.cli.history.rst

@@ -1,6 +1,6 @@
-History
-=======
+History Commands
+================
 
 .. click:: synadm.cli.history:history
    :prog: synadm history
-   :nested: full
+   :nested: full

doc/source/synadm.cli.matrix.rst

@@ -1,5 +1,5 @@
-Matrix
-======
+Matrix Commands
+===============
 
 .. click:: synadm.cli.matrix:matrix
    :prog: synadm matrix