From e453c3b0fa116d729895b61f37d363bfede55d1a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 May 2021 09:44:11 +0100 Subject: [PATCH 01/25] Setup; add book.toml We seem to include the documentation in our packaging, so perhaps we should include book.toml as well? --- MANIFEST.in | 1 + book.toml | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 book.toml diff --git a/MANIFEST.in b/MANIFEST.in index 25d1cb758e52..0522319c4000 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -40,6 +40,7 @@ exclude mypy.ini exclude sytest-blacklist exclude test_postgresql.sh +include book.toml include pyproject.toml recursive-include changelog.d * diff --git a/book.toml b/book.toml new file mode 100644 index 000000000000..aefcb6a5bd97 --- /dev/null +++ b/book.toml @@ -0,0 +1,26 @@ +# Documentation for possible options in this file is at +# https://rust-lang.github.io/mdBook/format/config.html +[book] +title = "Synapse" +authors = ["The Matrix.org Foundation C.I.C."] +language = "en" +multilingual = false + +# The directory that documentation files are stored in +src = "docs" + +[build] +# Prevent markdown pages from being automatically generated when they're +# linked to in SUMMARY.md +create-missing = false + +[output.html] +# The URL visitors will be directed to when they try to edit a page +# Disabled until https://github.com/rust-lang/mdBook/issues/1543 is fixed +#edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}" + +# The source code URL of the repository +git-repository-url = "https://github.com/matrix-org/synapse" + +# The path that the docs are hosted on +site-url = "/synapse/" \ No newline at end of file From f8f770ab59e65efdb8ee4ae8ee063b22fcc8a127 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 14 May 2021 01:31:22 +0100 Subject: [PATCH 02/25] Add book/ directory to .gitignore This is the default directory that is generated when the docs are built locally. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 295a18b5399a..6b9257b5c95b 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,6 @@ __pycache__/ /docs/build/ /htmlcov /pip-wheel-metadata/ + +# docs +book/ From 035d6961f7e8bbd9068004f1d3fcce3a6c2c78c0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 18:52:18 +0100 Subject: [PATCH 03/25] Add a favicon --- docs/favicon.png | Bin 0 -> 7908 bytes docs/favicon.svg | 58 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 docs/favicon.png create mode 100644 docs/favicon.svg diff --git a/docs/favicon.png b/docs/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..5f18bf641fae401bcfd808e1faa2ecd6dba1d7b5 GIT binary patch literal 7908 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 + + + + + image/svg+xml + + + + + + + + + From 706f64a5d75e72227bf1f930e700f0d19b7adada Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 11 May 2021 23:17:49 +0100 Subject: [PATCH 04/25] Add github actions workflow to deploy docs to gh-pages --- .github/workflows/docs.yaml | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 000000000000..a0eb95b5d0ca --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,34 @@ +name: Deploy the documentation +#on: +# release: +# types: [created] + +on: + push: + branches: + - develop + + workflow_dispatch: + +jobs: + pages: + name: GitHub Pages + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Setup mdbook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: '0.4.8' + + - name: Build the documentatino + run: mdbook build + + - name: Deploy latest documentation + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + keep_files: true + publish_dir: ./book + destination_dir: ./latest \ No newline at end of file From 99e7ffee39878f092423f9110560ebe1f8dd374a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 01:58:51 +0100 Subject: [PATCH 05/25] Organise existing documentation into a tree structure. SUMMARY.md defines the sidebar of the website. We organise existing documentation into a logical structure. We also add a couple of pages which make use of mdbook's file include feature to include existing documentation that typically lives outside of the docs/ directory. We also use it to combine the sample config files into a single page with surrounding contextual info. --- docs/SUMMARY.md | 79 ++++++++++++++++++++++++++++++++++++ docs/welcome_and_overview.md | 4 ++ 2 files changed, 83 insertions(+) create mode 100644 docs/SUMMARY.md create mode 100644 docs/welcome_and_overview.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 000000000000..cc76e1c1c99a --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,79 @@ +# Summary + +- [Introduction](welcome_and_overview.md) +- [Setup]() + - [Installation](setup/installation.md) + - [Using Postgres](postgres.md) + - [Configuring a Reverse Proxy](reverse_proxy.md) + - [Configuring a Turn Server](turn-howto.md) + - [Delegation](delegate.md) +- [Upgrading](upgrading/README.md) + - [Upgrading from pre-Synapse 1.0](MSC1711_certificates_FAQ.md) +- [Usage]() + - [Federation](federate.md) + - [Configuration]() + - [Sample Configuration Files](usage/configuration/sample_config.md) + - [User Authentication]() + - [Single-Sign On]() + - [OpenID Connect](openid.md) + - [SAML]() + - [CAS]() + - [SSO Mapping Providers](sso_mapping_providers.md) + - [Password Auth Providers](password_auth_providers.md) + - [JSON Web Tokens](jwt.md) + - [Registration Captcha](CAPTCHA_SETUP.md) + - [Application Services](application_services.md) + - [Server Notices](server_notices.md) + - [Consent Tracking](consent_tracking.md) + - [URL Previews](url_previews.md) + - [User Directory](user_directory.md) + - [Message Retention Policies](message_retention_policies.md) + - [Pluggable Modules]() + - [Third Party Rules]() + - [Spam Checker](spam_checker.md) + - [Presence Router](presence_router_module.md) + - [Writing a Module]() + - [Workers](workers.md) + - [Using `synctl` with Workers](synctl_workers.md) + - [Systemd](systemd-with-workers/README.md) + - [Administration](usage/administration/README.md) + - [Admin API](usage/administration/admin_api/README.md) + - [Account Validity](admin_api/account_validity.rst) + - [Delete Group](admin_api/delete_group.md) + - [Event Reports](admin_api/event_reports.md) + - [Media](admin_api/media_admin_api.md) + - [Purge History](admin_api/purge_history_api.rst) + - [Purge Rooms](admin_api/purge_room.md) + - [Register Users](admin_api/register_api.rst) + - [Manipulate Room Membership](admin_api/room_membership.md) + - [Rooms](admin_api/rooms.md) + - [Server Notices](admin_api/server_notices.md) + - [Shutdown Room](admin_api/shutdown_room.md) + - [Statistics](admin_api/statistics.md) + - [Users](admin_api/user_admin_api.rst) + - [Server Version](admin_api/version_api.rst) + - [Manhole](manhole.md) + - [Monitoring](metrics-howto.md) + - [Structured Logging](structured_logging.md) + - [Scripts]() +- [Development]() + - [Contributing Guide](development/contributing_guide.md) + - [Code Style](code_style.md) + - [Git Usage](dev/git.md) + - [Testing]() + - [OpenTracing](opentracing.md) + - [Synapse Architecture]() + - [Log Contexts](log_contexts.md) + - [Replication](replication.md) + - [TCP Replication](tcp_replication.md) + - [Feature Documentation]() + - [Single Sign-On]() + - [SAML](dev/saml.md) + - [CAS](dev/cas.md) + - [State Resolution]() + - [The Auth Chain Difference Algorithm](auth_chain_difference_algorithm.md) + - [Media Repository](media_repository.md) + - [Room and User Statistics](room_and_user_statistics.md) + - [Scripts]() +- [Other]() + - [Dependency Deprecation Policy](deprecation_policy.md) \ No newline at end of file diff --git a/docs/welcome_and_overview.md b/docs/welcome_and_overview.md new file mode 100644 index 000000000000..30e75984d1ef --- /dev/null +++ b/docs/welcome_and_overview.md @@ -0,0 +1,4 @@ +# Introduction + +Welcome to the documentation repository for Synapse, the reference +[Matrix](https://matrix.org) homeserver implementation. \ No newline at end of file From 069712e4d1bd4055a857cee5cb27daf093aa29c2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 02:06:33 +0100 Subject: [PATCH 06/25] Add some section pages These pages simply act as a container for other pages, but also serve to provide an introduction and explanation for the pages to come. We can also use it to describe what topics should be covered in the section, to help others organise new documentation pages. --- docs/SUMMARY.md | 14 +++++----- docs/development/contributing_guide.md | 7 +++++ .../feature_documentation/README.md | 12 ++++++++ docs/setup/installation.md | 7 +++++ docs/upgrading/README.md | 7 +++++ docs/usage/administration/README.md | 7 +++++ docs/usage/configuration/README.md | 4 +++ docs/usage/configuration/sample_config.md | 28 +++++++++++++++++++ .../user_authentication/README.md | 15 ++++++++++ 9 files changed, 94 insertions(+), 7 deletions(-) create mode 100644 docs/development/contributing_guide.md create mode 100644 docs/development/feature_documentation/README.md create mode 100644 docs/setup/installation.md create mode 100644 docs/upgrading/README.md create mode 100644 docs/usage/administration/README.md create mode 100644 docs/usage/configuration/README.md create mode 100644 docs/usage/configuration/sample_config.md create mode 100644 docs/usage/configuration/user_authentication/README.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cc76e1c1c99a..e94c84ce271d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,7 +1,7 @@ # Summary - [Introduction](welcome_and_overview.md) -- [Setup]() +- [Setup](setup/README.md) - [Installation](setup/installation.md) - [Using Postgres](postgres.md) - [Configuring a Reverse Proxy](reverse_proxy.md) @@ -9,11 +9,11 @@ - [Delegation](delegate.md) - [Upgrading](upgrading/README.md) - [Upgrading from pre-Synapse 1.0](MSC1711_certificates_FAQ.md) -- [Usage]() +- [Usage](usage/README.md) - [Federation](federate.md) - - [Configuration]() + - [Configuration](usage/configuration/README.md) - [Sample Configuration Files](usage/configuration/sample_config.md) - - [User Authentication]() + - [User Authentication](usage/configuration/user_authentication/README.md) - [Single-Sign On]() - [OpenID Connect](openid.md) - [SAML]() @@ -56,7 +56,7 @@ - [Monitoring](metrics-howto.md) - [Structured Logging](structured_logging.md) - [Scripts]() -- [Development]() +- [Development](development/README.md) - [Contributing Guide](development/contributing_guide.md) - [Code Style](code_style.md) - [Git Usage](dev/git.md) @@ -66,7 +66,7 @@ - [Log Contexts](log_contexts.md) - [Replication](replication.md) - [TCP Replication](tcp_replication.md) - - [Feature Documentation]() + - [Feature Documentation](development/feature_documentation/README.md) - [Single Sign-On]() - [SAML](dev/saml.md) - [CAS](dev/cas.md) @@ -75,5 +75,5 @@ - [Media Repository](media_repository.md) - [Room and User Statistics](room_and_user_statistics.md) - [Scripts]() -- [Other]() +- [Other](other/README.md) - [Dependency Deprecation Policy](deprecation_policy.md) \ No newline at end of file diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md new file mode 100644 index 000000000000..a79bb841c592 --- /dev/null +++ b/docs/development/contributing_guide.md @@ -0,0 +1,7 @@ + +# Contributing + +{{#include ../../CONTRIBUTING.md}} diff --git a/docs/development/feature_documentation/README.md b/docs/development/feature_documentation/README.md new file mode 100644 index 000000000000..271e9cca4c37 --- /dev/null +++ b/docs/development/feature_documentation/README.md @@ -0,0 +1,12 @@ +# Feature Documentation + +This section covers implementation documentation for various features of Synapse. + +If a developer is planning to make a change to a feature of Synapse, it can be useful for +general documentation of how that feature is implemented to be available. This saves the +developer time in place of needing to understand how the feature works by reading the +code. + +Documentation that would be more useful for the perspective of a sysadmin, rather than +a developer who's intended to change to code, should instead be placed in +[Usage](../../usage/). \ No newline at end of file diff --git a/docs/setup/installation.md b/docs/setup/installation.md new file mode 100644 index 000000000000..8bb1cffd3d67 --- /dev/null +++ b/docs/setup/installation.md @@ -0,0 +1,7 @@ + +{{#include ../../INSTALL.md}} \ No newline at end of file diff --git a/docs/upgrading/README.md b/docs/upgrading/README.md new file mode 100644 index 000000000000..258e58cf1532 --- /dev/null +++ b/docs/upgrading/README.md @@ -0,0 +1,7 @@ + +{{#include ../../UPGRADE.rst}} \ No newline at end of file diff --git a/docs/usage/administration/README.md b/docs/usage/administration/README.md new file mode 100644 index 000000000000..e1e57546ab6b --- /dev/null +++ b/docs/usage/administration/README.md @@ -0,0 +1,7 @@ +# Administration + +This section contains information on managing your Synapse homeserver. This includes: + +* Managing users, rooms and media via the Admin API. +* Setting up metrics and monitoring to give you insight into your homeserver's health. +* Configuring structured logging. \ No newline at end of file diff --git a/docs/usage/configuration/README.md b/docs/usage/configuration/README.md new file mode 100644 index 000000000000..7d3f586da335 --- /dev/null +++ b/docs/usage/configuration/README.md @@ -0,0 +1,4 @@ +# Configuration + +This section contains information on tweaking Synapse via the various options in the configuration file. A configuration +file should have been generated when you [installed Synapse](../setup/installation.html). \ No newline at end of file diff --git a/docs/usage/configuration/sample_config.md b/docs/usage/configuration/sample_config.md new file mode 100644 index 000000000000..f826de8b8518 --- /dev/null +++ b/docs/usage/configuration/sample_config.md @@ -0,0 +1,28 @@ +# Sample Configuration Files + +## Homeserver Config + +Below is a sample homeserver configuration file. The homeserver configuration file +can be tweaked to change the behaviour of your homeserver. A restart of the server is +generally required to apply any changes made to this file. + +Note that the contents below are *not* intended to be copied and used as the basis for +a real homeserver.yaml. Instead, if you are starting from scratch, please generate +a fresh config using Synapse by following the instructions in +[Installation](../../setup/installation.md). + +A sample logging config file is provided in [the next section](#logging-config). + + +```yaml +{{#include ../../sample_config.yaml}} +``` + +## Logging Config + +Below is a sample logging configuration file. This file controls how your homeserver +will output logs. + +```yaml +{{#include ../../sample_log_config.yaml}} +``` diff --git a/docs/usage/configuration/user_authentication/README.md b/docs/usage/configuration/user_authentication/README.md new file mode 100644 index 000000000000..087ae053cf61 --- /dev/null +++ b/docs/usage/configuration/user_authentication/README.md @@ -0,0 +1,15 @@ +# User Authentication + +Synapse supports multiple methods of authenticating users, either out-of-the-box or through custom pluggable +authentication modules. + +Included in Synapse is support for authenticating users via: + +* A username and password. +* An email address and password. +* Single Sign-On through the SAML, Open ID Connect or CAS protocols. +* JSON Web Tokens. +* An administrator's shared secret. + +Synapse can additionally be extended to support custom authentication schemes through optional "password auth provider" +modules. \ No newline at end of file From db469870a94029974cd8635bddd03b7def3cadf5 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 02:12:35 +0100 Subject: [PATCH 07/25] Add a table of contents plugin This allows for displaying a nifty auto-scrolling table of contents pane to the right of the current page of documentation. This is especially useful when viewing long documents such as the installation instructions. --- book.toml | 8 +- docs/website_files/README.md | 20 ++ docs/website_files/table-of-contents.css | 42 +++ docs/website_files/table-of-contents.js | 134 ++++++++++ docs/website_files/theme/index.hbs | 312 +++++++++++++++++++++++ 5 files changed, 515 insertions(+), 1 deletion(-) create mode 100644 docs/website_files/README.md create mode 100644 docs/website_files/table-of-contents.css create mode 100644 docs/website_files/table-of-contents.js create mode 100644 docs/website_files/theme/index.hbs diff --git a/book.toml b/book.toml index aefcb6a5bd97..7255bf83721e 100644 --- a/book.toml +++ b/book.toml @@ -23,4 +23,10 @@ create-missing = false git-repository-url = "https://github.com/matrix-org/synapse" # The path that the docs are hosted on -site-url = "/synapse/" \ No newline at end of file +site-url = "/synapse/" + +# Additional HTML, JS, CSS that's injected into each page of the book. +# More information is available in docs/website_files/README.md +additional-css = ["docs/website_files/table-of-contents.css"] +additional-js = ["docs/website_files/table-of-contents.js"] +theme = "docs/website_files/theme" \ No newline at end of file diff --git a/docs/website_files/README.md b/docs/website_files/README.md new file mode 100644 index 000000000000..acf73350d670 --- /dev/null +++ b/docs/website_files/README.md @@ -0,0 +1,20 @@ +# Documentation Website Files and Assets + +This directory contains extra files for modifying the look and functionality of +[mdbook](https://github.com/rust-lang/mdBook), the documentation software that's +used to generate Synapse's documentation website. + +The configuration options in the `output.html` section of [book.toml](../../book.toml) +point to additional JS/CSS in this directory that are added on each page load. In +addition, the `theme` directory contains files that overwrite their counterparts in +each of the default themes included with mdbook. + +Currently we use these files to generate a floating Table of Contents page. +The code for which was partially taken from +[JorelAli/mdBook-pagetoc](https://github.com/JorelAli/mdBook-pagetoc/) +before being modified such that it scrolls with the content of the page. + +More information can be found in mdbook's official documentation for +[injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html) +and +[customising the default themes](https://rust-lang.github.io/mdBook/format/theme/index.html). \ No newline at end of file diff --git a/docs/website_files/table-of-contents.css b/docs/website_files/table-of-contents.css new file mode 100644 index 000000000000..d16bb3b9886b --- /dev/null +++ b/docs/website_files/table-of-contents.css @@ -0,0 +1,42 @@ +@media only screen and (max-width:1439px) { + .sidetoc { + display: none; + } +} + +@media only screen and (min-width:1440px) { + main { + position: relative; + margin-left: 100px !important; + } + .sidetoc { + margin-left: auto; + margin-right: auto; + left: calc(100% + (var(--content-max-width))/4 - 140px); + position: absolute; + text-align: right; + } + .pagetoc { + position: fixed; + width: 250px; + overflow: auto; + right: 20px; + height: calc(100% - var(--menu-bar-height)); + } + .pagetoc a { + color: var(--fg) !important; + display: block; + padding: 5px 15px 5px 10px; + text-align: left; + text-decoration: none; + } + .pagetoc a:hover, + .pagetoc a.active { + background: var(--sidebar-bg) !important; + color: var(--sidebar-fg) !important; + } + .pagetoc .active { + background: var(--sidebar-bg); + color: var(--sidebar-fg); + } +} diff --git a/docs/website_files/table-of-contents.js b/docs/website_files/table-of-contents.js new file mode 100644 index 000000000000..0de5960b22b1 --- /dev/null +++ b/docs/website_files/table-of-contents.js @@ -0,0 +1,134 @@ +const getPageToc = () => document.getElementsByClassName('pagetoc')[0]; + +const pageToc = getPageToc(); +const pageTocChildren = [...pageToc.children]; +const headers = [...document.getElementsByClassName('header')]; + + +// Select highlighted item in ToC when clicking an item +pageTocChildren.forEach(child => { + child.addEventHandler('click', () => { + pageTocChildren.forEach(child => { + child.classList.remove('active'); + }); + child.classList.add('active'); + }); +}); + + +/** + * Test whether a node is in the viewport + */ +function isInViewport(node) { + const rect = node.getBoundingClientRect(); + return rect.top >= 0 && rect.left >= 0 && rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && rect.right <= (window.innerWidth || document.documentElement.clientWidth); +} + + +/** + * Set a new ToC entry. + * Clear any previously highlighted ToC items, set the new one, + * and adjust the ToC scroll position. + */ +function setTocEntry() { + let activeEntry; + const pageTocChildren = [...getPageToc().children]; + + // Calculate which header is the current one at the top of screen + headers.forEach(header => { + if (window.pageYOffset >= header.offsetTop) { + activeEntry = header; + } + }); + + // Update selected item in ToC when scrolling + pageTocChildren.forEach(child => { + if (activeEntry.href.localeCompare(child.href) === 0) { + child.classList.add('active'); + } else { + child.classList.remove('active'); + } + }); + + let tocEntryForLocation = document.querySelector(`nav a[href="${activeEntry.href}"]`); + if (tocEntryForLocation) { + const headingForLocation = document.querySelector(activeEntry.hash); + if (headingForLocation && isInViewport(headingForLocation)) { + // Update ToC scroll + const nav = getPageToc(); + const content = document.querySelector('html'); + if (content.scrollTop !== 0) { + nav.scrollTo({ + top: tocEntryForLocation.offsetTop - 100, + left: 0, + behavior: 'smooth', + }); + } else { + nav.scrollTop = 0; + } + } + } +} + + +/** + * Populate sidebar on load + */ +window.addEventListener('load', () => { + // Only create table of contents if there is more than one header on the page + if (headers.length <= 1) { + return; + } + + // Create an entry in the page table of contents for each header in the document + headers.forEach((header, index) => { + const link = document.createElement('a'); + + // Indent shows hierarchy + let indent = '0px'; + switch (header.parentElement.tagName) { + case 'H1': + indent = '5px'; + break; + case 'H2': + indent = '20px'; + break; + case 'H3': + indent = '30px'; + break; + case 'H4': + indent = '40px'; + break; + case 'H5': + indent = '50px'; + break; + case 'H6': + indent = '60px'; + break; + default: + break; + } + + let tocEntry; + if (index == 0) { + // Create a bolded title for the first element + tocEntry = document.createElement("strong"); + tocEntry.innerHTML = header.text; + } else { + // All other elements are non-bold + tocEntry = document.createTextNode(header.text); + } + link.appendChild(tocEntry); + + link.style.paddingLeft = indent; + link.href = header.href; + pageToc.appendChild(link); + }); + setTocEntry.call(); +}); + + +// Handle active headers on scroll, if there is more than one header on the page +if (headers.length > 1) { + window.addEventListener('scroll', setTocEntry); +} diff --git a/docs/website_files/theme/index.hbs b/docs/website_files/theme/index.hbs new file mode 100644 index 000000000000..3b7a5b616353 --- /dev/null +++ b/docs/website_files/theme/index.hbs @@ -0,0 +1,312 @@ + + + + + + {{ title }} + {{#if is_print }} + + {{/if}} + {{#if base_url}} + + {{/if}} + + + + {{> head}} + + + + + + + {{#if favicon_svg}} + + {{/if}} + {{#if favicon_png}} + + {{/if}} + + + + {{#if print_enable}} + + {{/if}} + + + + {{#if copy_fonts}} + + {{/if}} + + + + + + + + {{#each additional_css}} + + {{/each}} + + {{#if mathjax_support}} + + + {{/if}} + + + + + + + + + + + + + + + + +
+ +
+ {{> header}} + + + + {{#if search_enabled}} + + {{/if}} + + + + +
+
+ +
+ +
+ + {{{ content }}} +
+ + +
+
+ + + +
+ + {{#if livereload}} + + + {{/if}} + + {{#if google_analytics}} + + + {{/if}} + + {{#if playground_line_numbers}} + + {{/if}} + + {{#if playground_copyable}} + + {{/if}} + + {{#if playground_js}} + + + + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + {{#each additional_js}} + + {{/each}} + + {{#if is_print}} + {{#if mathjax_support}} + + {{else}} + + {{/if}} + {{/if}} + + + \ No newline at end of file From 3f9f35d0c3c3dd97ea0252f3bb5301b647487bc1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 02:13:48 +0100 Subject: [PATCH 08/25] Remove chapter navigation buttons on desktop As they interfere with the table of contents, and aren't really needed on desktop UI. Buttons are still kept for mobile. --- book.toml | 2 +- docs/website_files/remove-nav-buttons.css | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/website_files/remove-nav-buttons.css diff --git a/book.toml b/book.toml index 7255bf83721e..b21b6475263c 100644 --- a/book.toml +++ b/book.toml @@ -27,6 +27,6 @@ site-url = "/synapse/" # Additional HTML, JS, CSS that's injected into each page of the book. # More information is available in docs/website_files/README.md -additional-css = ["docs/website_files/table-of-contents.css"] +additional-css = ["docs/website_files/table-of-contents.css", "docs/website_files/remove-nav-buttons.css"] additional-js = ["docs/website_files/table-of-contents.js"] theme = "docs/website_files/theme" \ No newline at end of file diff --git a/docs/website_files/remove-nav-buttons.css b/docs/website_files/remove-nav-buttons.css new file mode 100644 index 000000000000..4b280794ea15 --- /dev/null +++ b/docs/website_files/remove-nav-buttons.css @@ -0,0 +1,8 @@ +/* Remove the prev, next chapter buttons as they interfere with the + * table of contents. + * Note that the table of contents only appears on desktop, thus we + * only remove the desktop (wide) chapter buttons. + */ +.nav-wide-wrapper { + display: none +} \ No newline at end of file From 3712044b9f1aad6cf20157cfe58a468faf1a2a8c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 17:50:06 +0100 Subject: [PATCH 09/25] Update docs/README.md with information on the site and how to build it --- docs/README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 68 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3c6ea48c66bb..37d70497ed59 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,72 @@ # Synapse Documentation -This directory contains documentation specific to the `synapse` homeserver. +**The documentation is currently hosted [here](https://matrix-org.github.com/synapse).** +Please update any links to point to the new website instead. -All matrix-generic documentation now lives in its own project, located at [matrix-org/matrix-doc](https://github.com/matrix-org/matrix-doc) +## About -(Note: some items here may be moved to [matrix-org/matrix-doc](https://github.com/matrix-org/matrix-doc) at some point in the future.) +This directory currently holds a series of markdown files documenting how to install, use +and develop Synapse, the reference Matrix homeserver. The documentation is readable directly +from this repository, but it is recommended to instead browse through the +[website](https://matrix-org.github.com/synapse) for easier discoverability. + +## Adding to the documentation + +Most of the documentation currently exists as top-level files, as when organising them into +a structured website, these files were kept in place so that existing links would not break. +The rest of the documentation is stored in folders, such as `setup`, `usage`, and `development` +etc. **All new documentation files should be placed in structured folders.** For example: + +To create a new user-facing documentation page about a new Single Sign-On protocol named +"MyCoolProtocol", one should create a new file with a relevant name, such as "my_cool_protocol.md". +This file might fit into the documentation structure at: + +- Usage + - Configuration + - User Authentication + - Single Sign-On + - **My Cool Protocol** + +Given that, one would place the new file under +`usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md`. + +Note that the structure of the documentation (and thus the left sidebar on the website) is determined +by the list in [SUMMARY.md](SUMMARY.md). The final thing to do when adding a new page is to add a new +line linking to the new documentation file: + +```markdown +- [My Cool Protocol](usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md) +``` + +## Building the documentation + +The documentation is built with [mdbook](https://rust-lang.github.io/mdBook/), and the outline of the +documentation is determined by the structure of [SUMMARY.md](SUMMARY.md). + +First, [get mdbook](https://github.com/rust-lang/mdBook#installation). Then, **from the root of the repository**, +build the documentation with: + +```sh +mdbook build +``` + +The rendered contents will be outputted to a new `book/` directory at the root of the repository. You can +browse the book by opening `book/index.html` in a web browser. + +You can also have mdbook host the docs on a local webserver with hot-reload functionality via: + +```sh +mdbook serve +``` + +The URL at which the docs can be viewed at will be logged. + +## Configuration and theming + +The look and behaviour of the website is configured by the [book.toml](../book.toml) file +at the root of the repository. See +[mdbook's documentation on configuration](https://rust-lang.github.io/mdBook/format/config.html) +for available options. + +The site can be themed and additionally extended with extra UI and features. See +[website_files/README.md](website_files/README.md) for details. From fe65330860444f3235addacfeb05cf8ed5a94bd1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 18:25:35 +0100 Subject: [PATCH 10/25] Update oft-linked to admin_api directory with info about the new site I also moved the information about how to get an admin access token to the "Admin API" chapter of the docs (and lightly spruced it up + did RST -> MD). --- docs/admin_api/README.rst | 30 +++++-------------- docs/usage/administration/admin_api/README.md | 28 +++++++++++++++++ 2 files changed, 36 insertions(+), 22 deletions(-) create mode 100644 docs/usage/administration/admin_api/README.md diff --git a/docs/admin_api/README.rst b/docs/admin_api/README.rst index 9587bee0ce5f..37cee87d32e0 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 `_. +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 " `` +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 `_. diff --git a/docs/usage/administration/admin_api/README.md b/docs/usage/administration/admin_api/README.md new file mode 100644 index 000000000000..53829741ddaa --- /dev/null +++ b/docs/usage/administration/admin_api/README.md @@ -0,0 +1,28 @@ +# The Admin API + +## Authenticate 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.: + +```sql +UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'; +``` + +A new server admin user can also be created using the +[register_new_matrix_user](../../../../scripts/register_new_matrix_user) script. + +Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings. + +## Making an Admin API request +Once you have your `access_token`, you will need to authenticate each request to an Admin API endpoint by +providing the token as either a query parameter or a request header. To add it as a request header in cURL: + +```sh +curl --header "Authorization: Bearer " +``` + +For more details on access tokens in Matrix, please refer to the complete +[matrix spec documentation](https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens). From b4bf418e6bafd2881a04efcb2f6393df746b3714 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 26 May 2021 19:29:21 +0100 Subject: [PATCH 11/25] Refine the sidebar: switch to headers without labels This just ends up looking much cleaner. Also includes some updates to the description of what each custom JS/CSS file does. --- book.toml | 12 ++++++++++-- docs/SUMMARY.md | 19 +++++++++++++------ docs/website_files/README.md | 16 +++++++++++++--- docs/website_files/indent-section-headers.css | 7 +++++++ 4 files changed, 43 insertions(+), 11 deletions(-) create mode 100644 docs/website_files/indent-section-headers.css diff --git a/book.toml b/book.toml index b21b6475263c..8d72082c881f 100644 --- a/book.toml +++ b/book.toml @@ -19,6 +19,10 @@ create-missing = false # Disabled until https://github.com/rust-lang/mdBook/issues/1543 is fixed #edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}" +# Remove the numbers that appear before each item in the sidebar, as they can +# get quite messy as we nest deeper +no-section-label = true + # The source code URL of the repository git-repository-url = "https://github.com/matrix-org/synapse" @@ -26,7 +30,11 @@ git-repository-url = "https://github.com/matrix-org/synapse" site-url = "/synapse/" # Additional HTML, JS, CSS that's injected into each page of the book. -# More information is available in docs/website_files/README.md -additional-css = ["docs/website_files/table-of-contents.css", "docs/website_files/remove-nav-buttons.css"] +# More information available in docs/website_files/README.md +additional-css = [ + "docs/website_files/table-of-contents.css", + "docs/website_files/remove-nav-buttons.css", + "docs/website_files/indent-section-headers.css", +] additional-js = ["docs/website_files/table-of-contents.js"] theme = "docs/website_files/theme" \ No newline at end of file diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e94c84ce271d..a60161ba724b 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,15 +1,20 @@ # Summary -- [Introduction](welcome_and_overview.md) -- [Setup](setup/README.md) +# Introduction +- [Welcome and Overview](welcome_and_overview.md) + +# Setup - [Installation](setup/installation.md) - [Using Postgres](postgres.md) - [Configuring a Reverse Proxy](reverse_proxy.md) - [Configuring a Turn Server](turn-howto.md) - [Delegation](delegate.md) -- [Upgrading](upgrading/README.md) + +# Upgrading + - [Upgrading between Synapse Versions](upgrading/README.md) - [Upgrading from pre-Synapse 1.0](MSC1711_certificates_FAQ.md) -- [Usage](usage/README.md) + +# Usage - [Federation](federate.md) - [Configuration](usage/configuration/README.md) - [Sample Configuration Files](usage/configuration/sample_config.md) @@ -56,7 +61,8 @@ - [Monitoring](metrics-howto.md) - [Structured Logging](structured_logging.md) - [Scripts]() -- [Development](development/README.md) + +# Development - [Contributing Guide](development/contributing_guide.md) - [Code Style](code_style.md) - [Git Usage](dev/git.md) @@ -75,5 +81,6 @@ - [Media Repository](media_repository.md) - [Room and User Statistics](room_and_user_statistics.md) - [Scripts]() -- [Other](other/README.md) + +# Other - [Dependency Deprecation Policy](deprecation_policy.md) \ No newline at end of file diff --git a/docs/website_files/README.md b/docs/website_files/README.md index acf73350d670..04d191479bfe 100644 --- a/docs/website_files/README.md +++ b/docs/website_files/README.md @@ -9,10 +9,20 @@ point to additional JS/CSS in this directory that are added on each page load. I addition, the `theme` directory contains files that overwrite their counterparts in each of the default themes included with mdbook. -Currently we use these files to generate a floating Table of Contents page. -The code for which was partially taken from +Currently we use these files to generate a floating Table of Contents panel. The code for +which was partially taken from [JorelAli/mdBook-pagetoc](https://github.com/JorelAli/mdBook-pagetoc/) -before being modified such that it scrolls with the content of the page. +before being modified such that it scrolls with the content of the page. This is handled +by the `table-of-contents.js/css` files. The table of contents panel only appears on pages +that have more than one header, as well as only appearing on desktop-sized monitors. + +We remove the navigation arrows which typically appear on the left and right side of the +screen on desktop as they interfere with the table of contents. This is handled by +the `remove-nav-buttons.css` file. + +Finally, we also stylise the chapter titles in the left sidebar by indenting them +slightly so that they are more visually distinguishable from the section headers +(the bold titles). This is done through the `indent-section-headers.css` file. More information can be found in mdbook's official documentation for [injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html) diff --git a/docs/website_files/indent-section-headers.css b/docs/website_files/indent-section-headers.css new file mode 100644 index 000000000000..f9b3c82ca68c --- /dev/null +++ b/docs/website_files/indent-section-headers.css @@ -0,0 +1,7 @@ +/* + * Indents each chapter title in the left sidebar so that they aren't + * at the same level as the section headers. + */ +.chapter-item { + margin-left: 1em; +} \ No newline at end of file From c6e5eafd4288ecf22206456c11126105f54678cc Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 27 May 2021 19:42:56 +0100 Subject: [PATCH 12/25] Changelog --- changelog.d/10086.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/10086.doc diff --git a/changelog.d/10086.doc b/changelog.d/10086.doc new file mode 100644 index 000000000000..2200579012db --- /dev/null +++ b/changelog.d/10086.doc @@ -0,0 +1 @@ +Add initial infrastructure for rendering Synapse documentation with mdbook. From 8d774a4c444447754f9eeace3221a239bd418f68 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 28 May 2021 11:22:30 +0100 Subject: [PATCH 13/25] Apply suggestions from code review Co-authored-by: Dan Callahan Co-authored-by: Patrick Cloke --- .github/workflows/docs.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index a0eb95b5d0ca..de568415f496 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,17 +18,17 @@ jobs: - uses: actions/checkout@v2 - name: Setup mdbook - uses: peaceiris/actions-mdbook@v1 + uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14 with: mdbook-version: '0.4.8' - - name: Build the documentatino + - name: Build the documentation run: mdbook build - name: Deploy latest documentation - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0 with: github_token: ${{ secrets.GITHUB_TOKEN }} keep_files: true publish_dir: ./book - destination_dir: ./latest \ No newline at end of file + destination_dir: ./latest From e9ba348cbd9f3cad29dbf22dfb407d8c8a97d49f Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 28 May 2021 11:31:00 +0100 Subject: [PATCH 14/25] Apply suggestions from code review Co-authored-by: Patrick Cloke --- docs/development/contributing_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md index a79bb841c592..ddf088712393 100644 --- a/docs/development/contributing_guide.md +++ b/docs/development/contributing_guide.md @@ -1,5 +1,5 @@ # Contributing From 14cb114a2f9feafdc8460cbb40a839103902c949 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 28 May 2021 11:31:27 +0100 Subject: [PATCH 15/25] Remove comments in workflow, latest -> develop --- .github/workflows/docs.yaml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index de568415f496..29f92b9765c4 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -1,7 +1,4 @@ name: Deploy the documentation -#on: -# release: -# types: [created] on: push: @@ -31,4 +28,4 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} keep_files: true publish_dir: ./book - destination_dir: ./latest + destination_dir: ./develop From b6adbd7fad4bc0be146e33277d887855b6b32ee2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 28 May 2021 12:29:39 +0100 Subject: [PATCH 16/25] Split out homeserver and logging sample config files --- docs/SUMMARY.md | 3 ++- ...ple_config.md => homeserver_sample_config.md} | 16 +--------------- .../usage/configuration/logging_sample_config.md | 14 ++++++++++++++ 3 files changed, 17 insertions(+), 16 deletions(-) rename docs/usage/configuration/{sample_config.md => homeserver_sample_config.md} (64%) create mode 100644 docs/usage/configuration/logging_sample_config.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index a60161ba724b..ea8cf3a10da2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -17,7 +17,8 @@ # Usage - [Federation](federate.md) - [Configuration](usage/configuration/README.md) - - [Sample Configuration Files](usage/configuration/sample_config.md) + - [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md) + - [Logging Sample Config File](usage/configuration/logging_sample_config.md) - [User Authentication](usage/configuration/user_authentication/README.md) - [Single-Sign On]() - [OpenID Connect](openid.md) diff --git a/docs/usage/configuration/sample_config.md b/docs/usage/configuration/homeserver_sample_config.md similarity index 64% rename from docs/usage/configuration/sample_config.md rename to docs/usage/configuration/homeserver_sample_config.md index f826de8b8518..11e806998d88 100644 --- a/docs/usage/configuration/sample_config.md +++ b/docs/usage/configuration/homeserver_sample_config.md @@ -1,6 +1,4 @@ -# Sample Configuration Files - -## Homeserver Config +# Homeserver Sample Configuration File Below is a sample homeserver configuration file. The homeserver configuration file can be tweaked to change the behaviour of your homeserver. A restart of the server is @@ -11,18 +9,6 @@ a real homeserver.yaml. Instead, if you are starting from scratch, please genera a fresh config using Synapse by following the instructions in [Installation](../../setup/installation.md). -A sample logging config file is provided in [the next section](#logging-config). - - ```yaml {{#include ../../sample_config.yaml}} ``` - -## Logging Config - -Below is a sample logging configuration file. This file controls how your homeserver -will output logs. - -```yaml -{{#include ../../sample_log_config.yaml}} -``` diff --git a/docs/usage/configuration/logging_sample_config.md b/docs/usage/configuration/logging_sample_config.md new file mode 100644 index 000000000000..4c4bc6fc1639 --- /dev/null +++ b/docs/usage/configuration/logging_sample_config.md @@ -0,0 +1,14 @@ +# Logging Sample Configuration File + +Below is a sample logging configuration file. This file can be tweaked to control how your +homeserver will output logs. A restart of the server is generally required to apply any +changes made to this file. + +Note that the contents below are *not* intended to be copied and used as the basis for +a real homeserver.yaml. Instead, if you are starting from scratch, please generate +a fresh config using Synapse by following the instructions in +[Installation](../../setup/installation.md). + +```yaml +{{#include ../../sample_log_config.yaml}} +``__` \ No newline at end of file From 2568e5b10969075e5e643442280a392c9ba9c1ee Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 1 Jun 2021 18:24:13 +0100 Subject: [PATCH 17/25] Move structured logging up next to the logging configuration chapter --- docs/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ea8cf3a10da2..17374b7f2555 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -19,6 +19,7 @@ - [Configuration](usage/configuration/README.md) - [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md) - [Logging Sample Config File](usage/configuration/logging_sample_config.md) + - [Structured Logging](structured_logging.md) - [User Authentication](usage/configuration/user_authentication/README.md) - [Single-Sign On]() - [OpenID Connect](openid.md) @@ -60,7 +61,6 @@ - [Server Version](admin_api/version_api.rst) - [Manhole](manhole.md) - [Monitoring](metrics-howto.md) - - [Structured Logging](structured_logging.md) - [Scripts]() # Development From 9157b8e631317a213c8680aa0e9c4cfd5ceedadb Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 1 Jun 2021 18:36:23 +0100 Subject: [PATCH 18/25] Don't link to register_new_matrix_user --- docs/usage/administration/admin_api/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/usage/administration/admin_api/README.md b/docs/usage/administration/admin_api/README.md index 53829741ddaa..2fca96f8be4e 100644 --- a/docs/usage/administration/admin_api/README.md +++ b/docs/usage/administration/admin_api/README.md @@ -11,8 +11,9 @@ A user can be marked as a server admin by updating the database directly, e.g.: UPDATE users SET admin = 1 WHERE name = '@foo:bar.com'; ``` -A new server admin user can also be created using the -[register_new_matrix_user](../../../../scripts/register_new_matrix_user) script. +A new server admin user can also be created using the `register_new_matrix_user` +command. This is a script that is located in the `scripts/` directory, or possibly +already on your `$PATH` depending on how Synapse was installed. Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings. From 92c514f7b45ec0a8c27597825f32be7306f0e86b Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 1 Jun 2021 18:35:51 +0100 Subject: [PATCH 19/25] Update docs/usage/configuration/README.md Co-authored-by: Patrick Cloke --- docs/usage/configuration/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/configuration/README.md b/docs/usage/configuration/README.md index 7d3f586da335..41d41167c680 100644 --- a/docs/usage/configuration/README.md +++ b/docs/usage/configuration/README.md @@ -1,4 +1,4 @@ # Configuration This section contains information on tweaking Synapse via the various options in the configuration file. A configuration -file should have been generated when you [installed Synapse](../setup/installation.html). \ No newline at end of file +file should have been generated when you [installed Synapse](../../setup/installation.html). From 170fed8e1df46aeac6934215e9f1f749a710a6d3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 3 Jun 2021 14:16:01 +0100 Subject: [PATCH 20/25] Switch admin_api SUMMARY entries to their markdown versions; fix links to README --- docs/SUMMARY.md | 10 ++++---- docs/admin_api/delete_group.md | 2 +- docs/admin_api/event_reports.md | 4 +-- docs/admin_api/media_admin_api.md | 4 +-- docs/admin_api/purge_history_api.md | 2 +- docs/admin_api/room_membership.md | 2 +- docs/admin_api/rooms.md | 2 +- docs/admin_api/statistics.md | 2 +- docs/admin_api/user_admin_api.md | 40 ++++++++++++++--------------- 9 files changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 17374b7f2555..19c846bf214c 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -45,20 +45,20 @@ - [Systemd](systemd-with-workers/README.md) - [Administration](usage/administration/README.md) - [Admin API](usage/administration/admin_api/README.md) - - [Account Validity](admin_api/account_validity.rst) + - [Account Validity](admin_api/account_validity.md) - [Delete Group](admin_api/delete_group.md) - [Event Reports](admin_api/event_reports.md) - [Media](admin_api/media_admin_api.md) - - [Purge History](admin_api/purge_history_api.rst) + - [Purge History](admin_api/purge_history_api.md) - [Purge Rooms](admin_api/purge_room.md) - - [Register Users](admin_api/register_api.rst) + - [Register Users](admin_api/register_api.md) - [Manipulate Room Membership](admin_api/room_membership.md) - [Rooms](admin_api/rooms.md) - [Server Notices](admin_api/server_notices.md) - [Shutdown Room](admin_api/shutdown_room.md) - [Statistics](admin_api/statistics.md) - - [Users](admin_api/user_admin_api.rst) - - [Server Version](admin_api/version_api.rst) + - [Users](admin_api/user_admin_api.md) + - [Server Version](admin_api/version_api.md) - [Manhole](manhole.md) - [Monitoring](metrics-howto.md) - [Scripts]() diff --git a/docs/admin_api/delete_group.md b/docs/admin_api/delete_group.md index c061678e7518..9c335ff759a5 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/ ``` 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 bfec06f75504..186139185e5d 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/ ``` 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 7709f3d8c740..9ab526988154 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//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 44971acd917c..25decc3e6107 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/[/] ``` 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 b6746ff5e413..ed40366099af 100644 --- a/docs/admin_api/room_membership.md +++ b/docs/admin_api/room_membership.md @@ -24,7 +24,7 @@ POST /_synapse/admin/v1/join/ ``` 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 5721210fee11..dc007fa00e82 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 d398a120fb7e..d93d52a3ac15 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 0c843316c93a..c835e4a0cdbc 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/ ``` 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//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//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//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//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//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//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: @@ -731,7 +731,7 @@ PUT /_synapse/admin/v2/users//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. @@ -760,7 +760,7 @@ DELETE /_synapse/admin/v2/users//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. @@ -781,7 +781,7 @@ GET /_synapse/admin/v1/users//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//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//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//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//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. From 2b392995617e801f9f00b874ec73b76123a46aad Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 3 Jun 2021 14:37:33 +0100 Subject: [PATCH 21/25] Feature Documentation -> Internal Documentation --- docs/SUMMARY.md | 2 +- .../README.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) rename docs/development/{feature_documentation => internal_documentation}/README.md (56%) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 19c846bf214c..3edfd7f48d1c 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -73,7 +73,7 @@ - [Log Contexts](log_contexts.md) - [Replication](replication.md) - [TCP Replication](tcp_replication.md) - - [Feature Documentation](development/feature_documentation/README.md) + - [Internal Documentation](development/internal_documentation/README.md) - [Single Sign-On]() - [SAML](dev/saml.md) - [CAS](dev/cas.md) diff --git a/docs/development/feature_documentation/README.md b/docs/development/internal_documentation/README.md similarity index 56% rename from docs/development/feature_documentation/README.md rename to docs/development/internal_documentation/README.md index 271e9cca4c37..51c5fb94d537 100644 --- a/docs/development/feature_documentation/README.md +++ b/docs/development/internal_documentation/README.md @@ -1,12 +1,12 @@ -# Feature Documentation +# Internal Documentation -This section covers implementation documentation for various features of Synapse. +This section covers implementation documentation for various parts of Synapse. If a developer is planning to make a change to a feature of Synapse, it can be useful for general documentation of how that feature is implemented to be available. This saves the developer time in place of needing to understand how the feature works by reading the code. -Documentation that would be more useful for the perspective of a sysadmin, rather than -a developer who's intended to change to code, should instead be placed in -[Usage](../../usage/). \ No newline at end of file +Documentation that would be more useful for the perspective of a system administrator, +rather than a developer who's intending to change to code, should instead be placed +under the Usage section of the documentation. \ No newline at end of file From 071a6efea79cdb5b9703553fb66dd0490e5eb15a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 3 Jun 2021 15:14:03 +0100 Subject: [PATCH 22/25] Add Media Storage Providers draft chapter --- docs/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3edfd7f48d1c..3ee33e4b148a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -39,6 +39,7 @@ - [Third Party Rules]() - [Spam Checker](spam_checker.md) - [Presence Router](presence_router_module.md) + - [Media Storage Providers]() - [Writing a Module]() - [Workers](workers.md) - [Using `synctl` with Workers](synctl_workers.md) From 90520ae87ddc8a61a918e9c2086732828f85cf44 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 3 Jun 2021 15:29:24 +0100 Subject: [PATCH 23/25] Update mdbooks to 0.4.9; re-enable edit button --- .github/workflows/docs.yaml | 2 +- book.toml | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 29f92b9765c4..a746ae6de3a8 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -17,7 +17,7 @@ jobs: - name: Setup mdbook uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14 with: - mdbook-version: '0.4.8' + mdbook-version: '0.4.9' - name: Build the documentation run: mdbook build diff --git a/book.toml b/book.toml index 8d72082c881f..fa83d86ffc1c 100644 --- a/book.toml +++ b/book.toml @@ -16,8 +16,7 @@ create-missing = false [output.html] # The URL visitors will be directed to when they try to edit a page -# Disabled until https://github.com/rust-lang/mdBook/issues/1543 is fixed -#edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}" +edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}" # Remove the numbers that appear before each item in the sidebar, as they can # get quite messy as we nest deeper From f896a1b622ed4072191b55e6415554fb5c7ff4fd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 3 Jun 2021 15:38:08 +0100 Subject: [PATCH 24/25] Drop 'Writing a Module' chapter draft until new module API exists --- docs/SUMMARY.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3ee33e4b148a..8f39ae027001 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -40,7 +40,6 @@ - [Spam Checker](spam_checker.md) - [Presence Router](presence_router_module.md) - [Media Storage Providers]() - - [Writing a Module]() - [Workers](workers.md) - [Using `synctl` with Workers](synctl_workers.md) - [Systemd](systemd-with-workers/README.md) From 6991e88f91508588ce60a75c90919ece699a6ad2 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 3 Jun 2021 15:46:59 +0100 Subject: [PATCH 25/25] Fix links to documentation Co-authored-by: Tulir Asokan --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 37d70497ed59..e113f55d2a70 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Synapse Documentation -**The documentation is currently hosted [here](https://matrix-org.github.com/synapse).** +**The documentation is currently hosted [here](https://matrix-org.github.io/synapse).** Please update any links to point to the new website instead. ## About @@ -8,7 +8,7 @@ Please update any links to point to the new website instead. This directory currently holds a series of markdown files documenting how to install, use and develop Synapse, the reference Matrix homeserver. The documentation is readable directly from this repository, but it is recommended to instead browse through the -[website](https://matrix-org.github.com/synapse) for easier discoverability. +[website](https://matrix-org.github.io/synapse) for easier discoverability. ## Adding to the documentation