add docs for files middlewares

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.

docs/middleware.md → 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

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

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