Create and deploy VitePress docs (GH-16)

Author: ArtyomVancyan

.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+name: docs
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run deployment script on server
+        uses: appleboy/ssh-action@master
+        with:
+          host: ${{ secrets.HOST }}
+          username: ${{ secrets.USERNAME }}
+          key: ${{ secrets.KEY_ED25519 }}
+          port: ${{ secrets.PORT }}
+          script: sh ~/fastapi-oauth2/docs/deploy.sh

README.md

@@ -4,74 +4,17 @@
 [![Python](https://img.shields.io/pypi/pyversions/fastapi-oauth2.svg?logoColor=white)](https://pypi.org/project/fastapi-oauth2/)
 [![FastAPI](https://img.shields.io/badge/fastapi-%E2%89%A50.68.1-009486)](https://pypi.org/project/fastapi-oauth2/)
 [![Tests](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/tests.yml)
-[![License](https://img.shields.io/pypi/l/fastapi-oauth2.svg)](https://github.com/pysnippet/fastapi-oauth2/blob/master/LICENSE)
+[![Docs](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml/badge.svg)](https://github.com/pysnippet/fastapi-oauth2/actions/workflows/docs.yml)
 
-FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several auth providers. It depends on
-the [social-core](https://github.com/python-social-auth/social-core) authentication backends.
-
-## Installation
-
-```shell
-python -m pip install fastapi-oauth2
-```
-
-## Configuration
-
-Configuration requires you to provide the JWT requisites and define the clients of the particular providers. The
-middleware configuration is declared with the `OAuth2Config` and `OAuth2Client` classes.
-
-### OAuth2Config
-
-- `allow_http` - Allow insecure HTTP requests. Defaults to `False`.
-- `jwt_secret` - The secret key used to sign the JWT. Defaults to `None`.
-- `jwt_expires` - The expiration time of the JWT in seconds. Defaults to `900`.
-- `jwt_algorithm` - The algorithm used to sign the JWT. Defaults to `HS256`.
-- `clients` - The list of the OAuth2 clients. Defaults to `[]`.
-
-### OAuth2Client
-
-- `backend` - The [social-core](https://github.com/python-social-auth/social-core) authentication backend classname.
-- `client_id` - The OAuth2 client ID for the particular provider.
-- `client_secret` - The OAuth2 client secret for the particular provider.
-- `redirect_uri` - The OAuth2 redirect URI to redirect to after success. Defaults to the base URL.
-- `scope` - The OAuth2 scope for the particular provider. Defaults to `[]`.
-- `claims` - Claims mapping for the certain provider.
-
-It is also important to mention that for the configured clients of the auth providers, the authorization URLs are
-accessible by the `/oauth2/{provider}/auth` path where the `provider` variable represents the exact value of the auth
-provider backend `name` attribute.
-
-```python
-from fastapi_oauth2.claims import Claims
-from fastapi_oauth2.client import OAuth2Client
-from fastapi_oauth2.config import OAuth2Config
-from social_core.backends.github import GithubOAuth2
-
-oauth2_config = OAuth2Config(
-    allow_http=False,
-    jwt_secret=os.getenv("JWT_SECRET"),
-    jwt_expires=os.getenv("JWT_EXPIRES"),
-    jwt_algorithm=os.getenv("JWT_ALGORITHM"),
-    clients=[
-        OAuth2Client(
-            backend=GithubOAuth2,
-            client_id=os.getenv("OAUTH2_CLIENT_ID"),
-            client_secret=os.getenv("OAUTH2_CLIENT_SECRET"),
-            redirect_uri="https://pysnippet.org/",
-            scope=["user:email"],
-            claims=Claims(
-                picture="avatar_url",
-                identity=lambda user: "%s:%s" % (user.get("provider"), user.get("id")),
-            ),
-        ),
-    ]
-)
-```
+FastAPI OAuth2 is a middleware-based social authentication mechanism supporting several OAuth2 providers. It leverages
+the [social-core](https://github.com/python-social-auth/social-core) authentication backends and integrates seamlessly
+with FastAPI applications.
 
 ## Integration
 
-To integrate the package into your FastAPI application, you need to add the `OAuth2Middleware` with particular configs
-in the above-represented format and include the router to the main router of the application.
+For integrating the package into an existing FastAPI application, the router with OAuth2 routes and
+the `OAuth2Middleware` with particular [configs](https://docs.pysnippet.org/fastapi-oauth2/integration/configuration)
+should be added to the application.
 
 ```python
 from fastapi import FastAPI
@@ -80,24 +23,14 @@ from fastapi_oauth2.router import router as oauth2_router
 
 app = FastAPI()
 app.include_router(oauth2_router)
-app.add_middleware(OAuth2Middleware, config=oauth2_config)
-```
-
-After adding the middleware, the `user` attribute will be available in the request context. It will contain the user
-data provided by the OAuth2 provider.
-
-```jinja2
-{% if request.user.is_authenticated %}
-    <a href="/oauth2/logout">Sign out</a>
-{% else %}
-    <a href="/oauth2/github/auth">Sign in</a>
-{% endif %}
+app.add_middleware(OAuth2Middleware, config=OAuth2Config(...))
 ```
 
 ## Contribute
 
-Any contribution is welcome. If you have any ideas or suggestions, feel free to open an issue or a pull request. And
-don't forget to add tests for your changes.
+Any contribution is welcome. Always feel free to open an issue or a discussion if you have any questions not covered by
+the documentation. If you have any ideas or suggestions, please, open a pull request. Your name will shine in our
+contributors' list. Be proud of what you build!
 
 ## License
 

docs/.vitepress/config.js

@@ -0,0 +1,7 @@
+#!/bin/bash
+cd ~/fastapi-oauth2/
+git restore .
+git pull
+sudo rm -r /var/www/docs/fastapi-oauth2/
+cd ~/fastapi-oauth2/docs/ && npm install && npm run build
+sudo cp -r ~/fastapi-oauth2/docs/.vitepress/dist/ /var/www/docs/fastapi-oauth2/

docs/deploy.sh

@@ -0,0 +1,33 @@
+---
+layout: home
+sidebar: false
+
+title: FastAPI OAuth2
+titleTemplate: OAuth2 authentication with support for several identity providers
+
+hero:
+  name: FastAPI OAuth2
+  text: OAuth2 has never been that simple
+  tagline: Easy to integrate OAuth2 authentication with support for several identity providers.
+  image:
+    src: /logo.png
+    alt: PySnippet
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /integration/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/pysnippet/fastapi-oauth2
+
+features:
+  - icon: 🛠️
+    title: Free and open source
+    details: Enjoy the freedom of our OSS project, giving you full access to its source code and allowing you to contribute to its development.
+  - icon: 🧩
+    title: Easy to integrate
+    details: Incorporate FastAPI OAuth2 into your existing projects with its straightforward integration process, saving you time.
+  - icon: ⚡
+    title: Compatible with FastAPI 0.68.1+
+    details: The package is fully compatible with FastAPI v0.68.1 and above, ensuring smooth operation and integration with your application.
+---