📖 🐈 Switch to Sphinx for Documentation (HarryMWinters#8)

- Switch to Sphinx for documentation.
- Update Readme to point to ReadTheDocs and PyPI
- Remove unused publish docs task

Author: HarryMWinters

.github/workflows/publish_docs.yaml

@@ -2,15 +2,31 @@
 
 # FastAPI OIDC
 
-![Tests](https://github.com/HarryMWinters/fastapi-oidc/workflows/Test/badge.svg)
+<p align="center">
+    <a href="https://github.com/HarryMWinters/fastapi-oidc/actions?query=workflow%3ATest"
+       target="_blank">
+       <img src="https://github.com/HarryMWinters/fastapi-oidc/workflows/Test/badge.svg"  
+            alt="Test">
+    </a>
+    <a href='https://fastapi-oidc.readthedocs.io/en/latest/?badge=latest'>
+        <img src='https://readthedocs.org/projects/fastapi-oidc/badge/?version=latest' alt='Documentation Status' />
+    </a>
+    <a href="https://pypi.org/project/fastapi-oidc" 
+       target="_blank">
+       <img src="https://img.shields.io/pypi/v/fastapi-oidc?color=%2334D058&label=pypi%20package" 
+            alt="Package version">
+    </a>
+</p>
+
+---
 
 :warning: **See [this issue](https://github.com/HarryMWinters/fastapi-oidc/issues/1) for simple role-your-own example of checking OIDC tokens.**
 
 Verify and decrypt 3rd party OIDC ID tokens to protect your [fastapi](https://github.com/tiangolo/fastapi) endpoints.
 
-Docs: [gh-Pages](https://harrymwinters.github.io/fastapi-oidc/)
+**Documentation:** [ReadTheDocs](https://fastapi-oidc.readthedocs.io/en/latest/)
 
-Source code: [Github](https://github.com/HarryMWinters/fastapi-oidc)
+**Source code:** [Github](https://github.com/HarryMWinters/fastapi-oidc)
 
 ### Installation
 

README.md

@@ -30,9 +30,7 @@
 # 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",
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/conf.py

@@ -24,6 +24,12 @@ Installation
 .. code-block:: bash
 
    pip install fastapi-oidc
+   
+Or, if you you're feeling hip...
+
+.. code-block:: bash
+
+   poetry add fastapi-oidc
 
 Example
 -------
@@ -55,12 +61,16 @@ Basic configuration for verifying OIDC tokens.
       return {"Hello": "World", "user_email": id_token.email}
 
 
-API References
---------------
+API Reference
+=============
 
-.. automodule:: fastapi_oidc
+Auth
+----
+
+.. automodule:: fastapi_oidc.auth
    :members:
 
+
 Discovery
 ---------
 

docs/index.rst

@@ -1 +0,0 @@
-"""Place holder for working with 3rd party OIDC ID tokens in fastapi """

fastapi_oidc/__init__.py

@@ -1,15 +1,23 @@
 # -*- coding: utf-8 -*-
 """
 Module for validating OIDC ID Tokens. Configured via config.py 
-#. Usage
+
+Usage
+=====
+
 .. code-block:: python3
-    from app.auth import authenticate_user
+
+    # This assumes you've already configured get_auth in your_app.py
+    from you_app.auth import authenticate_user
+
     @app.get("/auth")
     def test_auth(authenticated_user: AuthenticatedUser = Depends(authenticate_user)):
         name = authenticated_user.preferred_username
         return f"Hello {name}"
 """
 
+from typing import Callable
+
 from fastapi import Depends
 from fastapi import HTTPException
 from fastapi.security import OpenIdConnect
@@ -28,8 +36,28 @@ def get_auth(
     base_authorization_server_uri: str,
     issuer: str,
     signature_cache_ttl: int,
-):
+) -> Callable[[str], IDToken]:
+    """Take configurations and return the authenticate_user function.
+
+    This function should only be invoked once at the begging of your
+    server code. The function it returns should be used to check user credentials.
+
+    Args:
+        client_id (str): This string is provided when you register with your resource server.
+        base_authorization_server_uri(URL): Everything before /.wellknow in your auth server URL.
+            I.E. https://dev-123456.okta.com
+        issuer (URL): Same as base_authorization. This is used to generating OpenAPI3.0 docs which
+            is broken (in OpenAPI/FastAPI) right now.
+        signature_cache_ttl (int): How many seconds your app should cache the authorization
+            server's public signatures.
 
+
+    Returns:
+        func: authenticate_user(auth_header: str)
+
+    Raises:
+        Nothing intentional
+    """
     # As far as I can tell this does two things.
     # 1. Extracts and returns the Authorization header.
     # 2. Integrates with the OpenAPI3.0 doc generation in FastAPI.
@@ -41,19 +69,17 @@ def get_auth(
 
     discover = discovery.configure(cache_ttl=signature_cache_ttl)
 
-    def authenticate_user(
-        auth_header: str = Depends(oauth2_scheme),
-        client_id: str = client_id,
-        base_authorization_server_uri: str = base_authorization_server_uri,
-        issuer: str = issuer,
-        signature_cache_ttl: int = signature_cache_ttl,
-    ) -> IDToken:
+    def authenticate_user(auth_header: str = Depends(oauth2_scheme)) -> IDToken:
         """Validate and parse OIDC ID token against issuer in config.
         Note this function caches the signatures and algorithms of the issuing server
         for signature_cache_ttl seconds.
 
-        return:
-            IDToken:
+        Args:
+            auth_header (str): Base64 encoded OIDC Token. This is invoked behind the scenes
+                by Depends.
+
+        Return:
+            IDToken (types.IDToken):
 
         raises:
             HTTPException(status_code=401, detail=f"Unauthorized: {err}")
@@ -80,3 +106,21 @@ def authenticate_user(
             raise HTTPException(status_code=401, detail=f"Unauthorized: {err}")
 
     return authenticate_user
+
+
+# This is a dummy method for sphinx docs. DO NOT User.
+# TODO Find a way to doc higher order functions w/ sphinx.
+def authenticate_user(auth_header: str) -> IDToken:
+    """
+    Validate and parse OIDC ID token against issuer in config.
+    Note this function caches the signatures and algorithms of the issuing server
+    for signature_cache_ttl seconds.
+
+    Args:
+        auth_header (str): Base64 encoded OIDC Token. This is invoked behind the scenes
+            by Depends.
+
+    Return:
+        IDToken (types.IDToken):
+    """
+    pass

fastapi_oidc/auth.py

@@ -7,7 +7,7 @@ license = "MIT"
 readme = "README.md"
 homepage = "https://github.com/HarryMWinters/fastapi-oidc"
 repository = "https://github.com/HarryMWinters/fastapi-oidc"
-documentation = "https://github.com/HarryMWinters/fastapi-oidc"
+documentation = "https://fastapi-oidc.readthedocs.io/en/latest/"
 
 [tool.poetry.dependencies]
 python = "^3.8"