Convert docs from reStructuredText to MyST markdown

docs/convert/compare_screenshots.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+
+import subprocess
+import os
+
+output = subprocess.check_output(['find', 'screenshots', '-name', '*_dev.png']).decode('utf8')
+
+for dev in output.splitlines():
+   ref = dev.replace('_dev.png', '_ref.png')
+   if os.path.exists(dev) and os.path.exists(ref):
+      print(dev)
+      cmd = ['compare', '-compose', 'src', dev, ref, dev.replace('_dev.png', '_diff.png')]
+      print(cmd)
+      subprocess.run(cmd)
+   else:
+      print(f'Cannot compare {dev}')

docs/convert/config.yaml

@@ -0,0 +1 @@
+colon_fences: false

docs/convert/conversions.yaml

@@ -0,0 +1 @@
+sphinx.domains.std.Glossary: eval_rst

docs/convert/convert.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+#
+set -e
+# shellcheck disable=SC2044,SC3010
+for f in $(find . -type f -name '*.rst'); do
+    if [[ "$f" == */includes/* ]]; then
+        echo skipping "$f"
+        continue
+    fi
+    rst2myst convert -c convert/conversions.yaml --no-colon-fences "$f"
+    rm -f "$f"
+done

docs/convert/revert.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+
+git checkout src
+git clean src -f

docs/convert/screenshots.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+from selenium import webdriver
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.common.by import By
+import subprocess
+import os.path
+
+def sanitize_name(name):
+    r = ''
+    for c in name:
+        if c.isalpha():
+            r += c
+        else:
+            r += '_'
+    return r
+
+driver = webdriver.Firefox()
+
+output = subprocess.check_output(['find', 'build', '-name', '*.html']).decode('utf8')
+for i, p in enumerate(output.splitlines()):
+    n = os.path.relpath(p, 'build')
+    url_dev = f'http://localhost:3000/{n}'
+    url_ref = f'https://docs.wire.com/{n}'
+    img_basename = sanitize_name(n) + '_' + str(i)
+
+    try:
+        print(f'./screenshots/{i:03}-{img_basename}_dev.png')
+        driver.get(url_dev)
+        driver.get_full_page_screenshot_as_file(f'./screenshots/{i:03}-{img_basename}_dev.png')
+        print(url_ref)
+        driver.get(url_ref)
+        driver.get_full_page_screenshot_as_file(f'./screenshots/{i:03}-{img_basename}_ref.png')
+    except:
+        pass
+
+driver.close()
+
+
+
+# assert "Python" in driver.title
+# elem = driver.find_element(By.NAME, "q")
+# elem.clear()
+# elem.send_keys("pycon")
+# elem.send_keys(Keys.RETURN)
+# assert "No results found." not in driver.page_source
+#

docs/convert/shell.nix

@@ -0,0 +1,17 @@
+{ pkgs ? import <nixpkgs> {} }:
+(pkgs.buildFHSUserEnv {
+  name = "pipzone";
+  targetPkgs = pkgs: (with pkgs; [
+    python3
+    python3Packages.pip
+    python3Packages.virtualenv
+  ]);
+  runScript = "bash";
+}).env
+
+# then
+# virtualenv venv
+# pip install rst-to-myst
+# Fix this bug locally: https://github.com/executablebooks/rst-to-myst/issues/49
+# pip install sphinx-reredirects
+# pip install sphinx-multiversion

docs/src/conf.py

@@ -128,6 +128,5 @@
         "security-responses/log4shell": "2021-12-15_log4shell.html",
         "security-responses/cve-2021-44521": "2022-02-21_cve-2021-44521.html",
         "security-responses/2022-05_website_outage": "2022-05-23_website_outage.html",
-        "how-to/single-sign-on/index": "../../understand/single-sign-on/main.html#setting-up-sso-externally",
-        "how-to/scim/index": "../../understand/single-sign-on/main.html#user-provisioning",
+        "how-to/scim/index": "../../understand/single-sign-on/main.html#user-provisioning"
 }

docs/src/developer/developer/index.md

@@ -0,0 +1,10 @@
+# Developer
+
+```{toctree}
+:caption: 'Contents:'
+:glob: true
+:numbered: true
+:titlesonly: true
+
+**
+```

docs/src/developer/index.rst → docs/src/developer/index.md

@@ -1,19 +1,19 @@
-Notes for developers
-====================
+# Notes for developers
 
-If you are an on-premise operator (administrating your own self-hosted installation of wire-server), you may want to go back to `docs.wire.com <https://docs.wire.com/>`_ and ignore this section of the docs.
+If you are an on-premise operator (administrating your own self-hosted installation of wire-server), you may want to go back to [docs.wire.com](https://docs.wire.com/) and ignore this section of the docs.
 
-If you are a wire end-user, please check out our `support pages <https://support.wire.com/>`_.
+If you are a wire end-user, please check out our [support pages](https://support.wire.com/).
 
 What you need to know as a user of the Wire backend: concepts, features,
 and API. We want to keep these up to date. They could benefit from some
 re-ordering, and they are far from complete, but we hope they will still
 help you.
 
-.. toctree::
-   :titlesonly:
-   :caption: Contents:
-   :glob:
+```{toctree}
+:caption: 'Contents:'
+:glob: true
+:titlesonly: true
 
-   developer/index.rst
-   reference/index.rst
+developer/index.rst
+reference/index.rst
+```

docs/src/developer/reference/index.md

@@ -0,0 +1,10 @@
+# Reference
+
+```{toctree}
+:caption: 'Contents:'
+:glob: true
+:numbered: true
+:titlesonly: true
+
+**
+```

docs/src/developer/reference/spar-braindump.md

@@ -113,7 +113,7 @@ export IDP_ID=...
 
 Copy the new metadata file to one of your spar instances.
 
-Ssh into it.  If you can't, [the sso docs](../../understand/single-sign-on/main.rst) explain how you can create a
+Ssh into it.  If you can't, [the sso docs](../../how-to/single-sign-on/understand/main.rst) explain how you can create a
 bearer token if you have the admin's login credentials.  If you follow
 that approach, you need to replace all mentions of `-H'Z-User ...'`
 with `-H'Authorization: Bearer ...'` in the following, and you won't need

docs/src/how-to/administrate/cassandra.md

@@ -0,0 +1,63 @@
+# Cassandra
+
+```{eval-rst}
+.. include:: includes/intro.rst
+```
+
+This section only covers the bare minimum, for more information, see the [cassandra
+documentation](https://cassandra.apache.org/doc/latest/)
+
+(check-the-health-of-a-cassandra-node)=
+
+## Check the health of a Cassandra node
+
+To check the health of a Cassandra node, run the following command:
+
+```sh
+ssh <ip of cassandra node> /opt/cassandra/bin/nodetool status
+```
+
+or if you are running a newer version of wire-server (altough it should be backwards compatibile)
+
+```sh
+ssh <ip of cassandra node> /opt/cassandra/bin/nodetool -h ::FFFF:127.0.0.1 status
+```
+
+You should see a list of nodes like this:
+
+```sh
+Datacenter: datacenter1
+=======================
+Status=Up/Down
+|/ State=Normal/Leaving/Joining/Moving
+--  Address         Load       Tokens          Owns (effective)   Host ID                                Rack
+UN  192.168.220.13  9.51MiB    256             100.0%             3dba71c8-eea7-4e35-8f35-4386e7944894   rack1
+UN  192.168.220.23  9.53MiB    256             100.0%             3af56f1f-7685-4b5b-b73f-efdaa371e96e   rack1
+UN  192.168.220.33  9.55MiB    256             100.0%             RANDOMLY-MADE-UUID-GOES-INTHISPLACE!   rack1
+```
+
+A `UN` at the begginng of the line, refers to a node that is `Up` and `Normal`.
+
+## How to inspect tables and data manually
+
+```sh
+cqlsh
+# from the cqlsh shell
+describe keyspaces
+use <keyspace>;
+describe tables;
+select * from <tablename> WHERE <primarykey>=<some-value> LIMIT 10;
+```
+
+## How to rolling-restart a cassandra cluster
+
+For maintenance you may need to restart the cluster.
+
+On each server one by one:
+
+1. check your cluster is healthy: `nodetool status` or `nodetool -h ::FFFF:127.0.0.1 status` (in newer versions)
+2. `nodetool drain && systemctl stop cassandra` (to stop accepting writes and flush data to disk; then stop the process)
+3. do any operation you need, if any
+4. Start the cassandra daemon process: `systemctl start cassandra`
+5. Wait for your cluster to be healthy again.
+6. Do the same on the next server.