Add wizard.sql.auth function and plugin, refresh docs.

[wizard.git] / doc / plugin.rst

diff --git a/doc/plugin.rst b/doc/plugin.rst
index c30fc5df4deba002a1ab9133c45039e2ea985b53..fb6e418bc1056711ca129a3848bd6c9f34e9a5e8 100644 (file)
--- a/doc/plugin.rst
+++ b/doc/plugin.rst
@@ -45,19 +45,30 @@ For more information on how to create an application, check
 
     Plugins marked with prototype todo messages are not complete yet.
 
+.. _wizard.strategy:
+
 ``wizard.strategy``
 -------------------
 
 Used during installation to automatically determine values for
 installation parameters the user may have omitted.
 
+.. _wizard.sql.auth:
+
 ``wizard.sql.auth``
 --------------------
 
 Used to fill in a user's database authentication credentials if none are
-able to be determined from an application's configuration files.
+able to be determined from an application's configuration files.  Plugin
+should be a function that takes a single required argument ``url``,
+which is a :class:`sqlalchemy.engine.url.URL` with partial
+authentication information, including a database name, and should return either
+``None`` if it was unable to fill in authentication credentials for the
+user, or the completed URL.  Mutating the passed argument and then
+returning it is the expected modus operandi of a plugin.  The function
+that runs this plugin is :func:`wizard.sql.auth`.
 
-.. todo:: Prototype
+.. _wizard.deploy.web:
 
 ``wizard.deploy.web``
 ---------------------
@@ -67,7 +78,10 @@ an application's configuration files.  Plugin should be a function that
 takes a single required argument ``dir``, which is the directory to
 determint the web URL(s) for, and return a list or generator of
 :class:`urlparse.ParseResult` objects or URL strings of possible web locations
-for an application.
+for an application.  The function that runs this plugin is
+:func:`wizard.deploy.web`.
+
+.. _wizard.user.email:
 
 ``wizard.user.email``
 ---------------------
@@ -78,6 +92,8 @@ canonical form we recommend taking advantage of it.
 
 .. todo:: Prototype
 
+.. _wizard.user.operator:
+
 ``wizard.user.operator``
 ------------------------
 
@@ -88,6 +104,8 @@ information we recommend taking advantage of it.
 
 .. todo:: Prototype
 
+.. _wizard.user.passwd:
+
 ``wizard.user.passwd``
 ----------------------
 
@@ -98,6 +116,8 @@ alternative ``passwd`` lookup.
 
 .. todo:: Prototype
 
+.. _wizard.user.quota:
+
 ``wizard.user.quota``
 ---------------------
 
@@ -108,4 +128,5 @@ highly system dependent.  Use this hook to implement quota usage and
 limit reporting.  Plugin should be a function that takes a single
 required argument ``dir``, which is the directory to determine the quota
 for, and return a tuple ``(quota usage, quota limit)`` or ``(0, None)``
-if it could not determine quota.
+if it could not determine quota.  The function that runs this plugin is
+:func:`wizard.user.quota`.