move existing documentation into sphinx format

.gitignore

+docs/_build/
 .env
 __pycache__
 *.lock

README.md

-# Install
-
-Clone the repo  and make sure to also fetch the submodules.
-```
-git submodule update --init
-```
-
-Installation should be done via the helm using the helmchart contained in `./helmchart`.
-Make sure to edit the values in `./helmchart/single-sign-on/values.yaml` according to your needs
-
-For Details on how to configure the chart. Refer to `./helmchart/single-sign-on/README.md`
-
-# Using SSO
-
-To use OpenID Connect or oAuth you need to set up an oAuth Client for every application that
-needs to authenticate it's users. You can leverage the Hydra Admin API to create oAuth clients.
-As a starting point, you can have a look at the script provided in `test/`.
-
-To use SSO, configure your oAuth client (for example nextcloud) and create a new oAuth client object.
-After your server is running, refer to `https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` as a reference on how to configure your openID Connect or oAuth client.
-
-# Testing
-
-In order to run tests locally, you can start the environment via `docker-compose`.
-Install docker-compose via `pip install docker-compose` after you [insalled
-docker](https://docs.docker.com/v17.12/install/) on your machine.
-Running `docker-compose up --build` after that builds and starts all containers.
-The default configuration works if you are running the setup on your local
-machine. You need to change the following values in the docker-compose.yml file in case
-you run the containers on a remote machine:
-
-```
-    environment:
-      - URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
-      - URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
-      - URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
-      - URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
-      - URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/
-```
-
-Notice that you need to create users and applications before being able to login.
-You can use the scripts located in `user-panel/utils` to create users for testing.
-
-If you don't have a test application yourself, you can use the small OpeinID Connect
-test application located at `test/login_logout/`. Instructions on how to run the test
-application can be found in `test/login_logout/README.md`.
-
-Also refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests that are
-contained in this repository.
+Please refer to the [online documentation](...) for all the details

VERSION

+0.2

docs/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'single-sign-on'
+copyright = '2020, OpenAppStack'
+author = 'OpenAppStack'
+
+# The full version, including alpha/beta/rc tags
+with open('../VERSION') as version_file:
+    release = version_file.read()
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'recommonmark'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Readthedocs.io needs us to tell it what the index file is. This defaults to
+# 'contents'
+master_doc = 'index'

docs/helmchart.md

+# Single sign-on
+
+Single sign-on adds an Authentication server to your k8s cluster, that can be used by
+applications within your cluster and by external applications to log in your users.
+This chart also includes a minimalistic user-panel which can be used
+to create new users, assign roles to users and grant users access to applications.
+
+## Prerequisites
+
+ * Kubernetes 1.13+ with Beta APIs enabled
+ * helm 2.14.3+
+ * ORY helm chart repository installed
+   * `helm repo add ory https://k8s.ory.sh/helm/charts && helm repo update`
+
+## Configuration
+
+You can configure the chart by changing the default values in the `./values.yaml` file.
+The following table lists the configurable parameters of the single sign-on chart and their
+default values. Values in **bold** letters need to be changed for Routing and TLS to work.
+
+| Parameter                            | Description                                             | Default                                 |
+| ------------------------------------ | ------------------------------------------------------- | -------------------------               |
+| `singleSignOnHost`                   | **FQDN of the openID Connect / oAuth2 server**          | **sso.oas.example.net**                 |
+| `loginProviderImage.repository`      | Name of image repository to be used for login provider  | open.greenhost.net:4567/openappstack/single-sign-on/login_provider |
+| `loginProviderImage.tag`             | Release version of login provider image                 | master                                  |
+| `consentProviderImage.repository`    | Name of image repository to be used for consent provider| open.greenhost.net:4567/openappstack/single-sign-on/consent_provider |
+| `consentProviderImage.tag`           | Release version of consent provider image               | master                                  |
+| `userpanel.ingress.host`             | **FQDN of the userpanel**                               | **admin.oas.example.net**               |
+| `userpanel.oAuth.client_secret`      | oAuth2 client secret                                    | YouReallyNeedToChangeThis               |
+| `userbackend.username`               | Username of the admin user                              | admin                                   |
+| `userbackend.password`               | Password of the admin user                              | YouReallyNeedToChangeThis               |
+| `userbackend.email`                  | Email address of the admin user                         | admin@example.net                       |
+| `userbackend.postgres.password`      | Root pw of the psql DB                                  | postgres                                |
+| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server**                        | **https://sso.oas.example.net**         |
+| `hydra.hydra.config.urls.login`      | **URI that will be used for the login page**            | **https://sso.oas.example.net/login**   |
+| `hydra.hydra.config.urls.consent`    | **URI that will be used for permission checks**         | **https://sso.oas.example.net/consent** |
+| `hydra.hydra.config.secrets.system`  | Secret that is used to generate secure tokens           | YouReallyNeedToChangeThis               |
+
+## Installing and uninstalling the Chart
+
+To install the chart with the realease name `single-sign-on` first clone the repository,
+and then run helm install.
+
+```
+$ git clone https://open.greenhost.net/openappstack/single-sign-on
+$ cd single-sign-on/helmchart/single-sign-on/
+$ helm install -n single-sign-on .
+```
+
+The last command will deploy the single sign-on components on your server and applies a
+default configuration. You should change the default configuration before running the command.
+The [configuration](#configuration) section lists all configuration parameters.
+
+In case you already ran the install command, you can uninstall the deployment by executing:
+
+```
+$ helm list     # [OPTIONAL] - Lists all deployed releases
+$ helm delete single-sign-on --purge
+```
+
+> **WARNING**: Executing the `delete` command with the `purge` flag will delete all data that is related to the applications. Don't run this command in a production environment if you are not absolutely sure that you have a restorable backup of your data.
+

docs/index.rst

+.. single-sign-on documentation master file, created by
+   sphinx-quickstart on Thu Jan  9 10:37:53 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to single-sign-on's documentation!
+==========================================
+
+This project provides a single sign on solution based on
+[hydra](https://github.com/ory/hydra) and in combination with a [user
+panel](https://open.greenhost.net/openappstack/user-panel).
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation_instructions
+   usage
+   helmchart
+   local_development

docs/installation_instructions.md

+## Install
+
+Clone the repo  and make sure to also fetch the submodules.
+```
+git submodule update --init
+```
+
+Installation should be done via the helm using the helmchart contained in
+`./helmchart`.  Make sure to edit the values in
+`./helmchart/single-sign-on/values.yaml` according to your needs
+
+For Details on how to configure the chart. Refer to
+`./helmchart/single-sign-on/README.md`
+

docs/local_development.md

+# Testing
+
+In order to run tests locally, you can start the environment via
+`docker-compose`.  Install docker-compose via `pip install docker-compose` after
+you [insalled docker](https://docs.docker.com/v17.12/install/) on your machine.
+Running `docker-compose up --build` after that builds and starts all containers.
+The default configuration works if you are running the setup on your local
+machine. You need to change the following values in the docker-compose.yml file
+in case you run the containers on a remote machine:
+
+```yaml
+environment:
+ - URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
+ - URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
+ - URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
+ - URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
+ - URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/ ```
+```
+
+Notice that you need to create users and applications before being able to
+login.  You can use the scripts located in `user-panel/utils` to create users
+for testing.
+
+If you don't have a test application yourself, you can use the small OpeinID
+Connect test application located at `test/login_logout/`. Instructions on how to
+run the test application can be found in `test/login_logout/README.md`.
+
+Also refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests
+that are contained in this repository.

docs/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

+sphinx>=2.3.1
+sphinx_rtd_theme>=0.4.3
+recommonmark>=0.6.0

docs/usage.md

+## Using SSO
+
+To use OpenID Connect or oAuth you need to set up an oAuth Client for every
+application that needs to authenticate it's users. You can leverage the Hydra
+Admin API to create oAuth clients.  As a starting point, you can have a look at
+the script provided in `test/`.
+
+To use SSO, configure your oAuth client (for example nextcloud) and create a new
+oAuth client object.  After your server is running, refer to
+`https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` as a reference on
+how to configure your openID Connect or oAuth client.
+

helmchart/single-sign-on/README.md

-# Single sign-on
-
-Single sign-on adds an Authentication server to your k8s cluster, that can be used by
-applications within your cluster and by external applications to log in your users.
-This chart also includes a minimalistic user-panel which can be used
-to create new users, assign roles to users and grant users access to applications.
-
-## Prerequisites
-
- * Kubernetes 1.13+ with Beta APIs enabled
- * helm 2.14.3+
- * ORY helm chart repository installed
-   * `helm repo add ory https://k8s.ory.sh/helm/charts && helm repo update`
-
-## Configuration
-
-You can configure the chart by changing the default values in the `./values.yaml` file.
-The following table lists the configurable parameters of the single sign-on chart and their
-default values. Values in **bold** letters need to be changed for Routing and TLS to work.
-
-| Parameter                            | Description                                             | Default                                 |
-| ------------------------------------ | ------------------------------------------------------- | -------------------------               |
-| `singleSignOnHost`                   | **FQDN of the openID Connect / oAuth2 server**          | **sso.oas.example.net**                 |
-| `loginProviderImage.repository`      | Name of image repository to be used for login provider  | open.greenhost.net:4567/openappstack/single-sign-on/login_provider |
-| `loginProviderImage.tag`             | Release version of login provider image                 | master                                  |
-| `consentProviderImage.repository`    | Name of image repository to be used for consent provider| open.greenhost.net:4567/openappstack/single-sign-on/consent_provider |
-| `consentProviderImage.tag`           | Release version of consent provider image               | master                                  |
-| `userpanel.ingress.host`             | **FQDN of the userpanel**                               | **admin.oas.example.net**               |
-| `userpanel.oAuth.client_secret`      | oAuth2 client secret                                    | YouReallyNeedToChangeThis               |
-| `userbackend.username`               | Username of the admin user                              | admin                                   |
-| `userbackend.password`               | Password of the admin user                              | YouReallyNeedToChangeThis               |
-| `userbackend.email`                  | Email address of the admin user                         | admin@example.net                       |
-| `userbackend.postgres.password`      | Root pw of the psql DB                                  | postgres                                |
-| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server**                        | **https://sso.oas.example.net**         |
-| `hydra.hydra.config.urls.login`      | **URI that will be used for the login page**            | **https://sso.oas.example.net/login**   |
-| `hydra.hydra.config.urls.consent`    | **URI that will be used for permission checks**         | **https://sso.oas.example.net/consent** |
-| `hydra.hydra.config.secrets.system`  | Secret that is used to generate secure tokens           | YouReallyNeedToChangeThis               |
-
-## Installing and uninstalling the Chart
-
-To install the chart with the realease name `single-sign-on` first clone the repository,
-and then run helm install.
-
-```
-$ git clone https://open.greenhost.net/openappstack/single-sign-on
-$ cd single-sign-on/helmchart/single-sign-on/
-$ helm install -n single-sign-on .
-```
-
-The last command will deploy the single sign-on components on your server and applies a
-default configuration. You should change the default configuration before running the command.
-The [configuration](#configuration) section lists all configuration parameters.
-
-In case you already ran the install command, you can uninstall the deployment by executing:
-
-```
-$ helm list     # [OPTIONAL] - Lists all deployed releases
-$ helm delete single-sign-on --purge
-```
-
-> **WARNING**: Executing the `delete` command with the `purge` flag will delete all data that is related to the applications. Don't run this command in a production environment if you are not absolutely sure that you have a restorable backup of your data.
-
+Please refer to the [online documentation](.../helmchart)