Compile and render Synapse's docs into a browsable, mobile-friendly and searchable website (#10086)

9 files changed, 37 insertions, 51 deletions

diff --git a/docs/admin_api/README.rst b/docs/admin_api/README.rst
index 9587bee0ce..37cee87d32 100644
--- a/docs/admin_api/README.rst
+++ b/docs/admin_api/README.rst
@@ -1,28 +1,14 @@
 Admin APIs
 ==========
 
-This directory includes documentation for the various synapse specific admin
-APIs available.
-
-Authenticating as a server admin
---------------------------------
-
-Many of the API calls in the admin api will require an `access_token` for a
-server admin. (Note that a server admin is distinct from a room admin.)
-
-A user can be marked as a server admin by updating the database directly, e.g.:
-
-.. code-block:: sql
+**Note**: The latest documentation can be viewed `here <https://matrix-org.github.io/synapse>`_.
+See `docs/README.md <../docs/README.md>`_ for more information.
 
-    UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
+**Please update links to point to the website instead.** Existing files in this directory
+are preserved to maintain historical links, but may be moved in the future.
 
-A new server admin user can also be created using the
-``register_new_matrix_user`` script.
-
-Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings.
-
-Once you have your `access_token`, to include it in a request, the best option is to add the token to a request header:
-
-``curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>``
+This directory includes documentation for the various synapse specific admin
+APIs available. Updates to the existing Admin API documentation should still
+be made to these files, but any new documentation files should instead be placed under
+`docs/usage/administration/admin_api <../docs/usage/administration/admin_api>`_.
 
-Fore more details, please refer to the complete `matrix spec documentation <https://matrix.org/docs/spec/client_server/r0.5.0#using-access-tokens>`_.
diff --git a/docs/admin_api/delete_group.md b/docs/admin_api/delete_group.md
index c061678e75..9c335ff759 100644
--- a/docs/admin_api/delete_group.md
+++ b/docs/admin_api/delete_group.md
@@ -11,4 +11,4 @@ POST /_synapse/admin/v1/delete_group/<group_id>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
diff --git a/docs/admin_api/event_reports.md b/docs/admin_api/event_reports.md
index bfec06f755..186139185e 100644
--- a/docs/admin_api/event_reports.md
+++ b/docs/admin_api/event_reports.md
@@ -7,7 +7,7 @@ The api is:
 GET /_synapse/admin/v1/event_reports?from=0&limit=10
 ```
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 It returns a JSON body like the following:
 
@@ -95,7 +95,7 @@ The api is:
 GET /_synapse/admin/v1/event_reports/<report_id>
 ```
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 It returns a JSON body like the following:
 
diff --git a/docs/admin_api/media_admin_api.md b/docs/admin_api/media_admin_api.md
index 7709f3d8c7..9ab5269881 100644
--- a/docs/admin_api/media_admin_api.md
+++ b/docs/admin_api/media_admin_api.md
@@ -28,7 +28,7 @@ The API is:
 GET /_synapse/admin/v1/room/<room_id>/media
 ```
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 The API returns a JSON body like the following:
 ```json
@@ -311,7 +311,7 @@ The following fields are returned in the JSON response body:
 * `deleted`: integer - The number of media items successfully deleted
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 If the user re-requests purged remote media, synapse will re-request the media
 from the originating server.
