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

@@ -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)

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.

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.

docs/development/contributing_guide.md

@@ -0,0 +1,7 @@
+<!--
+  Include the contents of CONTRIBUTING.md from the project root (where Github likes it 
+  to be)
+-->
+# Contributing
+
+{{#include ../../CONTRIBUTING.md}}

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/).

docs/other/README.md

@@ -0,0 +1,4 @@
+# Other
+
+This section includes miscellaneous documentation that does not fit into any other
+section.

docs/setup/README.md

@@ -0,0 +1,3 @@
+# Setup
+
+In this section, you will learn how to install and configure your own Synapse homeserver.

docs/setup/installation.md

@@ -0,0 +1,7 @@
+<!--
+  Include the contents of INSTALL.md from the project root without moving it, which may
+  break links around the internet. Additionally, note that SUMMARY.md is unable to 
+  directly link to content outside of the docs/ directory. So we use this file as a 
+  redirection.
+-->
+{{#include ../../INSTALL.md}}

docs/upgrading/README.md

@@ -0,0 +1,7 @@
+<!--
+  Include the contents of UPGRADE.rst from the project root without moving it, which may
+  break links around the internet. Additionally, note that SUMMARY.md is unable to 
+  directly link to content outside of the docs/ directory. So we use this file as a 
+  redirection.
+-->
+{{#include ../../UPGRADE.rst}}

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.

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.

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).

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}}
+```

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.