Skip to content
This repository was archived by the owner on Apr 26, 2024. It is now read-only.

Commit fd9856e

Browse files
anoadragon453anoadragon453
authored
Compile and render Synapse's docs into a browsable, mobile-friendly and searchable website (#10086)
1 parent 9eea464 commit fd9856e

35 files changed

+978
-54
lines changed

‎.github/workflows/docs.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Deploy the documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- develop
7+
8+
workflow_dispatch:
9+
10+
jobs:
11+
pages:
12+
name: GitHub Pages
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v2
16+
17+
- name: Setup mdbook
18+
uses: peaceiris/actions-mdbook@4b5ef36b314c2599664ca107bb8c02412548d79d # v1.1.14
19+
with:
20+
mdbook-version: '0.4.9'
21+
22+
- name: Build the documentation
23+
run: mdbook build
24+
25+
- name: Deploy latest documentation
26+
uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
27+
with:
28+
github_token: ${{ secrets.GITHUB_TOKEN }}
29+
keep_files: true
30+
publish_dir: ./book
31+
destination_dir: ./develop

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,6 @@ __pycache__/
4646
/docs/build/
4747
/htmlcov
4848
/pip-wheel-metadata/
49+
50+
# docs
51+
book/

‎MANIFEST.in

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ exclude mypy.ini
4040
exclude sytest-blacklist
4141
exclude test_postgresql.sh
4242

43+
include book.toml
4344
include pyproject.toml
4445
recursive-include changelog.d *
4546

‎book.toml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Documentation for possible options in this file is at
2+
# https://rust-lang.github.io/mdBook/format/config.html
3+
[book]
4+
title = "Synapse"
5+
authors = ["The Matrix.org Foundation C.I.C."]
6+
language = "en"
7+
multilingual = false
8+
9+
# The directory that documentation files are stored in
10+
src = "docs"
11+
12+
[build]
13+
# Prevent markdown pages from being automatically generated when they're
14+
# linked to in SUMMARY.md
15+
create-missing = false
16+
17+
[output.html]
18+
# The URL visitors will be directed to when they try to edit a page
19+
edit-url-template = "https://github.com/matrix-org/synapse/edit/develop/{path}"
20+
21+
# Remove the numbers that appear before each item in the sidebar, as they can
22+
# get quite messy as we nest deeper
23+
no-section-label = true
24+
25+
# The source code URL of the repository
26+
git-repository-url = "https://github.com/matrix-org/synapse"
27+
28+
# The path that the docs are hosted on
29+
site-url = "/synapse/"
30+
31+
# Additional HTML, JS, CSS that's injected into each page of the book.
32+
# More information available in docs/website_files/README.md
33+
additional-css = [
34+
"docs/website_files/table-of-contents.css",
35+
"docs/website_files/remove-nav-buttons.css",
36+
"docs/website_files/indent-section-headers.css",
37+
]
38+
additional-js = ["docs/website_files/table-of-contents.js"]
39+
theme = "docs/website_files/theme"

‎changelog.d/10086.doc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Add initial infrastructure for rendering Synapse documentation with mdbook.

‎docs/README.md

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,72 @@
11
# Synapse Documentation
22

