Initial documentation setup

MANIFEST.in

@@ -1,6 +1,8 @@
 graft src/pas
 graft docs
+prune docs/_build
 global-exclude *.pyc
+global-exclude .DS_Store
 include *.md
 include *.txt
 include *.yaml

Makefile

@@ -15,9 +15,9 @@ GREEN=`tput setaf 2`
 RESET=`tput sgr0`
 YELLOW=`tput setaf 3`
 
-BACKEND_FOLDER=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
-COMPOSE_FOLDER=${BACKEND_FOLDER}/tests
-DOCS_DIR=${BACKEND_FOLDER}/docs
+REPOSITORY_FOLDER=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
+COMPOSE_FOLDER=${REPOSITORY_FOLDER}/tests
+DOCS_DIR=${REPOSITORY_FOLDER}/docs
 
 # Python checks
 PYTHON?=python3

docs/conf.py

@@ -0,0 +1,102 @@
+from pkg_resources import get_distribution
+
+import sys
+
+
+project = "pas.plugins.oidc"
+copyright = "2023, Plone Community"
+
+# The full version, including alpha/beta/rc tags.
+release = get_distribution(project).version
+# The short X.Y version.
+version = ".".join(release.split(".")[0:2])
+
+# The suffix of source filenames.
+source_suffix = {
+    ".md": "markdown",
+    ".rst": "restructuredtext",
+}
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinxext.opengraph",
+    "sphinx.ext.graphviz",
+]
+master_doc = "index"
+
+# locale_dirs = ['translated/']
+language = "en"
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual])
+# This enables PDF generation.
+latex_documents = [
+    (
+        "index",
+        "paspluginsoidc.tex",
+        "pas.plugins.oidc Documentation",
+        "",
+        "manual",
+    )
+]
+
+
+class Mock:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, *args, **kwargs):
+        return Mock()
+
+    @classmethod
+    def __getattr__(cls, name):
+        if name in ("__file__", "__path__"):
+            return "/dev/null"
+        elif name[0] == name[0].upper():
+            mockType = type(name, (), {})
+            mockType.__module__ = __name__
+            return mockType
+        else:
+            return Mock()
+
+
+MOCK_MODULES = ["lxml"]
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = Mock()
+
+
+# -- Options for myST markdown conversion to html -----------------------------
+
+# For more information see:
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "deflist",  # You will be able to utilise definition lists
+    # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists
+    "colon_fence",  # You can also use ::: delimiters to denote code fences,\
+    #  instead of ```.
+    "substitution",  # plone.restapi \
+    # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
+    "html_image",  # For inline images. \
+    # See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+]
+
+
+# -- 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_book_theme"
+html_logo = "_static/icon.png"
+html_favicon = "_static/favicon.ico"
+html_css_files = ["styles.css", ("print.css", {"media": "print"})]
+html_static_path = [
+    "_static",  # Last path wins. See https://github.com/plone/documentation/pull/1442
+]

docs/index.md

@@ -0,0 +1,35 @@
+(index-label)=
+
+# pas.plugins.oidc
+
+<div align="center">
+
+[![PyPI](https://img.shields.io/pypi/v/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+[![PyPI - Wheel](https://img.shields.io/pypi/wheel/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+[![PyPI - License](https://img.shields.io/pypi/l/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+[![PyPI - Status](https://img.shields.io/pypi/status/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+
+
+[![PyPI - Plone Versions](https://img.shields.io/pypi/frameworkversions/plone/pas.plugins.oidc)](https://pypi.org/project/pas.plugins.oidc/)
+
+[![Meta](https://github.com/collective/pas.plugins.oidc/actions/workflows/meta.yml/badge.svg)](https://github.com/collective/pas.plugins.oidc/actions/workflows/meta.yml)
+![Code Style](https://img.shields.io/badge/Code%20Style-Black-000000)
+
+[![GitHub contributors](https://img.shields.io/github/contributors/collective/pas.plugins.oidc)](https://github.com/collective/pas.plugins.oidc)
+[![GitHub Repo stars](https://img.shields.io/github/stars/collective/pas.plugins.oidc?style=social)](https://github.com/collective/pas.plugins.oidc)
+
+</div>
+
+## Intro
+
+This is a Plone authentication plugin for OpenID Connect.
+OAuth 2.0 should work as well because OpenID Connect is built on top of this protocol.
+
+
+```{toctree}
+:maxdepth: 3
+:hidden: true
+
+keycloak/index
+```

docs/keycloak/index.md

@@ -0,0 +1,10 @@
+(index-label)=
+
+# Keycloak Integration
+
+```{toctree}
+:maxdepth: 3
+:hidden: true
+
+restapi
+```

docs/keycloak/restapi.md

@@ -0,0 +1,49 @@
+(index-label)=
+
+# REST API Client
+
+To use the `Keycloak Group Plugin`, we need to create a client with the right permissions to use the REST API.
+
+## Client creation
+
+### Create a new client
+
+```{figure} _static/restapi-client-01.png
+:alt: Step 01 of Client Creation Wizard
+```
+
+### Set client authentication
+
+```{figure} _static/restapi-client-02.png
+:alt: Step 02 of Client Creation Wizard
+```
+
+### Login settings
+
+```{figure} _static/restapi-client-03.png
+:alt: Step 03 of Client Creation Wizard
+```
+
+### Check client credentials (client secret)
+
+```{figure} _static/restapi-client-04.png
+:alt: Client credentials
+```
+
+### Service accounts roles
+
+```{figure} _static/restapi-client-05.png
+:alt: Service Account Roles
+```
+
+### Assign new roles, filtering by clients
+
+```{figure} _static/restapi-client-06.png
+:alt: Assign roles to plone-admin (Filter by clients)
+```
+
+### Assign new realm-managent roles
+
+```{figure} _static/restapi-client-07.png
+:alt: Assign realm-management roles
+```

requirements-docs.txt

@@ -8,3 +8,4 @@ sphinx-book-theme
 sphinx-copybutton
 sphinx-togglebutton
 sphinxcontrib-spelling
+sphinxext.opengraph