From 50a3314f5d466754c7fbd1b75b54a3b6a81cba5e Mon Sep 17 00:00:00 2001
From: Livio Ribeiro <livioribeiro@outlook.com>
Date: Tue, 8 Oct 2024 08:51:52 -0300
Subject: [PATCH] add docs for files middlewares

---
 docs/extensions/overview.md                   |  2 +-
 .../{middleware.md => middleware/overview.md} |  2 +-
 docs/middleware/staticfiles_uploads.md        | 57 +++++++++++++++++++
 mkdocs.yml                                    |  6 +-
 4 files changed, 63 insertions(+), 4 deletions(-)
 rename docs/{middleware.md => middleware/overview.md} (97%)
 create mode 100644 docs/middleware/staticfiles_uploads.md

diff --git a/docs/extensions/overview.md b/docs/extensions/overview.md
index 905cd46..1061e2c 100644
--- a/docs/extensions/overview.md
+++ b/docs/extensions/overview.md
@@ -1,4 +1,4 @@
-# Overview
+# Extensions
 
 Extensions are python packages that provide additional functionality or integrate
 external libraries into the framework.
diff --git a/docs/middleware.md b/docs/middleware/overview.md
similarity index 97%
rename from docs/middleware.md
rename to docs/middleware/overview.md
index a6ab758..30a5b7c 100644
--- a/docs/middleware.md
+++ b/docs/middleware/overview.md
@@ -1,6 +1,6 @@
 # Middleware
 
-The middleware pipeline is configured with the `MIDDLEWARE` configuration property. It must contain a list of classes
+The middleware pipeline is configured with the `middleware` configuration property. It must contain a list of classes
 that inherit from `selva.web.middleware.Middleware`.
 
 ## Usage
diff --git a/docs/middleware/staticfiles_uploads.md b/docs/middleware/staticfiles_uploads.md
new file mode 100644
index 0000000..bc2c44b
--- /dev/null
+++ b/docs/middleware/staticfiles_uploads.md
@@ -0,0 +1,57 @@
+# Static and uploaded files
+
+The `StaticFilesMiddleware` and `UploadedFilesMiddleware` provide a way of serving
+static content and user uploaded files.
+
+There are two separate middlewares to allow distinct handling in the middleware
+pipeline. For example, you could set the uploaded files to be served after authorization,
+while the static files remain publicly accessible.
+
+## Usage
+
+First you need to activate the middlewares in the `settings.yaml`
+
+```yaml
+middleware:
+  # ...
+  - selva.web.middleware.files.StaticFilesMiddleware
+  - selva.web.middleware.files.UploadedFilesMiddleware
+  # ...
+```
+
+After that, files located in the directories `resources/static` and `resources/uploads`
+will be served at `/static/` and `/uploads/`, respectively.
+
+## Static files mappings
+
+You can map specific paths to single static files in order to, for example, serve
+the favicon at `/favicon.ico` pointing to a file in `resources/static/`:
+
+```yaml
+middleware:
+  - selva.web.middleware.files.StaticFilesMiddleware
+staticfiles:
+  mappings:
+    favicon.ico: my-icon.ico
+```
+
+## Configuration options
+
+The available options to configure the `StaticFilesMiddleware` and `UploadedFilesMiddleware`
+are shown below:
+
+```yaml
+staticfiles:
+    path: /static # (1)
+    root: resources/static # (2)
+    mappings: {}
+
+uploadedfiles:
+    path: /uploads # (3)
+    root: resources/uploads # (4)
+```
+
+1.  Path where static files are served
+2.  Directory where static files are located
+3.  Path where uploaded files are served
+4.  Directory where uploaded files are located
diff --git a/mkdocs.yml b/mkdocs.yml
index bcea0b7..7c94bb4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -47,10 +47,12 @@ nav:
   - routing.md
   - templates.md
   - configuration.md
-  - middleware.md
   - logging.md
+  - Middleware:
+    - Overview: middleware/overview.md
+    - middleware/staticfiles_uploads.md
   - Extensions:
-    - extensions/overview.md
+    - Overview: extensions/overview.md
     - extensions/sqlalchemy.md
     - extensions/redis.md
     - extensions/jinja.md