Merge pull request #6186 from vector-im/feature/bma/knit_toc

Generate toc in md files using knit

docs/add_threePids.md

@@ -1,5 +1,34 @@
 # Adding and removing ThreePids to an account
 
+<!--- TOC -->
+
+* [Add email](#add-email)
+  * [User enter the email](#user-enter-the-email)
+    * [The email is already added to an account](#the-email-is-already-added-to-an-account)
+    * [The email is free](#the-email-is-free)
+* [User receives an e-mail](#user-receives-an-e-mail)
+  * [User clicks on the link](#user-clicks-on-the-link)
+  * [User returns on Element](#user-returns-on-element)
+  * [User enters his password](#user-enters-his-password)
+    * [The link has not been clicked](#the-link-has-not-been-clicked)
+    * [Wrong password](#wrong-password)
+    * [The link has been clicked and the account password is correct](#the-link-has-been-clicked-and-the-account-password-is-correct)
+* [Remove email](#remove-email)
+  * [User want to remove an email from his account](#user-want-to-remove-an-email-from-his-account)
+    * [Email was not bound to an identity server](#email-was-not-bound-to-an-identity-server)
+    * [Email was bound to an identity server](#email-was-bound-to-an-identity-server)
+* [Add phone number](#add-phone-number)
+    * [The phone number is already added to an account](#the-phone-number-is-already-added-to-an-account)
+    * [The phone number is free](#the-phone-number-is-free)
+* [User receive a text message](#user-receive-a-text-message)
+  * [User enter the code to the app](#user-enter-the-code-to-the-app)
+    * [Wrong code](#wrong-code)
+    * [Correct code](#correct-code)
+* [Remove phone number](#remove-phone-number)
+  * [User wants to remove a phone number from his account](#user-wants-to-remove-a-phone-number-from-his-account)
+
+<!--- END -->
+
 ## Add email
 
 ### User enter the email

docs/analytics.md

@@ -1,5 +1,13 @@
 # Analytics in Element
 
+<!--- TOC -->
+
+* [Solution](#solution)
+* [How to add a new Event](#how-to-add-a-new-event)
+* [Forks of Element](#forks-of-element)
+
+<!--- END -->
+
 ## Solution
 
 Element is using PostHog to send analytics event.

docs/color_migration_guide.md

@@ -1,5 +1,14 @@
 # Color migration
 
+<!--- TOC -->
+
+  * [Changes](#changes)
+  * [Main change for developers](#main-change-for-developers)
+  * [Remaining work](#remaining-work)
+  * [Migration guide](#migration-guide)
+
+<!--- END -->
+
 ### Changes
 
 - use colors defined in https://www.figma.com/file/X4XTH9iS2KGJ2wFKDqkyed/Compound?node-id=557%3A0

docs/design.md

@@ -1,5 +1,31 @@
 # Element Android design
 
+<!--- TOC -->
+
+* [Introduction](#introduction)
+* [How to import from Figma to the Element Android project](#how-to-import-from-figma-to-the-element-android-project)
+  * [Colors](#colors)
+  * [Text](#text)
+  * [Dimension, position and margin](#dimension-position-and-margin)
+  * [Icons](#icons)
+    * [Export drawable from Figma](#export-drawable-from-figma)
+    * [Import in Android Studio](#import-in-android-studio)
+  * [Images](#images)
+* [Figma links](#figma-links)
+  * [Coumpound](#coumpound)
+  * [Login](#login)
+    * [Login v2](#login-v2)
+  * [Room list](#room-list)
+  * [Timeline](#timeline)
+  * [Voice message](#voice-message)
+  * [Room settings](#room-settings)
+  * [VoIP](#voip)
+  * [Presence](#presence)
+  * [Spaces](#spaces)
+  * [List to be continued...](#list-to-be-continued)
+
+<!--- END -->
+
 ## Introduction
 
 Design at element.io is done using Figma - https://www.figma.com

docs/identity_server.md

@@ -1,5 +1,19 @@
 # Identity server
 
+<!--- TOC -->
+
+* [Introduction](#introduction)
+* [Implementation](#implementation)
+* [Related MSCs](#related-mscs)
+* [Steps and requirements](#steps-and-requirements)
+* [Screens](#screens)
+  * [Settings](#settings)
+  * [Discovery screen](#discovery-screen)
+  * [Set identity server screen](#set-identity-server-screen)
+* [Ref:](#ref:)
+
+<!--- END -->
+
 Issue: #607
 PR: #1354
 

docs/integration_tests.md

@@ -1,5 +1,18 @@
 # Integration tests
 
+<!--- TOC -->
+
+* [Pre requirements](#pre-requirements)
+* [Install and run Synapse](#install-and-run-synapse)
+* [Run the test](#run-the-test)
+* [Stop Synapse](#stop-synapse)
+* [Troubleshoot](#troubleshoot)
+  * [Android Emulator does cannot reach the homeserver](#android-emulator-does-cannot-reach-the-homeserver)
+  * [Tests partially run but some fail with "Unable to contact localhost:8080"](#tests-partially-run-but-some-fail-with-"unable-to-contact-localhost:8080")
+  * [virtualenv command fails](#virtualenv-command-fails)
+
+<!--- END -->
+
 Integration tests are useful to ensure that the code works well for any use cases.
 
 They can also be used as sample on how to use the Matrix SDK.

docs/jitsi.md

@@ -1,20 +1,32 @@
 # Jitsi in Element Android
 
+<!--- TOC -->
+
+* [Native Jitsi SDK](#native-jitsi-sdk)
+  * [How to build the Jitsi Meet SDK](#how-to-build-the-jitsi-meet-sdk)
+    * [Jitsi version](#jitsi-version)
+    * [Run the build script](#run-the-build-script)
+    * [Link with the new generated library](#link-with-the-new-generated-library)
+    * [Sanity tests](#sanity-tests)
+    * [Export the build library](#export-the-build-library)
+
+<!--- END -->
+
 Native Jitsi support has been added to Element Android by the PR [#1914](https://github.com/vector-im/element-android/pull/1914). The description of the PR contains some documentation about the behaviour in each possible room configuration.
 
 Also, ensure to have a look on [the documentation from Element Web](https://github.com/vector-im/element-web/blob/develop/docs/jitsi.md)
 
 The official documentation about how to integrate the Jitsi SDK in an Android app is available here: https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-android-sdk.
 
-# Native Jitsi SDK
+## Native Jitsi SDK
 
 The Jitsi SDK is built by ourselves with the flag LIBRE_BUILD, to be able to be integrated on the F-Droid version of Element Android.
 
 The generated maven repository is then host in the project https://github.com/vector-im/jitsi_libre_maven
 
-## How to build the Jitsi Meet SDK
+### How to build the Jitsi Meet SDK
 
-### Jitsi version
+#### Jitsi version
 
 Update the script `./tools/jitsi/build_jisti_libs.sh` with the tag of the project `https://github.com/jitsi/jitsi-meet`.
 
@@ -22,7 +34,7 @@ Latest tag can be found from this page: https://github.com/jitsi/jitsi-meet-rele
 
 Currently we are building the version with the tag `android-sdk-3.10.0`.
 
-### Run the build script
+#### Run the build script
 
 At the root of the Element Android, run the following script:
 
@@ -32,7 +44,7 @@ At the root of the Element Android, run the following script:
 
 It will build the Jitsi Meet Android library and put every generated files in the folder `/tmp/jitsi`
 
-### Link with the new generated library
+#### Link with the new generated library
 
 - Update the file `./build.gradle` to use the previously created local Maven repository. Currently we have this line:
 
@@ -57,7 +69,7 @@ implementation('com.facebook.react:react-native-webrtc:1.92.1-jitsi-9093212@aar'
 - Perform a gradle sync and build the project
 - Perform test
 
-### Sanity tests
+#### Sanity tests
 
 In order to validate that the upgrade of the Jitsi and WebRTC dependency does not break anything, the following sanity tests have to be performed, using two devices:
 - Make 1-1 audio call (so using WebRTC)
@@ -65,7 +77,7 @@ In order to validate that the upgrade of the Jitsi and WebRTC dependency does no
 - Create and join a conference call with audio only (so using Jitsi library). Leave the conference. Join it again.
 - Create and join a conference call with audio and video (so using Jitsi library) Leave the conference. Join it again.
 
-### Export the build library
+#### Export the build library
 
 If all the tests are passed, you can export the generated Jitsi library to our Maven repository.
 
@@ -81,4 +93,4 @@ url "https://github.com/vector-im/jitsi_libre_maven/raw/master/android-sdk-3.10.
 
 - Build the project and perform the sanity tests again.
 
-- Update the file `/CHANGES.md` to notify about the library upgrade, and create a regular PR for project Element Android.
+- Update the file `/CHANGES.md` to notify about the library upgrade, and create a regular PR for project Element Android.

docs/notifications.md

@@ -1,28 +1,33 @@
 This document aims to describe how Element android displays notifications to the end user. It also clarifies notifications and background settings in the app.
 
 # Table of Contents
-1. [Prerequisites Knowledge](#prerequisites-knowledge)
+
-    * [How does a matrix client get a message from a homeserver?](#how-does-a-matrix-client-get-a-message-from-a-homeserver)
+<!--- TOC -->
-    * [How does a mobile app receives push notification?](#how-does-a-mobile-app-receives-push-notification)
+
-    * [Push VS Notification](#push-vs-notification)
+* [Prerequisites Knowledge](#prerequisites-knowledge)
-    * [Push in the matrix federated world](#push-in-the-matrix-federated-world)
+  * [How does a matrix client get a message from a homeserver?](#how-does-a-matrix-client-get-a-message-from-a-homeserver?)
-    * [How does the homeserver know when to notify a client?](#how-does-the-homeserver-know-when-to-notify-a-client)
+  * [How does a mobile app receives push notification](#how-does-a-mobile-app-receives-push-notification)
-    * [Push vs privacy, and mitigation](#push-vs-privacy-and-mitigation)
+  * [Push VS Notification](#push-vs-notification)
-    * [Background processing limitations](#background-processing-limitations)
+  * [Push in the matrix federated world](#push-in-the-matrix-federated-world)
-2. [Element Notification implementations](#element-notification-implementations)
+  * [How does the homeserver know when to notify a client?](#how-does-the-homeserver-know-when-to-notify-a-client?)
-    * [Requirements](#requirements) 
+  * [Push vs privacy, and mitigation](#push-vs-privacy-and-mitigation)
-    * [Foreground sync mode (Gplay & F-Droid)](#foreground-sync-mode-gplay--f-droid)
+  * [Background processing limitations](#background-processing-limitations)
-    * [Push (FCM) received in background](#push-fcm-received-in-background)
+* [Element Notification implementations](#element-notification-implementations)
-    * [FCM Fallback mode](#fcm-fallback-mode)
+  * [Requirements](#requirements)
-    * [F-Droid background Mode](#f-droid-background-mode)
+  * [Foreground sync mode (Gplay and F-Droid)](#foreground-sync-mode-gplay-and-f-droid)
-3. [Application Settings](#application-settings)
+  * [Push (FCM) received in background](#push-fcm-received-in-background)
+  * [FCM Fallback mode](#fcm-fallback-mode)
+  * [F-Droid background Mode](#f-droid-background-mode)
+* [Application Settings](#application-settings)
+
+<!--- END -->
 
 
 First let's start with some prerequisite knowledge
 
-# Prerequisites Knowledge
+## Prerequisites Knowledge
 
-## How does a matrix client get a message from a homeserver?
+### How does a matrix client get a message from a homeserver?
 
 In order to get messages from a homeserver, a matrix client need to perform a ``sync`` operation.
 
@@ -52,7 +57,7 @@ By default, this is 0, so the server will return immediately even if the respons
 
 When the Element Android app is open (i.e in foreground state), the default timeout is 30 seconds, and delay is 0.
 
-## How does a mobile app receives push notification
+### How does a mobile app receives push notification
 
 Push notification is used as a way to wake up a mobile application when some important information is available and should be processed.
 
@@ -69,7 +74,7 @@ De-Googlified devices need to rely on something else in order to stay up to date
 There some cases when devices with google services cannot use FCM (network infrastructure limitations -firewalls-,
  privacy and or independence requirement, source code licence)
 
-## Push VS Notification
+### Push VS Notification
 
 This need some disambiguation, because it is the source of common confusion:
 
@@ -81,7 +86,7 @@ This need some disambiguation, because it is the source of common confusion:
   Notifications are not always triggered by a push (One can display a notification locally triggered by an alarm)
 
 
-## Push in the matrix federated world
+### Push in the matrix federated world
 
 In order to send a push to a mobile, App developers need to have a server that will use the FCM APIs, and these APIs requires authentication!
 This server is called a **Push Gateway** in the matrix world
@@ -122,7 +127,7 @@ Recommended reading:
 * https://matrix.org/docs/spec/client_server/r0.4.0.html#id128
 
 
-## How does the homeserver know when to notify a client?
+### How does the homeserver know when to notify a client?
 
 This is defined by [**push rules**](https://matrix.org/docs/spec/client_server/r0.4.0.html#push-rules-).
 
@@ -140,14 +145,14 @@ Of course, content patterns matching cannot be used for encrypted messages serve
 
 That is why clients are able to **process the push rules client side** to decide what kind of notification should be presented for a given event.
 
-## Push vs privacy, and mitigation
+### Push vs privacy, and mitigation
 
 As seen previously, App developers don't directly send a push to the end user's device, they use a Push Provider as intermediary. So technically this intermediary is able to read the content of what is sent.
 
 App developers usually mitigate this by sending a `silent notification`, that is a notification with no identifiable data, or with an encrypted payload. When the push is received the app can then synchronise to it's server in order to generate a local notification.
 
 
-## Background processing limitations
+### Background processing limitations
 
 A mobile applications process live in a managed word, meaning that its process can be limited (e.g no network access), stopped or killed at almost anytime by the Operating System.
 
@@ -167,15 +172,15 @@ The documentation on this subject is vague, and as per our experiments not alway
 
 It is getting more and more complex to have reliable notifications when FCM is not used.
 
-# Element Notification implementations
+## Element Notification implementations
 
-## Requirements
+### Requirements
 
 Element Android must work with and without FCM.
 * The Element android app published on F-Droid do not rely on FCM (all related dependencies are not present)
 * The Element android app published on google play rely on FCM, with a fallback mode when FCM registration has failed (e.g outdated or missing Google Play Services)
 
-## Foreground sync mode (Gplay & F-Droid)
+### Foreground sync mode (Gplay and F-Droid)
 
 When in foreground, Element performs sync continuously with a timeout value set to 10 seconds (see HttpPooling).
 
@@ -185,7 +190,7 @@ This mode is turned on when the app enters foreground, and off when enters backg
 
 In background, and depending on whether push is available or not, Element will use different methods to perform the syncs (Workers / Alarms / Service)
 
-## Push (FCM) received in background 
+### Push (FCM) received in background 
 
 In order to enable Push, Element must first get a push token from the firebase SDK, then register a pusher with this token on the homeserver.
 
@@ -225,7 +230,7 @@ Upon reception of the FCM push, Element will perform a sync call to the homeserv
 
 Element implements several strategies in these cases (TODO document)
 
-## FCM Fallback mode
+### FCM Fallback mode
 
 It is possible that Element is not able to get a FCM push token.
 Common errors (among several others) that can cause that:
@@ -246,7 +251,7 @@ Usually in this mode, what happen is when you take back your phone in your hand,
 
 The fallback mode is supposed to be a temporary state waiting for the user to fix issues for FCM, or for App Developers that has done a fork to correctly configure their FCM settings.
 
-## F-Droid background Mode
+### F-Droid background Mode
 
 The F-Droid Element flavor has no dependencies to FCM, therefore cannot relies on Push.
 
@@ -266,9 +271,7 @@ That is why on Element F-Droid, the broadcast receiver will acquire a temporary
 
 Note that foreground services require to put a notification informing the user that the app is doing something even if not launched).
 
-
+## Application Settings
-
-# Application Settings
 
 **Notifications > Enable notifications for this account**
 

docs/pull_request.md

@@ -1,5 +1,43 @@
 # Pull requests
 
+<!--- TOC -->
+
+* [Introduction](#introduction)
+* [Who should read this document?](#who-should-read-this-document?)
+* [Submitting PR](#submitting-pr)
+  * [Who can submit pull requests?](#who-can-submit-pull-requests?)
+    * [Humans](#humans)
+      * [Draft PR?](#draft-pr?)
+      * [Base branch](#base-branch)
+      * [PR Review Assignment](#pr-review-assignment)
+      * [PR review time](#pr-review-time)
+      * [Re-request PR review](#re-request-pr-review)
+      * [When create split PR?](#when-create-split-pr?)
+      * [Avoid fixing other unrelated issue in a big PR](#avoid-fixing-other-unrelated-issue-in-a-big-pr)
+    * [Bots](#bots)
+      * [Dependabot](#dependabot)
+      * [Gradle wrapper](#gradle-wrapper)
+      * [Sync analytics plan](#sync-analytics-plan)
+* [Reviewing PR](#reviewing-pr)
+  * [Who can review pull requests?](#who-can-review-pull-requests?)
+  * [What to have in mind when reviewing a PR](#what-to-have-in-mind-when-reviewing-a-pr)
+  * [Rules](#rules)
+    * [Check the form](#check-the-form)
+      * [PR title](#pr-title)
+      * [PR description](#pr-description)
+      * [File change](#file-change)
+      * [Check the commit](#check-the-commit)
+      * [Check the substance](#check-the-substance)
+      * [Make a dedicated meeting to review the PR](#make-a-dedicated-meeting-to-review-the-pr)
+  * [What happen to the issue(s)?](#what-happen-to-the-issues?)
+  * [Merge conflict](#merge-conflict)
+  * [When and who can merge PR](#when-and-who-can-merge-pr)
+    * [Merge type](#merge-type)
+  * [Resolve conversation](#resolve-conversation)
+* [Responsibility](#responsibility)
+
+<!--- END -->
+
 ## Introduction
 
 This document gives some clue about how to efficiently manage Pull Requests (PR). This document is a first draft and may be improved later.

docs/signin.md

@@ -2,6 +2,27 @@
 
 This document describes the flow of signin to a homeserver, and also the flow when user want to reset his password. Examples come from the `matrix.org` homeserver.
 
+<!--- TOC -->
+
+* [Sign in flows](#sign-in-flows)
+  * [Get the flow](#get-the-flow)
+  * [Login with username](#login-with-username)
+    * [Incorrect password](#incorrect-password)
+    * [Correct password:](#correct-password:)
+  * [Login with email](#login-with-email)
+    * [Unknown email](#unknown-email)
+    * [Known email, wrong password](#known-email-wrong-password)
+      * [Known email, correct password](#known-email-correct-password)
+  * [Login with Msisdn](#login-with-msisdn)
+  * [Login with SSO](#login-with-sso)
+* [Reset password](#reset-password)
+  * [Send email](#send-email)
+    * [When the email is not known](#when-the-email-is-not-known)
+    * [When the email is known](#when-the-email-is-known)
+  * [User clicks on the link](#user-clicks-on-the-link)
+
+<!--- END -->
+
 ## Sign in flows
 
 ### Get the flow
@@ -322,4 +343,4 @@ curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds":
 {}
 ```
 
-The password has been changed, and all the existing token are invalidated. User can now login with the new password.
+The password has been changed, and all the existing token are invalidated. User can now login with the new password.

docs/signup.md

@@ -4,6 +4,20 @@ This document describes the flow of registration to a homeserver. Examples come
 
 *Ref*: https://matrix.org/docs/spec/client_server/latest#account-registration-and-management
 
+<!--- TOC -->
+
+* [Sign up flows](#sign-up-flows)
+  * [First step](#first-step)
+  * [Step 1: entering user name and password](#step-1:-entering-user-name-and-password)
+    * [If username already exists](#if-username-already-exists)
+  * [Step 2: entering email](#step-2:-entering-email)
+  * [Step 2 bis: user enters an email](#step-2-bis:-user-enters-an-email)
+  * [Step 3: Accepting T&C](#step-3:-accepting-t&c)
+  * [Step 4: Captcha](#step-4:-captcha)
+  * [Step 5: MSISDN](#step-5:-msisdn)
+
+<!--- END -->
+
 ## Sign up flows
 
 ### First step

docs/ui-tests.md

@@ -10,6 +10,20 @@ Currently the test are covering a small set of application flows:
 	- Self verification via emoji
 	- Self verification via passphrase
 
+<!--- TOC -->
+
+* [Prerequisites:](#prerequisites:)
+* [Run the tests](#run-the-tests)
+  * [From the source code](#from-the-source-code)
+  * [From command line](#from-command-line)
+* [Recipes](#recipes)
+  * [Wait for initial sync](#wait-for-initial-sync)
+  * [Accessing current activity](#accessing-current-activity)
+  * [Interact with other session](#interact-with-other-session)
+  * [Contributing to the UiAllScreensSanityTest](#contributing-to-the-uiallscreenssanitytest)
+
+<!--- END -->
+
 ## Prerequisites:
 
 Out of the box, the tests use one of the homeservers (located at http://localhost:8080) of the "Demo Federation of Homeservers" (https://github.com/matrix-org/synapse#running-a-demo-federation-of-synapses).