Merge pull request #149 from JOJ0/dev

Add an API vs command overview in table form to docs

CONTRIBUTING.md

@@ -6,6 +6,7 @@
   - [Programming](#programming)
 - [Submitting Your Work](#submitting-your-work)
 - [Expectations Regarding Timelines](#expectations-regarding-timelines)
+- [Feature Coverage Documentation](#feature-coverage-documentation)
 - [Discuss \& Design First](#discuss--design-first)
 - [Getting the Source \& Installing](#getting-the-source--installing)
 - [Command Design](#command-design)
@@ -27,16 +28,15 @@ No matter if you're a programmer or not there are many ways to contribute to the
 ### Non-Programming
 
 * [Set up synadm](README.md#installation) and report whether the installation, configuration and update processes work as described or could be improved. We don't have the resources to test on many operating systems, but you can [let us know](https://matrix.to/#/%23synadm%3Apeek-a-boo.at?via=jacksonchen666.com&via=maclemon.at&via=matrix.org&via=raim.ist) if it does work.
-* Help keeping the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter up to date. The Synapse project is steadily releasing new features for the _Synapse Admin API_. We can't keep up with updating this list but still think it is a handy overview of what's supported and what isn't.
-* Help prioritizing what to code next: Pick a feature from the list you find in the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter, open a GitHub issue and tell us what it is. If you don't find the feature in the list, please add it!
+* Help keep the features list on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html) up to date.
 * Improve the docs: The end-user documentation is entirely realized with the typical online help of Unix commands, an option named`--help/-h`. We believe that a top-priority in designing CLI tools is getting this information right. Spelling, wording and of course technical correctness are equally important. If it's not easily possible to stay brief and technically precise at the same time, we believe it is OK to prioritize precision over shortness. We also have documentation made with _Sphinx_ [available online](https://synadm.readthedocs.io/en/latest/index_cli_reference.html).
 
 ### Programming
 
-* Pick an open issue on GitHub or an unticked feature from the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter, start implementing and submit a pull-request when you are ready to receive our feedback.
+* Pick an [open issue on GitHub](https://github.com/JOJ0/synadm/issues) or a not yet implemented [Synapse Admin API](https://synadm.readthedocs.io/en/latest/features.html) (see [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html)) and start implementing it, then submit a pull-request when you are ready.
   * If you'd like to receive "early feedback" even though you think your code is not ready yet, submit your PR already and set it to draft state. You can then mention us (`@` then followed by a GitHub username).
   * It's ok to open a Draft PR even if you don't want our feedback yet but it helps you in any way. We won't bother you until you ping us.
-* Read the [Synapse Admin API docs](https://github.com/matrix-org/synapse/tree/master/docs/admin_api), pick a feature, implement it and send a pull-request. Don't forget to check if the feature is listed in the [Implementation Status / Commands List](README.md#implementation-status--commands-list) chapter already. If not, please add the command to the list (preferably in a separate commit).
+* Don't forget to check if the feature you are submitting is listed on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html) already. If not, please add it to the corresponding table (preferably in a separate commit).
 
 
 ## Submitting Your Work
@@ -60,6 +60,31 @@ We are maintaining `synadm` in our spare time and currently are not sponsored by
 - Unfortunately we often see contributors submitting PR's, correcting a few of our suggested changes but then disappear, so if you realize you won't find the time at all to continue your work, **please just let us know**.
 - We believe that even the tiniest feature deserves a timely release. Sometimes we just can't make it soon enough because we don't find the time or we wait for something else because it makes sense to be released together. If a feature you submitted is merged and you'd need it urgently to be available on PyPi, **please let us know**.
 
+## Feature Coverage Documentation
+
+We keep track of which Synapse Admin API's `synadm` supports in a set of tables on [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html). The structure of this page follows the layout of the official [Synapse Admin API documentation](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html). Each table represents one main chapter of the Synapse documentation.
+
+In our documentation source, the page is defined by [features.rst](https://github.com/JOJ0/synadm/blob/master/doc/source/features.rst), which contains multiple CSV files, each representing a table. To assist with maintaining this page, we offer a [web scraper tool](https://github.com/JOJ0/synadm/blob/master/scrape_docs.py) that pulls data from the Synapse Admin API docs and creates an initial version of such a CSV table. A basic usage example is
+
+```
+./scrape_docs.py -o csv https://element-hq.github.io/synapse/latest/admin_api/rooms.html
+```
+
+which prints a two-column CSV table containing restructuredText formatted hyperlinks in the left column. A corresponding `synadm` command is supposed to be added to the right hand side column manually. For example, you could add the following:
+
+```
+:option:`synadm user details USER_ID`
+```
+
+This would directly link to the `USER_ID` argument's documentation of that command.
+Linking to an option is also possible:
+
+```
+:option:`synadm media list -r`
+```
+
+Due to a shortcoming of Sphinx it is currently not possible to link to a plain command (without any option or argument). Also see `scrape_docs.py --help` and the [existing CSV files](https://github.com/JOJ0/synadm/tree/master/doc/source/features).
+
 
 ## Discuss & Design First
 

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,155 @@
+API to CLI Mapping
+==========================
+
+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`_ - see `feature coverage documentation`_ for details.
+
+
+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/
+.. _feature request issue:
+   https://github.com/JOJ0/synadm/issues/new
+.. _pull request:
+   https://github.com/JOJ0/synadm/blob/master/CONTRIBUTING.md#submitting-your-work
+.. _feature coverage documentation:
+   https://github.com/JOJ0/synadm/blob/master/CONTRIBUTING.md#feature-coverage-documentation 
+.. |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>`_",