From cea4c7c3b1b9a28ac60757410278a03e9bdea85a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20P=C3=BChringer?=
 <51900829+puehringer@users.noreply.github.com>
Date: Mon, 4 Apr 2022 13:13:54 +0200
Subject: [PATCH] Removed sphinx and added mkdocs (#685)

---
 .circleci/config.yml                     |   2 +-
 Makefile                                 |   6 +-
 docs/.gitignore                          |   2 -
 docs/ID-Mapping/index.md                 |  54 ++++++++++
 docs/_static/touch.txt                   |   0
 docs/_templates/touch.txt                |   0
 docs/commands/command-extension-point.md |  29 ++++++
 docs/commands/index.md                   |   2 +
 docs/conf.py                             | 126 -----------------------
 docs/database/index.md                   |   2 +
 docs/development/index.md                |  33 ++++++
 docs/development/workspaces.md           |   1 +
 docs/index.md                            |   3 +
 docs/index.rst                           |  20 ----
 docs/middleware/index.md                 |   2 +
 docs/plugins/index.md                    |   2 +
 docs/plugins/write-your-own-plugin.md    |   1 +
 docs/security/index.md                   |   1 +
 docs/settings/index.md                   |   1 +
 mkdocs.yml                               |  26 +++++
 requirements_dev.txt                     |   4 +-
 tdp_core/security/store/base_store.py    |   4 +-
 tdp_core/security/store/dummy_store.py   |   9 --
 23 files changed, 165 insertions(+), 165 deletions(-)
 delete mode 100644 docs/.gitignore
 create mode 100644 docs/ID-Mapping/index.md
 delete mode 100644 docs/_static/touch.txt
 delete mode 100644 docs/_templates/touch.txt
 create mode 100644 docs/commands/command-extension-point.md
 create mode 100644 docs/commands/index.md
 delete mode 100644 docs/conf.py
 create mode 100644 docs/database/index.md
 create mode 100644 docs/development/index.md
 create mode 100644 docs/development/workspaces.md
 create mode 100644 docs/index.md
 delete mode 100644 docs/index.rst
 create mode 100644 docs/middleware/index.md
 create mode 100644 docs/plugins/index.md
 create mode 100644 docs/plugins/write-your-own-plugin.md
 create mode 100644 docs/security/index.md
 create mode 100644 docs/settings/index.md
 create mode 100644 mkdocs.yml

diff --git a/.circleci/config.yml b/.circleci/config.yml
index da34c4760..fcd8e3896 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -55,7 +55,7 @@ jobs:
           name: API Doc generation
           command: |
             . ~/venv/bin/activate
-            make sphinx
+            make mkdocs
       - run:
           name: Build wheel
           command: |
diff --git a/Makefile b/Makefile
index 7c4e27d7a..c9ce5e500 100644
--- a/Makefile
+++ b/Makefile
@@ -29,9 +29,9 @@ lint:
 test:
 	pytest $(pkg_src)
 
-.PHONEY: sphinx ## Generate API docs using sphinx
-sphinx: 
-	sphinx-apidoc -o docs -f ./$(pkg_src) && sphinx-build ./docs build/docs
+.PHONEY: mkdocs ## Shortcut for mkdocs command
+mkdocs: 
+	mkdocs build
 
 .PHONY: install  ## Install the requirements
 install:
diff --git a/docs/.gitignore b/docs/.gitignore
deleted file mode 100644
index 55736c38a..000000000
--- a/docs/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-/modules.rst
-/tdp_core.rst
diff --git a/docs/ID-Mapping/index.md b/docs/ID-Mapping/index.md
new file mode 100644
index 000000000..f62ea8fc6
--- /dev/null
+++ b/docs/ID-Mapping/index.md
@@ -0,0 +1,54 @@
+# ID-Mapping introduction
+
+## What is an ID-type?
+
+## Adding a mapping between two ID-types
+
+In your `__init__.py` of your plugin, you can add a new mapping via the `mapping_provider` extension point:
+
+```python
+registry.append('mapping_provider', '<my_mapping_provider_id>', '<my_plugin>.my_mapping_provider')
+```
+
+The new file `<my_plugin>.my_mapping_provider.py` containing the mapping provider, i.e. a create
+function returning mapping tuples (these can be dynamically generated, coming from a db, request, ...):
+
+```python
+def create():
+  return [
+    ('from', 'to', lambda ids: [[f'converted_{id}'] for id in ids]),
+    ('to', 'from', lambda ids: [[id[10:]] for id in ids]),
+  ]
+```
+
+Each tuple is basically `(from_idtype, to_idtype, mapping_function receiving multiple ids returning multiple ids for each id)`. Generally, the first id returned by the mapping function is preferred, however all are returned by default.
+
+!!! note
+
+    By simply defining tuples between id-types, powerful transitive mappings can be resolved by traversing the resulting graph. Visyn Core utilizing such a graph to allow for transitive mappings. 
+    
+    Example:
+    Imagine registering the tuples `IDTypeA -> IDTypeB` and `IDTypeB -> IDTypeC`. With that, the transitive connection between `ÌDTypeA -> IDTypeC` is possible by first executing `IDTypeA -> IDTypeB`, followed by `IDTypeB -> IDTypeC`.
+
+## Mapping between two ID-types
+
+ * You can test it by showing all possible idtypes:
+
+[http://localhost:9000/api/idtype](http://localhost:9000/api/idtype)
+
+ * Or where 'from' can be mapped to:
+
+[http://localhost:9000/api/idtype/from](http://localhost:9000/api/idtype/from)
+
+ * Or mapping 'from' to 'to' for some ids:
+
+[http://localhost:9000/api/idtype/from/to?q=1,2,3](http://localhost:9000/api/idtype/from/to?q=1,2,3)
+
+ * Or mapping 'to' to 'from' for some ids:
+
+[http://localhost:9000/api/idtype/to/from?q=converted_1,converted_2,converted_3](http://localhost:9000/api/idtype/to/from?q=converted_1,converted_2,converted_3)
+
+ * Or mapping 'from' to 'to' for some ids and only wanting the first mapped id each:
+
+[http://localhost:9000/api/idtype/from/to?q=1,2,3&mode=first](http://localhost:9000/api/idtype/from/to?q=1,2,3&mode=first
+)
diff --git a/docs/_static/touch.txt b/docs/_static/touch.txt
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/_templates/touch.txt b/docs/_templates/touch.txt
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/commands/command-extension-point.md b/docs/commands/command-extension-point.md
new file mode 100644
index 000000000..a657c68a9
--- /dev/null
+++ b/docs/commands/command-extension-point.md
@@ -0,0 +1,29 @@
+# `command` Extension Point
+
+The `command` extension point supports adding custom commands which are executed within the server context, i.e. with loaded plugin registry, migrations, etc. These command override the default server startup and execute the command only. 
+
+## Register a custom command
+
+Registering custom commands is considered legacy and will not be discussed thoroughly. 
+
+## Running a custom command
+
+The python module `tdp_core.cmd` can be used as executable module to run any registered command. The corresponding call (executed in the same bash where the server is usually executed, i.e. docker if in dockerized environment) looks like this:
+
+```bash
+python -m tdp_core.cmd <cmd-id> <cmd-arg1> <cmd-arg2> <...>
+```
+
+More concretely, one can trigger a database upgrade using the following command:
+
+```bash
+python -m tdp_core.cmd db-migration <migration-id> upgrade head
+```
+
+And a complete downgrade using following command:
+
+```bash
+python -m tdp_core.cmd db-migration <migration-id> downgrade base
+```
+
+Please see the official alembic documentation regarding database migrations: [https://alembic.sqlalchemy.org/en/latest/api/commands.html](https://alembic.sqlalchemy.org/en/latest/api/commands.html).
diff --git a/docs/commands/index.md b/docs/commands/index.md
new file mode 100644
index 000000000..913953ca2
--- /dev/null
+++ b/docs/commands/index.md
@@ -0,0 +1,2 @@
+# TODO: Commands introduction
+
diff --git a/docs/conf.py b/docs/conf.py
deleted file mode 100644
index cf81bf759..000000000
--- a/docs/conf.py
+++ /dev/null
@@ -1,126 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# 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 sys
-import os
-import json
-from codecs import open
-
-sys.path.insert(0, os.path.abspath('..'))
-
-with open('../package.json', encoding='utf-8') as json_data:
-  import json
-
-  pkg = json.load(json_data)
-
-# -- General configuration ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.todo']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_parsers = {
-  '.md': 'recommonmark.parser.CommonMarkParser',
-}
-source_suffix = ['.rst', '.md']
-
-# The master toctree document.
-master_doc = 'index'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['build', 'tests']
-
-# General information about the project.
-project = pkg['name']
-copyright = pkg['license']
-author = pkg['author']['name']
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = pkg['version']
-# The full version, including alpha/beta/rc tags.
-release = pkg['version']
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
-
-# -- 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 = 'alabaster'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# 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']
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = pkg['name'] + 'doc'
-
-# Sort members by type
-autodoc_member_order = 'groupwise'
-
-
-# Ensure that the __init__ method gets documented.
-def skip(app, what, name, obj, skip, options):
-  if name == '__init__':
-    return False
-  return skip
-
-
-def setup(app):
-  app.connect('autodoc-skip-member', skip)
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
diff --git a/docs/database/index.md b/docs/database/index.md
new file mode 100644
index 000000000..3bace34fc
--- /dev/null
+++ b/docs/database/index.md
@@ -0,0 +1,2 @@
+# TODO: Databases introduction
+
diff --git a/docs/development/index.md b/docs/development/index.md
new file mode 100644
index 000000000..d4158fe2a
--- /dev/null
+++ b/docs/development/index.md
@@ -0,0 +1,33 @@
+# TODO: Development Introduction
+
+All important scripts are exposed via the Makefile. Use `make help` to show all available commands. 
+
+## Formatting
+
+Use `make format` to reformat all corresponding files.
+
+## Linting
+
+Use `make lint` to check for linting issues.
+
+## Testing
+
+Use `make test` to run the available test-suites using pytest.
+
+## Writing documentation
+
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) is used to write this documentation.
+
+### Commands
+
+* `make mkdocs new [dir-name]` - Create a new project.
+* `make mkdocs serve` - Start the live-reloading docs server.
+* `make mkdocs build` - Build the documentation site.
+* `make mkdocs -h` - Print help message and exit.
+
+### Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
diff --git a/docs/development/workspaces.md b/docs/development/workspaces.md
new file mode 100644
index 000000000..008edccec
--- /dev/null
+++ b/docs/development/workspaces.md
@@ -0,0 +1 @@
+# TODO: Developer Workspace
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..e27a4d8c4
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,3 @@
+# Welcome to Visyn Core
+
+Visyn Core is the core of the Visyn Platform, an open-source platform for developing scalable web-based visual ananlytics platforms.
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 721442cc4..000000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. tdp_core documentation master file, created by
-   sphinx-quickstart on Tue Feb  7 19:42:32 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to TDP Core's documentation!
-=========================================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   modules
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/middleware/index.md b/docs/middleware/index.md
new file mode 100644
index 000000000..b2692c98c
--- /dev/null
+++ b/docs/middleware/index.md
@@ -0,0 +1,2 @@
+# TODO: Middleware
+
diff --git a/docs/plugins/index.md b/docs/plugins/index.md
new file mode 100644
index 000000000..22cfc9fcf
--- /dev/null
+++ b/docs/plugins/index.md
@@ -0,0 +1,2 @@
+# TODO: Plugins and Extensions
+
diff --git a/docs/plugins/write-your-own-plugin.md b/docs/plugins/write-your-own-plugin.md
new file mode 100644
index 000000000..84a162ba5
--- /dev/null
+++ b/docs/plugins/write-your-own-plugin.md
@@ -0,0 +1 @@
+# TODO: Write your own plugin
diff --git a/docs/security/index.md b/docs/security/index.md
new file mode 100644
index 000000000..45442c217
--- /dev/null
+++ b/docs/security/index.md
@@ -0,0 +1 @@
+# TODO: Security
diff --git a/docs/settings/index.md b/docs/settings/index.md
new file mode 100644
index 000000000..88886f17e
--- /dev/null
+++ b/docs/settings/index.md
@@ -0,0 +1 @@
+# TODO: Settings
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 000000000..6d2b67a94
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,26 @@
+site_name: Visyn Core
+theme:
+  name: material
+  features:
+    - navigation.expand
+  palette:
+    - media: "(prefers-color-scheme: light)" 
+      scheme: default
+      primary: blue
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)" 
+      scheme: slate
+      primary: blue
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.details
\ No newline at end of file
diff --git a/requirements_dev.txt b/requirements_dev.txt
index fec42709c..6d5e04493 100644
--- a/requirements_dev.txt
+++ b/requirements_dev.txt
@@ -2,8 +2,8 @@ black~=22.3.0
 debugpy~=1.5.1
 flake8~=4.0.1
 isort~=5.10.1
+mkdocs-material~=8.2.8
 pep8-naming~=0.12.1
 pytest-runner~=6.0.0
 pytest~=7.1.1
-recommonmark~=0.7.1
-Sphinx~=4.4.0
\ No newline at end of file
+recommonmark~=0.7.1
\ No newline at end of file
diff --git a/tdp_core/security/store/base_store.py b/tdp_core/security/store/base_store.py
index acea669fb..36bafccdc 100644
--- a/tdp_core/security/store/base_store.py
+++ b/tdp_core/security/store/base_store.py
@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Optional
 
 from fastapi import FastAPI, Request
 
@@ -18,5 +18,5 @@ def load_from_request(self, request: Request) -> User:
     def login(self, username: str, extra_fields={}) -> User:
         return None
 
-    def logout(self, user: User) -> Union[LogoutReturnValue, None]:
+    def logout(self, user: User) -> Optional[LogoutReturnValue]:
         pass
diff --git a/tdp_core/security/store/dummy_store.py b/tdp_core/security/store/dummy_store.py
index a85febf2f..0ffb19813 100644
--- a/tdp_core/security/store/dummy_store.py
+++ b/tdp_core/security/store/dummy_store.py
@@ -23,15 +23,6 @@ def is_password(self, given):
         return given_h == self.password
 
 
-def from_env_var(k, v):
-    elems = v.split(";")
-    name = k[12:]  # PHOVEA_USER_
-    salt = elems[0]
-    password = elems[1]
-    roles = elems[2:]
-    return DummyUser(id=name, name=name, roles=roles, password=password, salt=salt)
-
-
 class DummyStore(BaseStore):
     def __init__(self):
         self._users = [