basepath: Provide minimal documentation

docs/middlewares/basepath.rst

@@ -0,0 +1,52 @@
+Basepath
+========
+
+The ``basepath`` middleware allow a better isolation when composing routers by
+stripping a prefix on the :doc:`../vsgi/request` URI.
+
+The middleware strips and forwards requests which match the provided base path.
+If the resulting path is empty, it fallbacks to a root ``/``.
+
+Error which use their message as a ``Location`` header are automatically
+prefixed by the base path.
+
+::
+
+    var user = new Router ();
+
+    user.get ("/<int:id>", (req, res) => {
+        // ...
+    });
+
+    user.post ("/", (req, res) => {
+        throw new Success.CREATED ("/5");
+    });
+
+    app.use (basepath ("/user", user.handle));
+
+    app.status (Soup.Status.CREATED, (req, res) => {
+        assert ("/user/5" == context["message"]);
+    });
+
+If ``next`` is called while forwarding or an error is thrown, the original path
+is restored.
+
+::
+
+    user.get ("/<int:id>", (req, res, next) => { 
+        return next (req, res); // path is '/5'
+    });
+
+    app.use (basepath ("/user", user.handle));
+
+    app.use ((req, res) => {
+        // path is '/user/5'
+    });
+
+One common pattern is to provide a path-based fallback when using the
+:doc:`subdomain` middleware.
+
+::
+
+    app.use (subdomain ("api", api.handle));
+    app.use (basepath ("/api", api.handle));

docs/middlewares/index.rst

@@ -2,5 +2,6 @@ Middlewares
 ===========
 
 .. toctree::
+    basepath
     server-sent-events
     subdomain

src/valum/valum-basepath.vala

@@ -35,7 +35,7 @@ namespace Valum {
 	 *
 	 * @since 0.3
 	 *
-	 * @param path
+	 * @param path    path prefix stripped on forwarded requests
 	 * @param forward callback used to forward the request
 	 */
 	public HandlerCallback basepath (string path, owned HandlerCallback forward) {