Convert admin api docs to markdown (#10089)

So that they render nicely in mdbook (see #10086), and so that we no longer have a mix of structured text languages in our documentation (excluding files outside of `docs/`).

changelog.d/10089.doc

+Convert the remaining Admin API documentation files to markdown.

docs/admin_api/account_validity.rst → docs/admin_api/account_validity.md

-Account validity API
-====================
+# Account validity API
 
 This API allows a server administrator to manage the validity of an account. To
 use it, you must enable the account validity feature (under
-``account_validity``) in Synapse's configuration.
+`account_validity`) in Synapse's configuration.
 
-Renew account
--------------
+## Renew account
 
 This API extends the validity of an account by as much time as configured in the
-``period`` parameter from the ``account_validity`` configuration.
+`period` parameter from the `account_validity` configuration.
 
-The API is::
+The API is:
 
-    POST /_synapse/admin/v1/account_validity/validity
+```
+POST /_synapse/admin/v1/account_validity/validity
+```
 
 with the following body:
 
-.. code:: json
+```json
+{
+    "user_id": "<user ID for the account to renew>",
+    "expiration_ts": 0,
+    "enable_renewal_emails": true
+}
+```
 
-    {
-        "user_id": "<user ID for the account to renew>",
-        "expiration_ts": 0,
-        "enable_renewal_emails": true
-    }
 
-
-``expiration_ts`` is an optional parameter and overrides the expiration date,
+`expiration_ts` is an optional parameter and overrides the expiration date,
 which otherwise defaults to now + validity period.
 
-``enable_renewal_emails`` is also an optional parameter and enables/disables
+`enable_renewal_emails` is also an optional parameter and enables/disables
 sending renewal emails to the user. Defaults to true.
 
 The API returns with the new expiration date for this account, as a timestamp in
 milliseconds since epoch:
 
-.. code:: json
-
-    {
-        "expiration_ts": 0
-    }
+```json
+{
+    "expiration_ts": 0
+}
+```

docs/admin_api/purge_history_api.rst → docs/admin_api/purge_history_api.md

-Purge History API
-=================
+# Purge History API
 
 The purge history API allows server admins to purge historic events from their
 database, reclaiming disk space.
@@ -13,10 +12,12 @@ delete the last message in a room.
 
 The API is:
 
-``POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]``
+```
+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: see `README.rst <README.rst>`_.
+To use it, you will need to authenticate by providing an `access_token` for a
+server admin: [Admin API](README.rst)
 
 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
@@ -24,54 +25,54 @@ deleted.)
 
 Room state data (such as joins, leaves, topic) is always preserved.
 
-To delete local message events as well, set ``delete_local_events`` in the body:
+To delete local message events as well, set `delete_local_events` in the body:
 
-.. code:: json
-
-   {
-       "delete_local_events": true
-   }
+```
+{
+   "delete_local_events": true
+}
+```
 
 The caller must specify the point in the room to purge up to. This can be
 specified by including an event_id in the URI, or by setting a
-``purge_up_to_event_id`` or ``purge_up_to_ts`` in the request body. If an event
+`purge_up_to_event_id` or `purge_up_to_ts` in the request body. If an event
 id is given, that event (and others at the same graph depth) will be retained.
-If ``purge_up_to_ts`` is given, it should be a timestamp since the unix epoch,
+If `purge_up_to_ts` is given, it should be a timestamp since the unix epoch,
 in milliseconds.
 
 The API starts the purge running, and returns immediately with a JSON body with
 a purge id:
 
-.. code:: json
-
-    {
-        "purge_id": "<opaque id>"
-    }
+```json
+{
+    "purge_id": "<opaque id>"
+}
+```
 
-Purge status query
-------------------
+## Purge status query
 
 It is possible to poll for updates on recent purges with a second API;
 
-``GET /_synapse/admin/v1/purge_history_status/<purge_id>``
+```
+GET /_synapse/admin/v1/purge_history_status/<purge_id>
+```
 
-Again, you will need to authenticate by providing an ``access_token`` for a
+Again, you will need to authenticate by providing an `access_token` for a
 server admin.
 
 This API returns a JSON body like the following:
 
-.. code:: json
-
-    {
-        "status": "active"
-    }
+```json
+{
+    "status": "active"
+}
+```
 
-The status will be one of ``active``, ``complete``, or ``failed``.
+The status will be one of `active`, `complete`, or `failed`.
 
-Reclaim disk space (Postgres)
------------------------------
+## Reclaim disk space (Postgres)
 
 To reclaim the disk space and return it to the operating system, you need to run
 `VACUUM FULL;` on the database.
 
-https://www.postgresql.org/docs/current/sql-vacuum.html
+<https://www.postgresql.org/docs/current/sql-vacuum.html>

docs/admin_api/register_api.rst → docs/admin_api/register_api.md

-Shared-Secret Registration
-==========================
+# Shared-Secret Registration
 
 This API allows for the creation of users in an administrative and
 non-interactive way. This is generally used for bootstrapping a Synapse
 instance with administrator accounts.
 
 To authenticate yourself to the server, you will need both the shared secret
-(``registration_shared_secret`` in the homeserver configuration), and a
+(`registration_shared_secret` in the homeserver configuration), and a
 one-time nonce. If the registration shared secret is not configured, this API
 is not enabled.
 
-To fetch the nonce, you need to request one from the API::
+To fetch the nonce, you need to request one from the API:
 
-  > GET /_synapse/admin/v1/register
+```
+> GET /_synapse/admin/v1/register
 
