diff --git a/docs/conf.py b/docs/conf.py index 55286bd..0a318f2 100644 --- a/docs/conf.py +++ b/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), } diff --git a/docs/configuration.rst b/docs/configuration.rst index d4ad247..7d67d09 100644 --- a/docs/configuration.rst +++ b/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) diff --git a/docs/extending.rst b/docs/extending.rst index 6e52994..3a8550c 100644 --- a/docs/extending.rst +++ b/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" diff --git a/docs/modules/renderers/tonnikala.rst b/docs/modules/renderers/tonnikala.rst deleted file mode 100644 index 636f6f8..0000000 --- a/docs/modules/renderers/tonnikala.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`asphalt.templating.renderers.tonnikala` -============================================= - -.. automodule:: asphalt.templating.renderers.tonnikala - :members: diff --git a/docs/usage.rst b/docs/usage.rst index 9604e32..0c5eb23 100644 --- a/docs/usage.rst +++ b/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')