diff --git a/docs/admin_api/purge_history_api.md b/docs/admin_api/purge_history_api.md
index 44971acd91..25decc3e61 100644
--- a/docs/admin_api/purge_history_api.md
+++ b/docs/admin_api/purge_history_api.md
@@ -17,7 +17,7 @@ POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 By default, events sent by local users are not deleted, as they may represent
 the only copies of this content in existence. (Events sent by remote users are
diff --git a/docs/admin_api/room_membership.md b/docs/admin_api/room_membership.md
index b6746ff5e4..ed40366099 100644
--- a/docs/admin_api/room_membership.md
+++ b/docs/admin_api/room_membership.md
@@ -24,7 +24,7 @@ POST /_synapse/admin/v1/join/<room_id_or_alias>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 Response:
 
diff --git a/docs/admin_api/rooms.md b/docs/admin_api/rooms.md
index 5721210fee..dc007fa00e 100644
--- a/docs/admin_api/rooms.md
+++ b/docs/admin_api/rooms.md
@@ -443,7 +443,7 @@ with a body of:
 ```
 
 To use it, you will need to authenticate by providing an ``access_token`` for a
-server admin: see [README.rst](README.rst).
+server admin: see [Admin API](../../usage/administration/admin_api).
 
 A response body like the following is returned:
 
diff --git a/docs/admin_api/statistics.md b/docs/admin_api/statistics.md
index d398a120fb..d93d52a3ac 100644
--- a/docs/admin_api/statistics.md
+++ b/docs/admin_api/statistics.md
@@ -10,7 +10,7 @@ GET /_synapse/admin/v1/statistics/users/media
 ```
 
 To use it, you will need to authenticate by providing an `access_token`
-for a server admin: see [README.rst](README.rst).
+for a server admin: see [Admin API](../../usage/administration/admin_api).
 
 A response body like the following is returned:
 
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 0c843316c9..c835e4a0cd 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -11,7 +11,7 @@ GET /_synapse/admin/v2/users/<user_id>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 It returns a JSON body like the following:
 
@@ -78,7 +78,7 @@ with a body of:
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 URL parameters:
 
@@ -119,7 +119,7 @@ GET /_synapse/admin/v2/users?from=0&limit=10&guests=false
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -237,7 +237,7 @@ See also: [Client Server
 API Whois](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-admin-whois-userid).
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 It returns a JSON body like the following:
 
@@ -294,7 +294,7 @@ with a body of:
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 The erase parameter is optional and defaults to `false`.
 An empty body may be passed for backwards compatibility.
@@ -339,7 +339,7 @@ with a body of:
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 The parameter `new_password` is required.
 The parameter `logout_devices` is optional and defaults to `true`.
@@ -354,7 +354,7 @@ GET /_synapse/admin/v1/users/<user_id>/admin
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -384,7 +384,7 @@ with a body of:
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 
 ## List room memberships of a user
@@ -398,7 +398,7 @@ GET /_synapse/admin/v1/users/<user_id>/joined_rooms
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -443,7 +443,7 @@ GET /_synapse/admin/v1/users/<user_id>/media
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -591,7 +591,7 @@ GET /_synapse/admin/v2/users/<user_id>/devices
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -659,7 +659,7 @@ POST /_synapse/admin/v2/users/<user_id>/delete_devices
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 An empty JSON dict is returned.
 
@@ -683,7 +683,7 @@ GET /_synapse/admin/v2/users/<user_id>/devices/<device_id>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -731,7 +731,7 @@ PUT /_synapse/admin/v2/users/<user_id>/devices/<device_id>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 An empty JSON dict is returned.
 
@@ -760,7 +760,7 @@ DELETE /_synapse/admin/v2/users/<user_id>/devices/<device_id>
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 An empty JSON dict is returned.
 
@@ -781,7 +781,7 @@ GET /_synapse/admin/v1/users/<user_id>/pushers
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -872,7 +872,7 @@ POST /_synapse/admin/v1/users/<user_id>/shadow_ban
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 An empty JSON dict is returned.
 
@@ -897,7 +897,7 @@ GET /_synapse/admin/v1/users/<user_id>/override_ratelimit
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -939,7 +939,7 @@ POST /_synapse/admin/v1/users/<user_id>/override_ratelimit
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 A response body like the following is returned:
 
@@ -984,7 +984,7 @@ DELETE /_synapse/admin/v1/users/<user_id>/override_ratelimit
 ```
 
 To use it, you will need to authenticate by providing an `access_token` for a
-server admin: [Admin API](README.rst)
+server admin: [Admin API](../../usage/administration/admin_api)
 
 An empty JSON dict is returned.