Create a basic documentation (#705)

Author: nycholas

.readthedocs.yaml

@@ -1,13 +1,10 @@
 version: 2
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: 'latest'
-python:
-  install:
-    - requirements: requirements/docs.txt
-    - method: pip
-      path: .
-sphinx:
-  builder: dirhtml
-  fail_on_warning: true
+    python: '3.13'
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html

bin/cibw-before-build.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (c) 2024-2024, Cenobit Technologies, Inc. http://cenobit.es/
+# Copyright (c) 2024-2025, Cenobit Technologies, Inc. http://cenobit.es/
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without

docs/_static/flask-jsonrpc-icon.svg

@@ -1,4 +1,4 @@
-# Copyright (c) 2012-2024, Cenobit Technologies, Inc. http://cenobit.es/
+# Copyright (c) 2012-2025, Cenobit Technologies, Inc. http://cenobit.es/
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -27,18 +27,21 @@
 from pallets_sphinx_themes import ProjectLink, get_version
 
 project = 'Flask-JSONRPC'
-copyright = '2021-2024, Nycholas de Oliveira e Oliveira'
+copyright = '2021-2025, Cenobit Technologies, Inc. http://cenobit.es/'
 author = 'Nycholas de Oliveira e Oliveira'
 release, version = get_version('Flask-JSONRPC')
 
-master_doc = 'index'
 default_role = 'code'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
     'sphinxcontrib.log_cabinet',
     'sphinx_tabs.tabs',
+    # 'sphinx_autodoc_typehints',
     'pallets_sphinx_themes',
 ]
 autodoc_member_order = 'bysource'
@@ -50,6 +53,7 @@
 extlinks = {
     'issue': ('https://github.com/cenobites/flask-jsonrpc/issues/%s', '#%s'),
     'pr': ('https://github.com/cenobites/flask-jsonrpc/pull/%s', '#%s'),
+    'ghsa': ('https://github.com/cenobites/flask-jsonrpc/security/advisories/GHSA-%s', 'GHSA-%s'),
 }
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
@@ -73,9 +77,13 @@
 }
 singlehtml_sidebars = {'index': ['project.html', 'localtoc.html', 'ethicalads.html']}
 html_static_path = ['_static']
-# html_favicon = '_static/flask-jsonrpc-icon.png'
-# html_logo = '_static/flask-jsonrpc-icon.png'
+html_favicon = '_static/flask-jsonrpc-icon.svg'
+html_logo = '_static/flask-jsonrpc-icon.svg'
 html_title = f'Flask-JSONRPC Documentation ({version})'
 html_show_sourcelink = False
 
-latex_documents = [(master_doc, f'Flask-JSONRPC-{version}.tex', html_title, author, 'manual')]
+gettext_uuid = True
+gettext_compact = False
+autosummary_generate = True
+napoleon_google_docstring = True
+add_module_names = False

docs/_static/flask-jsonrpc-name.png

@@ -0,0 +1,68 @@
+Deployment
+==========
+
+This section covers deploying Flask-JSONRPC services in production environments.
+
+----
+
+WSGI Servers
+------------
+
+Use a WSGI server such as Gunicorn or uWSGI:
+
+.. code-block:: bash
+
+   # Using Gunicorn
+   gunicorn -w 4 -b 0.0.0.0:8000 app:create_app()
+
+.. note::
+
+   Replace ``app:create_app()`` with your factory function if using app factories.
+
+----
+
+Reverse Proxy (Nginx Example)
+-----------------------------
+
+Example configuration for Nginx forwarding to Gunicorn:
+
+.. code-block:: nginx
+
+   server {
+       listen 80;
+       server_name example.com;
+
+       location /api {
+           proxy_pass http://127.0.0.1:8000/api;
+           proxy_set_header Host $host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+       }
+   }
+
+----
+
+HTTPS and Security
+------------------
+
+* Always enable HTTPS in production.
+* Protect sensitive methods with authentication (see :doc:`patterns/auth`).
+* Disable the web explorer in public environments:
+
+.. code-block:: python
+
+   JSONRPC(app, "/api", enable_web_browsable_api=False)
+
+----
+
+Scaling and Multiple Instances
+------------------------------
+
+Use standard Flask/WSGI scaling:
+
+* Multiple Gunicorn workers
+* Load balancer in front (NGINX, HAProxy)
+* Optional horizontal scaling across servers
+
+Flask-JSONRPC methods remain stateless by default. Ensure shared state (like
+databases) is properly configured.

