docs: Add custom filter example

Author: SilverRainZ

docs/conf.py

@@ -164,3 +164,4 @@ def setup(app):
     __import__('test-base-context-directive-example.conf').conf.setup(app)
     __import__('test-base-data-define-directive-example.conf').conf.setup(app)
     __import__('test-strict-data-define-directive-example.conf').conf.setup(app)
+    __import__('test-filter-example.conf').conf.setup(app)

docs/ext.rst

@@ -94,13 +94,31 @@ The decorated class must be one of the following classes:
 
 .. _ext-filters:
 
-Extending Filters
+Extending ilters
 =================
 
 Template filters are registered by a
 :py:deco:`sphinxnotes.render.filter` function decorator.
 
-TODO
+The decorated function takes a :py:class:`sphinx.environment.BuildEnvironment`
+as argument and returns a filter function.
+
+.. note::
+
+   The decorator is used to **decorate the filter function factory, NOT
+   the filter function itself**.
+
+.. literalinclude:: ../tests/roots/test-filter-example/conf.py
+   :language: python
+   :start-after: [literalinclude start]
+   :end-before: [literalinclude end]
+
+.. example::
+   :style: grid
+
+   .. data.render::
+
+      {{ "Hello world" | catify }}
 
 .. _ext-directives:
 .. _ext-roles:

tests/roots/test-filter-example/conf.py

@@ -0,0 +1,20 @@
+from sphinxnotes.render import filter
+from sphinx.environment import BuildEnvironment
+
+
+# [literalinclude start]
+@filter('catify')
+def catify(_: BuildEnvironment):
+    """Speak in a cat-like tone"""
+
+    def _filter(value: str) -> str:
+        return value + ", meow~"
+
+    return _filter
+# [literalinclude end]
+
+
+extensions = ['sphinxnotes.render.ext']
+
+
+def setup(app): ...

tests/roots/test-filter-example/index.rst

@@ -0,0 +1,6 @@
+test filter
+============
+
+.. data.render::
+
+   {{ "I love you" | catify }}

tests/test_e2e.py

@@ -3,6 +3,14 @@
 import pytest
 
 
+@pytest.mark.sphinx('html', testroot='filter-example')
+def test_custom_filter(app, status, warning):
+    app.build()
+
+    html = (app.outdir / 'index.html').read_text(encoding='utf-8')
+
+    assert 'I love you, meow~' in html
+
 @pytest.mark.sphinx('html', testroot='strict-data-define-directive-example')
 def test_strict_data_define_directive(app, status, warning):
     app.build()