diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 22ed0ef024..39c8879b58 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]() @@ -36,7 +36,7 @@ - [Workers](workers.md) - [Using `synctl` with Workers](synctl_workers.md) - [Systemd](systemd-with-workers/README.md) - - [Administration]() + - [Administration](usage/administration/README.md) - [Admin API](admin_api/README.rst) - [Account Validity](admin_api/account_validity.rst) - [Delete Group](admin_api/delete_group.md) @@ -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/administration/README.md b/docs/administration/README.md new file mode 100644 index 0000000000..e1e57546ab --- /dev/null +++ b/docs/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/development/README.md b/docs/development/README.md new file mode 100644 index 0000000000..393133ea75 --- /dev/null +++ b/docs/development/README.md @@ -0,0 +1,5 @@ +# Development + +This section covers topics related to development of Synapse. This includes explanations +of how different parts of Synapse are implemented, as well as guidance on the tooling +that Synapse developers regularly use. \ 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 0000000000..a79bb841c5 --- /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 0000000000..271e9cca4c --- /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/other/README.md b/docs/other/README.md new file mode 100644 index 0000000000..ba29d867e0 --- /dev/null +++ b/docs/other/README.md @@ -0,0 +1,4 @@ +# Other + +This section includes miscellaneous documentation that does not fit into any other +section. \ No newline at end of file diff --git a/docs/setup/README.md b/docs/setup/README.md new file mode 100644 index 0000000000..fcc2bf23a1 --- /dev/null +++ b/docs/setup/README.md @@ -0,0 +1,3 @@ +# Setup + +In this section, you will learn how to install and configure your own Synapse homeserver. \ No newline at end of file diff --git a/docs/setup/installation.md b/docs/setup/installation.md new file mode 100644 index 0000000000..8bb1cffd3d --- /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 0000000000..258e58cf15 --- /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/README.md b/docs/usage/README.md new file mode 100644 index 0000000000..5dee2f38c7 --- /dev/null +++ b/docs/usage/README.md @@ -0,0 +1,3 @@ +# Usage + +This section contains information on how to configure, manage, maintain and administrate your Synapse homeserver and users. \ 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 0000000000..e1e57546ab --- /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 0000000000..7d3f586da3 --- /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 0000000000..f826de8b85 --- /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 0000000000..087ae053cf --- /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