docs/conf.py

@@ -1,20 +1,53 @@
-.. Flask-JSONRPC documentation master file, created by
-   sphinx-quickstart on Wed Jul 14 14:54:46 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. rst-class:: hide-header
 
 Welcome to Flask-JSONRPC's documentation!
 =========================================
 
+.. image:: _static/flask-jsonrpc-name.png
+   :align: center
+   :height: 250px
+
+Flask-JSONRPC brings full **JSON-RPC 2.0** support to your Flask applications.
+It is designed to feel natural to anyone who already knows Flask, and easy to
+learn for those who do not.
+
+Flask-JSONRPC provides:
+
+* a Pythonic decorator-based API for defining JSON-RPC methods
+* automatic request parsing and parameter handling
+* validation based on Python type hints
+* batch request support
+* method namespacing
+* an optional built-in web UI explorer for testing and debugging, `available here <https://flask-jsonrpc.cenobit.es/api/browse/#/>`__
+* an extension system that plays nicely with the Flask ecosystem
+
+Flask-JSONRPC follows the JSON-RPC 2.0 specification and integrates naturally
+with Flask's routing, blueprints, and application factory patterns.
+
+
+User's Guide
+------------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   installation
+   quickstart
+
+   tutorial/index
 
+   usage/methods
+   usage/params
+   usage/types
+   usage/blueprints
+   usage/batch
+   usage/errors
+   usage/explorer
 
-Indices and tables
-==================
+   patterns/factories
+   patterns/auth
+   patterns/validation
+   patterns/marshaling
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   testing
+   deployment

docs/deployment.rst

@@ -0,0 +1,38 @@
+Installation
+============
+
+Flask-JSONRPC is available on PyPI and supports modern versions of Python and
+Flask.
+
+Requirements
+------------
+
+* Python 3.10 or later
+* Flask 3.x or later
+
+Installation
+------------
+
+Install using pip:
+
+.. code-block:: bash
+
+   pip install Flask-JSONRPC
+
+Verifying the Installation
+--------------------------
+
+You can verify that Flask-JSONRPC is installed by running:
+
+.. code-block:: bash
+
+   python -c "import flask_jsonrpc; print(flask_jsonrpc.__version__)"
+
+Upgrading
+---------
+
+To upgrade to the latest version:
+
+.. code-block:: bash
+
+   pip install --upgrade Flask-JSONRPC

docs/index.rst

@@ -0,0 +1,43 @@
+Authentication Patterns
+=======================
+
+Flask-JSONRPC does not include built-in authentication. Use Flask patterns to
+secure your endpoints.
+
+----
+
+Token-based Authentication
+--------------------------
+
+You can require a token in request headers:
+
+.. code-block:: python
+
+   from flask import request
+   from flask_jsonrpc.exceptions import JSONRPCError
+
+   @jsonrpc.method("secret.echo")
+   def echo(message: str):
+       token = request.headers.get("X-Auth-Token")
+       if token != "my-secret":
+           raise JSONRPCError(code=401, message="Unauthorized")
+       return message
+
+----
+
+JWT Authentication (Optional Extension)
+---------------------------------------
+
+.. code-block:: python
+
+   import jwt
+
+   SECRET_KEY = "supersecret"
+
+   @jsonrpc.method("auth.verify")
+   def verify(token: str):
+       try:
+           payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
+       except jwt.InvalidTokenError:
+           raise JSONRPCError(code=401, message="Invalid token")
+       return payload

docs/installation.rst

@@ -0,0 +1,39 @@
+Application Factories
+=====================
+
+Flask recommends using **application factories** for flexibility and testability.
+Flask-JSONRPC integrates naturally with this pattern.
+
+----
+
+Creating an Application Factory
+-------------------------------
+
+.. code-block:: python
+
+   from flask import Flask
+   from flask_jsonrpc import JSONRPC
+
+   def create_app(config=None):
+       app = Flask(__name__)
+       if config:
+           app.config.update(config)
+
+       # JSON-RPC endpoint
+       jsonrpc = JSONRPC(app, "/api", enable_web_browsable_api=True)
+
+       # Example method
+       @jsonrpc.method("ping")
+       def ping():
+           return "pong"
+
+       return app
+
+----
+
+Benefits
+--------
+
+* Easy testing (create multiple app instances)
+* Clean separation between app and extensions
+* Works with blueprints and modular JSON-RPC endpoints