From 494085bcd3a47e5a4363e0ba27f6abbb0c65caff Mon Sep 17 00:00:00 2001
From: Dominik Kellner <dkellner@dkellner.de>
Date: Thu, 29 Sep 2016 00:35:45 +0200
Subject: [PATCH] Update documentation for #268 and `rule_filter`

---
 docs/usage.rst            | 26 ++++++++++++++++++++++++++
 docs/validation-rules.rst |  5 ++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/usage.rst b/docs/usage.rst
index e1184c1d..f9934e4b 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -161,6 +161,32 @@ mapping that is checked against the :ref:`schema <schema_dict-rule>` rule:
 .. versionchanged:: 0.8
    ``allow_unknown`` can also be set to a validation schema.
 
+Filter rules
+------------
+You can filter the rules to be processed by a ``Validator``-instance by
+providing a function returning either ``True`` or ``False`` given a rule name.
+
+.. doctest::
+
+   >>> schema = {'name': {'type': 'string', 'maxlength': 10}}
+   >>> v.rule_filter = lambda f: f != 'maxlength'
+   >>> v.validate({'name': 'Johanna-Maria'}, schema)
+   True
+
+Regardless of the ``rule_filter``, the ``Validator`` always recurses down
+subdocuments:
+
+.. doctest::
+
+   >>> schema = {'entries': {'type': 'list', 'schema': {'type': 'integer', 'max': 10}}}
+   >>> v.rule_filter = lambda f: f == 'type'
+   >>> v.validate({'entries': [10, 20, 30]}, schema)
+   True
+
+   >>> schema = {'entries': {'type': 'list', 'schema': {'type': 'integer', 'max': 10}}}
+   >>> v.rule_filter = lambda f: f in ('type', 'max')
+   >>> v.validate({'entries': [10, 20, 30]}, schema)
+   False
 
 Fetching Processed Documents
 ----------------------------
diff --git a/docs/validation-rules.rst b/docs/validation-rules.rst
index e876a103..16366fbe 100644
--- a/docs/validation-rules.rst
+++ b/docs/validation-rules.rst
@@ -425,7 +425,10 @@ readonly
 If ``True`` the value is readonly. Validation will fail if this field is
 present in the target dictionary. This is useful, for example, when receiving
 a payload which is to be validated before it is sent to the datastore. The field
-might be provided by the datastore, but should not writable.
+might be provided by the datastore, but should not be writable.
+
+``readonly`` can be combined with ``default`` because validation of
+``readonly`` is done before normalization.
 
 regex
 -----