Updated the documentation

docs/conf.py

@@ -21,7 +21,7 @@
 version = v.base_version
 release = v.public
 
-language = None
+language = "en"
 
 exclude_patterns = ["_build"]
 pygments_style = "sphinx"
@@ -35,7 +35,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "asphalt": ("https://asphalt.readthedocs.org/en/latest/", None),
-    "jinja2": ("https://jinja.pocoo.org/docs/dev/", None),
+    "jinja2": ("https://jinja.octoprint.org/", None),
     "mako": ("https://docs.makotemplates.org/en/latest/", None),
     "tornado": ("https://www.tornadoweb.org/en/stable/", None),
 }

docs/configuration.rst

@@ -10,7 +10,6 @@ box:
 * :mod:`~asphalt.templating.renderers.django`
 * :mod:`~asphalt.templating.renderers.jinja2`
 * :mod:`~asphalt.templating.renderers.mako`
-* :mod:`~asphalt.templating.renderers.tonnikala`
 * :mod:`~asphalt.templating.renderers.tornado`
 
 Other backends may be provided by other components.
@@ -22,57 +21,58 @@ for the backend class::
     components:
       templating:
         backend: mako
-        package_paths:
-          - myapp.somepackage/templates
+        options:
+          package_paths:
+            - myapp.somepackage/templates
 
-This configuration publishes a :class:`asphalt.templating.api.TemplateRenderer` lazy resource
-named ``default`` using the Mako backend, accessible as ``ctx.mako``. The renderer will look for
-templates in the ``templates`` subdirectory of the ``myapp.somepackage`` package.
+This configuration publishes a :class:`asphalt.templating.api.TemplateRenderer` lazy
+resource named ``default`` using the Mako backend. The renderer will look for templates
+in the ``templates`` subdirectory of the ``myapp.somepackage`` package.
 
-The same can be done directly in Python code as follows::
+The same can be done directly in Python code as follows:
+
+.. code-block:: python
 
     class ApplicationComponent(ContainerComponent):
-        async def start(ctx: Context):
-            self.add_component('templating', backend='mako',
-                               package_paths=['myapp.somepackage/templates'])
+        async def start(ctx: Context) -> None:
+            self.add_component(
+                "templating",
+                backend="mako",
+                options={"package_paths": ['myapp.somepackage/templates']}
+            )
             await super().start()
 
 
 Multiple renderers
 ------------------
 
-If you need to configure multiple renderers, you can do so by using the ``renderers``
-configuration option::
+If you need to configure multiple renderers, you will need to use multiple instances
+of the templating component::
 
     components:
       templating:
-        renderers:
-          django:
-            package_paths:
-              - myapp.somepackage/templates/django
-          jinja2:
-            package_name: myapp.somepackage
-            package_path: templates/jinja2
-          mako:
-            package_paths:
-              - myapp.somepackage/templates/mako
-          tonnikala:
-            package_paths:
-              - myapp.somepackage/templates/tonnikala
-          tornado:
-            package_path: myapp.somepackage/templates/tornado
-          foobar:
-            backend: jinja2
-            context_attr: foo
-            package_name: myapp.somepackage
-            package_path: templates/jinja2
-
-The above configuration creates 5 lazy resources of type
-:class:`asphalt.templating.api.TemplateRendererProxy`:
-
-* ``django`` as ``ctx.django``
-* ``jinja2`` as ``ctx.jinja2``
-* ``mako`` as ``ctx.mako``
-* ``tonnikala`` as ``ctx.tonnikala``
-* ``tornado`` as ``ctx.tornado``
-* ``foobar`` as ``ctx.foo``
+        backend: django
+        options:
+          package_paths:
+            - myapp.somepackage/templates/django
+      templating2:
+        type: templating
+        backend: jinja2
+        resource_name: jinja2
+        options:
+          package_name: myapp.somepackage
+          package_path: templates/jinja2
+      templating3:
+        type: templating
+        backend: mako
+        resource_name: mako
+        options:
+          package_paths:
+            - myapp.somepackage/templates/mako
+
+The above configuration creates 3 lazy resources of type
+:class:`asphalt.templating.api.TemplateRenderer`:
+
+* ``default`` (the Django renderer)
+* ``jinja2`` (the Jinja 2 renderer)
+* ``mako`` (the Mako renderer)

docs/extending.rst

@@ -1,24 +1,21 @@
 Writing new renderer backends
 =============================
 
-If you wish to implement an alternate method of template rendering, you can do so by subclassing
-the :class:`~asphalt.templating.api.TemplateRenderer` class.
-There is only one method implementors must override:
+.. highlight:: toml
+
+If you wish to implement an alternate method of template rendering, you can do so by
+subclassing the :class:`~asphalt.templating.api.TemplateRenderer` class.
+There are two methods implementors must override:
 
 * :meth:`~asphalt.templating.api.TemplateRenderer.render`
+* :meth:`~asphalt.templating.api.TemplateRenderer.render_string`
 
 If you want your renderer to be available as a backend for
-:class:`~asphalt.templating.component.TemplatingComponent`, you need to add the corresponding
-entry point for it. Suppose your serializer class is named ``AwesomeRenderer``, lives in the
-package ``foo.bar.awesome`` and you want to give it the alias ``awesome``, add this line to your
-project's ``setup.py`` under the ``entry_points`` argument in the ``asphalt.templating.renderers``
-namespace::
+:class:`~asphalt.templating.component.TemplatingComponent`, you need to add the
+corresponding entry point for it. Suppose your template renderer class is named
+``AwesomeRenderer``, lives in the package ``foo.bar.awesome`` and you want to give it
+the alias ``awesome``, add this line to your project's ``pyproject.toml`` under the
+``entry_points`` argument in the ``asphalt.templating.renderers`` namespace::
 
-    setup(
-        # (...other arguments...)
-        entry_points={
-            'asphalt.templating.renderers': [
-                'awesome = foo.bar.awesome:AwesomeRenderer'
-            ]
-        }
-    )
+    [project.entry-points."asphalt.templating.renderers"]
+    awesome = "foo.bar.awesome:AwesomeRenderer"

docs/usage.rst

@@ -4,13 +4,18 @@ Using template renderers
 Using renderers is quite straightforward. For example, to render a Jinja2 template named
 ``templatefile.html``::
 
-    async def handler(ctx):
-        text = ctx.jinja2.render('templatefile.html', somevariable='foo')
+    from asphalt.core import inject, resource
+    from asphalt.templating import TemplateRenderer
 
-This example assumes a configuration with a Jinja2 renderer and a Jinja2 template file named
-``templatefile.html`` in the designated template directory.
+    @inject
+    async def handler(*, renderer: TemplateRenderer = resource()):
+        text = renderer.render("templatefile.html", somevariable="foo")
+
+This example assumes a configuration with a Jinja2 renderer and a Jinja2 template file
+named ``templatefile.html`` in the designated template directory.
 
 To directly render a template string::
 
-    async def handler(ctx):
-        text = ctx.jinja2.render_string('This is foo: {{ foo }}', somevariable='foo')
+    @inject
+    async def handler(*, renderer: TemplateRenderer = resource()):
+        text = renderer.render_string('This is foo: {{ foo }}', somevariable='foo')