docs: add Sphinx documentation site and prepare 0.1.3 release (#1)

Add the Sphinx docs site and Read the Docs config, fix docs accuracy,
and bump the version to 0.1.3. No runtime behaviour changes.

Author: LJFCoding

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.3
+
+- Add a Sphinx documentation site with installation, quick start,
+  configuration, examples and API reference pages.
+- Configure Read the Docs to build the documentation from the repository.
+- Add the documentation URL to package metadata.
+
 ## 0.1.2
 
 - Clear the request-cached GitHubKit client on logout, so logging out

README.md

@@ -4,6 +4,8 @@ A Flask extension for GitHub OAuth login, built on
 [GitHubKit](https://github.com/yanyongyu/githubkit). It handles expiring-token
 refresh and stores tokens in `flask.session`.
 
+Documentation: [flask-githubkit.readthedocs.io](https://flask-githubkit.readthedocs.io/en/latest/)
+
 ## Installation
 
 Install the latest release from PyPI:
@@ -15,8 +17,8 @@ pip install flask-githubkit
 To pin a release or install directly from GitHub:
 
 ```console
-pip install "flask-githubkit==0.1.2"
-pip install "flask-githubkit @ git+https://github.com/LJFCoding/flask-githubkit.git@v0.1.2"
+pip install "flask-githubkit==0.1.3"
+pip install "flask-githubkit @ git+https://github.com/LJFCoding/flask-githubkit.git@v0.1.3"
 ```
 
 It requires Python 3.10+ and installs Flask, GitHubKit and httpx.
@@ -116,15 +118,15 @@ def create_app():
 
 ## Examples
 
-Each file in [examples/](examples) is a complete app. They are checked by the
+Each file in [examples/](https://github.com/LJFCoding/flask-githubkit/tree/main/examples) is a complete app. They are checked by the
 test suite, which confirms the login route redirects to GitHub.
 
 | File | Shows |
 | --- | --- |
-| [single_file.py](examples/single_file.py) | A module-level app with `GitHub(app)` |
-| [factory.py](examples/factory.py) | An app factory with `init_app` and the optional config keys |
-| [blueprint.py](examples/blueprint.py) | Login routes in a blueprint; the `auth.login` endpoint is found from `@github.login` |
-| [routes.py](examples/routes.py) | A `login_required` decorator and a route that calls the GitHub API |
+| [single_file.py](https://github.com/LJFCoding/flask-githubkit/blob/main/examples/single_file.py) | A module-level app with `GitHub(app)` |
+| [factory.py](https://github.com/LJFCoding/flask-githubkit/blob/main/examples/factory.py) | An app factory with `init_app` and the optional config keys |
+| [blueprint.py](https://github.com/LJFCoding/flask-githubkit/blob/main/examples/blueprint.py) | Login routes in a blueprint; the `auth.login` endpoint is found from `@github.login` |
+| [routes.py](https://github.com/LJFCoding/flask-githubkit/blob/main/examples/routes.py) | A `login_required` decorator and a route that calls the GitHub API |
 
 Set `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` and `SECRET_KEY` in your
 environment, then run one with, for example,
@@ -177,7 +179,7 @@ github = flask_githubkit.GitHub(
   OAuth flow. You can also call `github.login()` inside a view and return
   the result, which is useful if you want to run code first. The decorated
   function's body never runs.
-- `@callback` wraps the callback view.
+- `@github.callback` wraps the callback view.
 - `client()` returns the request-cached GitHubKit `GitHub` client, or `None`
   when there is no valid stored token.
 - `logout()` removes the stored GitHub token from the session.

docs/_static/custom.css

@@ -0,0 +1,7 @@
+.rst-content code.literal,
+.rst-content tt.literal,
+.rst-content .sig-name,
+.rst-content .sig-prename,
+.rst-content .sig-param {
+    color: #333333;
+}

docs/api.md

@@ -0,0 +1,53 @@
+# API reference
+
+The package's public imports are `GitHub`, `Config` and `Token`:
+
+```python
+import flask_githubkit
+
+github = flask_githubkit.GitHub()
+```
+
+Most applications only need `GitHub`. The extension handles callback
+state validation, code exchange and token persistence. Application code
+uses `github.client()` to make GitHub API calls.
+
+## `GitHub`
+
+The generated reference below documents the public extension methods
+and their signatures.
+
+```{eval-rst}
+.. autoclass:: flask_githubkit.GitHub
+   :members: init_app, login, callback, client, logout
+```
+
+### Callback behavior
+
+`@github.callback` checks and consumes the one-time OAuth `state` value
+before calling the decorated view. Invalid or replayed state returns
+HTTP 400 and the view is not called. If the user denies authorization,
+the view receives `None`. When the exchange succeeds, the view receives
+the access token as its first argument.
+
+If GitHub redirects back without an authorization code, the extension
+returns HTTP 400. Network failures while exchanging the code return HTTP 502. If the
+GitHubKit client later raises `AuthExpiredError`, the extension clears
+the token and redirects to the configured or discovered login endpoint.
+
+## `Config`
+
+`Config.from_current_app()` reads the OAuth client ID, client secret,
+redirect URI, scope and Flask `SECRET_KEY` from the active Flask app.
+It returns `None` when required configuration is missing or invalid.
+Most applications do not need to construct or call `Config` directly.
+
+## `Token`
+
+`Token` serializes and restores the GitHubKit OAuth token strategy in
+`flask.session`. Application code normally uses `GitHub.callback`,
+`GitHub.client()` and `GitHub.logout()` instead of calling `Token`
+directly.
+
+For GitHubKit's complete API, see its
+[REST API documentation](https://yanyongyu.github.io/githubkit/).

docs/conf.py

@@ -0,0 +1,19 @@
+project = "flask-githubkit"
+author = "LJFCoding"
+release = "0.1.3"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+]
+
+root_doc = "index"
+myst_heading_anchors = 3
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]

docs/configuration.md

@@ -0,0 +1,106 @@
+# Configuration
+
+The extension reads OAuth credentials from the active Flask application's
+config. Configure the app before serving requests.
+
+## Flask configuration
+
+| Key | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `SECRET_KEY` | Yes | — | Flask session signing key. Keep it secret and stable. |
+| `GITHUB_CLIENT_ID` | Yes | — | Client ID from your GitHub OAuth App. |
+| `GITHUB_CLIENT_SECRET` | Yes | — | Client secret from your GitHub OAuth App. |
+| `GITHUB_REDIRECT_URI` | Yes | — | Absolute callback URL registered with the OAuth App. |
+| `GITHUB_SCOPE` | No | `read:user` | Space-separated OAuth scopes requested at login. |
+| `GITHUB_LOGIN_VIEW` | No | Decorated login view, otherwise `login` | Flask endpoint to use when a refresh token has expired. |
+
+The client ID, client secret, redirect URI, scope and `SECRET_KEY` must be
+non-empty strings. If any is missing or empty, the login route returns a
+JSON error with HTTP 500, the callback route returns the same error once its
+`state` check passes, and `github.client()` returns `None`.
+
+## Initialize the extension
+
+For a single app, pass the app to the extension:
+
+```python
+github = flask_githubkit.GitHub(app)
+```
+
+For an application factory, create the extension without an app and call
+`init_app` when the app is created:
+
+```python
+github = flask_githubkit.GitHub()
+
+
+def create_app():
+    app = flask.Flask(__name__)
+    app.config.from_mapping(...)
+    github.init_app(app)
+    return app
+```
+
+See [application factory and Blueprint examples](examples.md).
+
+## Scope and login endpoint overrides
+
+The constructor accepts optional `scope` and `login_view` keyword
+arguments:
+
+```python
+github = flask_githubkit.GitHub(
+    scope="read:user repo",
+    login_view="auth.login",
+)
+```
+
+For either option, the constructor value takes precedence over its Flask
+config key. If no scope is supplied, the default is `read:user`. If no
+login endpoint is supplied, the extension looks for a route decorated
+with `@github.login` and uses its Flask endpoint. This works with
+Blueprints (for example, `auth.login`). If no decorated route exists, it
+uses the endpoint named `login`.
+
+`login_view` is an endpoint name used by `flask.url_for`, not a URL path.
+Most apps do not need to set it when they decorate their login route with
+`@github.login`.
+
+Scopes determine what user access the OAuth App requests. Request only
+the access your app needs. GitHub's OAuth scope behavior is documented
+in the [GitHub OAuth scopes guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps).
+
+## Session storage
+
+Tokens are stored in `flask.session`. The extension marks the session
+permanent when it saves tokens, but does not select or configure a
+session backend or its expiration policy.
+
+Flask's default session is a signed client-side cookie; it is **not
+encrypted**, so users can read its contents. For production, use a
+server-side session backend, such as Flask-Session with Redis, and
+configure the backend and session lifetime for your application.
+Sliding expiry and TTL behavior depend on that backend.
+
+## Token refresh
+
+Enable **Expire user authorization tokens** in the GitHub OAuth App if
+you want expiring access tokens and refresh tokens. GitHubKit refreshes
+an expired access token when an API request uses the client.
+flask-githubkit writes the updated token values back to the session after
+the request.
+
+GitHub refresh tokens are single-use. Concurrent requests using the same
+expired token can race; this extension does not provide a distributed
+lock. A deployment that needs coordination across workers must implement
+that policy in its own storage or infrastructure.
+
+## Limitations
+
+- Only synchronous Flask applications and GitHub OAuth Apps are supported.
+  GitHub Apps and GitHub Enterprise endpoints are not configurable.
+- Real GitHub code exchange and token refresh, Redis, and Flask-Session TTL
+  behavior are not verified by the automated tests. Test them against those
+  services before relying on them in production.
+- Errors raised by your own API calls, such as network failures, are not
+  caught by the extension.

docs/examples.md

@@ -0,0 +1,62 @@
+# Examples
+
+The complete, runnable apps live in the repository's
+[`examples/` directory](https://github.com/LJFCoding/flask-githubkit/tree/main/examples).
+The test suite smoke-tests these examples so documentation snippets do
+not have to be maintained separately.
+
+## Single-file application
+
+Use this pattern for a small app with a module-level Flask application.
+`GitHub(app)` initializes the extension immediately:
+
+```{literalinclude} ../examples/single_file.py
+:language: python
+```
+
+Run it from the repository root after setting `SECRET_KEY`,
+`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`:
+
+```console
+flask --app examples/single_file run
+```
+
+## Application factory
+
+An application factory creates the Flask app inside a function. This
+pattern is useful for tests, multiple app configurations, and larger
+projects. Create the extension once, then call `init_app(app)` inside
+the factory:
+
+```{literalinclude} ../examples/factory.py
+:language: python
+```
+
+## Blueprint
+
+Blueprints give routes an endpoint prefix. In the following example,
+the login endpoint is `auth.login`. The extension discovers this from
+`@github.login`, so no `GITHUB_LOGIN_VIEW` setting is needed:
+
+```{literalinclude} ../examples/blueprint.py
+:language: python
+```
+
+The callback URL registered with GitHub must include the Blueprint
+prefix, for example `http://localhost:5000/auth/callback`.
+
+## Call the API from a route
+
+`github.client()` returns a GitHubKit client for the signed-in user, or
+`None` when no token is available. Use the client's typed REST methods:
+
+```{literalinclude} ../examples/routes.py
+:language: python
+```
+
+Prefer API calls over reading the access token directly. If server-side
+integration code needs the token, it is available as
+`client.auth.token`. It is a bearer credential: do not return it to the
+browser, include it in a URL, or write it to logs. An API request may
+refresh the token, so read the value after using the client if you need
+the refreshed credential.

docs/index.md

@@ -0,0 +1,54 @@
+# flask-githubkit
+
+**GitHub OAuth for Flask, with GitHubKit's typed API client.**
+
+`flask-githubkit` connects Flask routes to GitHub's OAuth flow and API. It
+validates the OAuth callback's `state`, stores user tokens in the Flask
+session, and saves refreshed token values after API calls.
+
+```python
+@app.route("/login")
+@github.login
+def login():
+    """Redirect the user to GitHub."""
+
+
+@app.route("/callback")
+@github.callback
+def callback(access_token):
+    if access_token is None:
+        return "GitHub authorization was denied.", 401
+    return flask.redirect(flask.url_for("profile"))
+```
+
+## What you get
+
+- A GitHub OAuth login flow designed for Flask.
+- Callback state validation to protect against login CSRF.
+- GitHubKit's typed REST API client, cached for the current request.
+- Automatic refresh of expiring user tokens when the client is used, with
+  refreshed tokens saved back to the Flask session.
+- Support for Flask application factories and Blueprints.
+- A small synchronous API: `@github.login`, `@github.callback`,
+  `github.client()` and `github.logout()`.
+
+Token refresh requires a GitHub OAuth App configured to issue expiring user
+authorization tokens. GitHub refresh tokens are single-use, so simultaneous
+requests can race while refreshing. Flask's default session cookie is signed
+but not encrypted; see [session security](configuration.md).
+
+## Start here
+
+```{toctree}
+:maxdepth: 2
+
+installation
+quickstart
+configuration
+examples
+api
+```
+
+For GitHubKit's REST methods and other client features, see the
+[GitHubKit documentation](https://yanyongyu.github.io/githubkit/). This
+extension currently supports synchronous Flask applications.