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.

14 files changed, 117 insertions, 8 deletions

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 @@
+<!--
+  Include the contents of CONTRIBUTING.md from the project root (where Github likes it 
+  to be)
+-->
+# 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 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}}
\ 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 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}}
\ 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