3-
This directory contains documentation specific to the `synapse` homeserver.
3+
**The documentation is currently hosted [here](https://matrix-org.github.io/synapse).**
4+
Please update any links to point to the new website instead.
45

5-
All matrix-generic documentation now lives in its own project, located at [matrix-org/matrix-doc](https://github.com/matrix-org/matrix-doc)
6+
## About
67

7-
(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.)
8+
This directory currently holds a series of markdown files documenting how to install, use
9+
and develop Synapse, the reference Matrix homeserver. The documentation is readable directly
10+
from this repository, but it is recommended to instead browse through the
11+
[website](https://matrix-org.github.io/synapse) for easier discoverability.
12+
13+
## Adding to the documentation
14+
15+
Most of the documentation currently exists as top-level files, as when organising them into
16+
a structured website, these files were kept in place so that existing links would not break.
17+
The rest of the documentation is stored in folders, such as `setup`, `usage`, and `development`
18+
etc. **All new documentation files should be placed in structured folders.** For example:
19+
20+
To create a new user-facing documentation page about a new Single Sign-On protocol named
21+
"MyCoolProtocol", one should create a new file with a relevant name, such as "my_cool_protocol.md".
22+
This file might fit into the documentation structure at:
23+
24+
- Usage
25+
- Configuration
26+
- User Authentication
27+
- Single Sign-On
28+
- **My Cool Protocol**
29+
30+
Given that, one would place the new file under
31+
`usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md`.
32+
33+
Note that the structure of the documentation (and thus the left sidebar on the website) is determined
34+
by the list in [SUMMARY.md](SUMMARY.md). The final thing to do when adding a new page is to add a new
35+
line linking to the new documentation file:
36+
37+
```markdown
38+
- [My Cool Protocol](usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md)
39+
```
40+
41+
## Building the documentation
42+
43+
The documentation is built with [mdbook](https://rust-lang.github.io/mdBook/), and the outline of the
44+
documentation is determined by the structure of [SUMMARY.md](SUMMARY.md).
45+
46+
First, [get mdbook](https://github.com/rust-lang/mdBook#installation). Then, **from the root of the repository**,
47+
build the documentation with:
48+
49+
```sh
50+
mdbook build
51+
```
52+
53+
The rendered contents will be outputted to a new `book/` directory at the root of the repository. You can
54+
browse the book by opening `book/index.html` in a web browser.
55+
56+
You can also have mdbook host the docs on a local webserver with hot-reload functionality via:
57+
58+
```sh
59+
mdbook serve
60+
```
61+
62+
The URL at which the docs can be viewed at will be logged.
63+
64+
## Configuration and theming
65+
66+
The look and behaviour of the website is configured by the [book.toml](../book.toml) file
67+
at the root of the repository. See
68+
[mdbook's documentation on configuration](https://rust-lang.github.io/mdBook/format/config.html)
69+
for available options.
70+
71+
The site can be themed and additionally extended with extra UI and features. See
72+
[website_files/README.md](website_files/README.md) for details.

‎docs/SUMMARY.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Summary
2+
3+
# Introduction
4+
- [Welcome and Overview](welcome_and_overview.md)
5+
6+
# Setup
7+
- [Installation](setup/installation.md)
8+
- [Using Postgres](postgres.md)
9+
- [Configuring a Reverse Proxy](reverse_proxy.md)
10+
- [Configuring a Turn Server](turn-howto.md)
11+
- [Delegation](delegate.md)
12+
13+
# Upgrading
14+
- [Upgrading between Synapse Versions](upgrading/README.md)
15+
- [Upgrading from pre-Synapse 1.0](MSC1711_certificates_FAQ.md)
16+
17+
# Usage
18+
- [Federation](federate.md)
19+
- [Configuration](usage/configuration/README.md)
20+
- [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md)
21+
- [Logging Sample Config File](usage/configuration/logging_sample_config.md)
22+
- [Structured Logging](structured_logging.md)
23+
- [User Authentication](usage/configuration/user_authentication/README.md)
24+
- [Single-Sign On]()
25+
- [OpenID Connect](openid.md)
26+
- [SAML]()
27+
- [CAS]()
28+
- [SSO Mapping Providers](sso_mapping_providers.md)
29+
- [Password Auth Providers](password_auth_providers.md)
30+
- [JSON Web Tokens](jwt.md)
31+
- [Registration Captcha](CAPTCHA_SETUP.md)
32+
- [Application Services](application_services.md)
33+
- [Server Notices](server_notices.md)
34+
- [Consent Tracking](consent_tracking.md)
35+
- [URL Previews](url_previews.md)
36+
- [User Directory](user_directory.md)
37+
- [Message Retention Policies](message_retention_policies.md)
38+
- [Pluggable Modules]()
39+
- [Third Party Rules]()
40+
- [Spam Checker](spam_checker.md)
41+
- [Presence Router](presence_router_module.md)
42+
- [Media Storage Providers]()
43+
- [Workers](workers.md)
44+
- [Using `synctl` with Workers](synctl_workers.md)
45+
- [Systemd](systemd-with-workers/README.md)
46+
- [Administration](usage/administration/README.md)
47+
- [Admin API](usage/administration/admin_api/README.md)
48+
- [Account Validity](admin_api/account_validity.md)
49+
- [Delete Group](admin_api/delete_group.md)
50+
- [Event Reports](admin_api/event_reports.md)
51+
- [Media](admin_api/media_admin_api.md)
52+
- [Purge History](admin_api/purge_history_api.md)
53+
- [Purge Rooms](admin_api/purge_room.md)
54+
- [Register Users](admin_api/register_api.md)
55+
- [Manipulate Room Membership](admin_api/room_membership.md)
56+
- [Rooms](admin_api/rooms.md)
57+
- [Server Notices](admin_api/server_notices.md)
58+
- [Shutdown Room](admin_api/shutdown_room.md)
59+
- [Statistics](admin_api/statistics.md)
60+
- [Users](admin_api/user_admin_api.md)
61+
- [Server Version](admin_api/version_api.md)
62+
- [Manhole](manhole.md)
63+
- [Monitoring](metrics-howto.md)
64+
- [Scripts]()
65+
66+
# Development
67+
- [Contributing Guide](development/contributing_guide.md)
68+
- [Code Style](code_style.md)
69+
- [Git Usage](dev/git.md)
70+
- [Testing]()
71+
- [OpenTracing](opentracing.md)
72+
- [Synapse Architecture]()
73+
- [Log Contexts](log_contexts.md)
74+
- [Replication](replication.md)
75+
- [TCP Replication](tcp_replication.md)
76+
- [Internal Documentation](development/internal_documentation/README.md)
77+
- [Single Sign-On]()
78+
- [SAML](dev/saml.md)
79+
- [CAS](dev/cas.md)
80+
- [State Resolution]()
81+
- [The Auth Chain Difference Algorithm](auth_chain_difference_algorithm.md)
82+
- [Media Repository](media_repository.md)
83+
- [Room and User Statistics](room_and_user_statistics.md)
84+
- [Scripts]()
85+
86+
# Other
87+
- [Dependency Deprecation Policy](deprecation_policy.md)

‎docs/admin_api/README.rst

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,14 @@
11
Admin APIs
22
==========
33

4-
This directory includes documentation for the various synapse specific admin
5-
APIs available.
6-
7-
Authenticating as a server admin
8-
--------------------------------
9-
10-
Many of the API calls in the admin api will require an `access_token` for a
11-
server admin. (Note that a server admin is distinct from a room admin.)
12-
13-
A user can be marked as a server admin by updating the database directly, e.g.:
14-
15-
.. code-block:: sql
4+
**Note**: The latest documentation can be viewed `here <https://matrix-org.github.io/synapse>`_.
5+
See `docs/README.md <../docs/README.md>`_ for more information.
166

17-
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
7+
**Please update links to point to the website instead.** Existing files in this directory
8+
are preserved to maintain historical links, but may be moved in the future.
189

19-
A new server admin user can also be created using the
20-
``register_new_matrix_user`` script.
21-
22-
Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings.
23-
24-
Once you have your `access_token`, to include it in a request, the best option is to add the token to a request header:
25-
26-
``curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>``
10+
This directory includes documentation for the various synapse specific admin
11+
APIs available. Updates to the existing Admin API documentation should still
12+
be made to these files, but any new documentation files should instead be placed under
13+
`docs/usage/administration/admin_api <../docs/usage/administration/admin_api>`_.
2714

28-
Fore more details, please refer to the complete `matrix spec documentation <https://matrix.org/docs/spec/client_server/r0.5.0#using-access-tokens>`_.

‎docs/admin_api/delete_group.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ POST /_synapse/admin/v1/delete_group/<group_id>
1111
```
1212

1313
To use it, you will need to authenticate by providing an `access_token` for a
14-
server admin: see [README.rst](README.rst).
14+
server admin: see [Admin API](../../usage/administration/admin_api).

‎docs/admin_api/event_reports.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The api is:
77
GET /_synapse/admin/v1/event_reports?from=0&limit=10
88
```
99
To use it, you will need to authenticate by providing an `access_token` for a
10-
server admin: see [README.rst](README.rst).
10+
server admin: see [Admin API](../../usage/administration/admin_api).
1111

1212
It returns a JSON body like the following:
1313

@@ -95,7 +95,7 @@ The api is:
9595
GET /_synapse/admin/v1/event_reports/<report_id>
9696
```
9797
To use it, you will need to authenticate by providing an `access_token` for a
98-
server admin: see [README.rst](README.rst).
98+
server admin: see [Admin API](../../usage/administration/admin_api).
9999

100100
It returns a JSON body like the following:
101101

0 commit comments

Comments
 (0)