-  < {"nonce": "thisisanonce"}
+< {"nonce": "thisisanonce"}
+```
 
-Once you have the nonce, you can make a ``POST`` to the same URL with a JSON
+Once you have the nonce, you can make a `POST` to the same URL with a JSON
 body containing the nonce, username, password, whether they are an admin
 (optional, False by default), and a HMAC digest of the content. Also you can
-set the displayname (optional, ``username`` by default).
+set the displayname (optional, `username` by default).
 
-As an example::
+As an example:
 
-  > POST /_synapse/admin/v1/register
-  > {
-     "nonce": "thisisanonce",
-     "username": "pepper_roni",
-     "displayname": "Pepper Roni",
-     "password": "pizza",
-     "admin": true,
-     "mac": "mac_digest_here"
-    }
+```
+> POST /_synapse/admin/v1/register
+> {
+   "nonce": "thisisanonce",
+   "username": "pepper_roni",
+   "displayname": "Pepper Roni",
+   "password": "pizza",
+   "admin": true,
+   "mac": "mac_digest_here"
+  }
 
-  < {
-     "access_token": "token_here",
-     "user_id": "@pepper_roni:localhost",
-     "home_server": "test",
-     "device_id": "device_id_here"
-    }
+< {
+   "access_token": "token_here",
+   "user_id": "@pepper_roni:localhost",
+   "home_server": "test",
+   "device_id": "device_id_here"
+  }
+```
 
 The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
 the shared secret and the content being the nonce, user, password, either the
 string "admin" or "notadmin", and optionally the user_type
-each separated by NULs. For an example of generation in Python::
+each separated by NULs. For an example of generation in Python:
 
-  import hmac, hashlib
+```python
+import hmac, hashlib
 
-  def generate_mac(nonce, user, password, admin=False, user_type=None):
+def generate_mac(nonce, user, password, admin=False, user_type=None):
 
-      mac = hmac.new(
-        key=shared_secret,
-        digestmod=hashlib.sha1,
-      )
+    mac = hmac.new(
+      key=shared_secret,
+      digestmod=hashlib.sha1,
+    )
 
-      mac.update(nonce.encode('utf8'))
-      mac.update(b"\x00")
-      mac.update(user.encode('utf8'))
-      mac.update(b"\x00")
-      mac.update(password.encode('utf8'))
-      mac.update(b"\x00")
-      mac.update(b"admin" if admin else b"notadmin")
-      if user_type:
-          mac.update(b"\x00")
-          mac.update(user_type.encode('utf8'))
+    mac.update(nonce.encode('utf8'))
+    mac.update(b"\x00")
+    mac.update(user.encode('utf8'))
+    mac.update(b"\x00")
+    mac.update(password.encode('utf8'))
+    mac.update(b"\x00")
+    mac.update(b"admin" if admin else b"notadmin")
+    if user_type:
+        mac.update(b"\x00")
+        mac.update(user_type.encode('utf8'))
 
-      return mac.hexdigest()
+    return mac.hexdigest()
+```
\ No newline at end of file

docs/admin_api/version_api.rst → docs/admin_api/version_api.md

-Version API
-===========
+# Version API
 
 This API returns the running Synapse version and the Python version
 on which Synapse is being run. This is useful when a Synapse instance
 is behind a proxy that does not forward the 'Server' header (which also
 contains Synapse version information).
 
-The api is::
+The api is:
 
-    GET /_synapse/admin/v1/server_version
+```
+GET /_synapse/admin/v1/server_version
+```
 
 It returns a JSON body like the following:
 
-.. code:: json
-
-    {
-        "server_version": "0.99.2rc1 (b=develop, abcdef123)",
-        "python_version": "3.6.8"
-    }
+```json
+{
+    "server_version": "0.99.2rc1 (b=develop, abcdef123)",
+    "python_version": "3.6.8"
+}
+```