Merge pull request #176 from jg-rp/mkdocs

Bundle i18n and i10n tags and filters and update docs

Author: jg-rp

CHANGES.md

@@ -2,23 +2,24 @@
 
 ## Version 2.0.0 (unreleased)
 
-This major release:
+This is a major release with several breaking changes. As well as API changes listed below, we:
 
-- Drops support for Python version 3.7 and 3.8.
-- Introduces API changes [discussed here](https://github.com/jg-rp/liquid/discussions/137).
+- Drop support for Python version 3.7 and 3.8.
 - Promotes rendering behavior from `liquid.future.Environment` to be the default, so as to improve Shopify/liquid compatibility by default.
-- Fixes variable/identifier/path parsing described in [issue #39](https://github.com/jg-rp/liquid/issues/39).
-- Improves Liquid syntax error messages and exposes source index, line numbers and column numbers through methods on Liquid exceptions. See [#53](https://github.com/jg-rp/liquid/issues/53).
-- Changes comment tag parsing to better match Shopify/Liquid. See [#133](https://github.com/jg-rp/liquid/issues/133).
-- Removes `BoundTemplate.analyze_with_context()`. Shout if you need contextual analysis and we'll restore this feature.
-- Removes the `cache_size` argument to `liquid.Environment` and `liquid.Template`. Template caching is now handled by template loaders.
-- Removes the `expression_cache_size` argument to `liquid.Environment` and `liquid.Template`. Environment-level expression caching is no longer available as it does not play nicely with detailed error messages. If you need to cache parsing of Liquid expressions, it is now recommended to implement a cache per tag, where it makes sense to do so for your use case.
-- Makes markupsafe>=3 a dependency. Previously markupsafe was an optional dependency. Version 3 of markupsafe brings some subtle changes to the `replace`, `replace_first` and `replace_last` filters when they receive a "safe" string wrapped in `Markup()`.
-- Adds new filters `reject`, `has`, `find` and `find_index`.
-- Adds the new `doc` tag.
+- Fixe variable/identifier/path parsing described in [issue #39](https://github.com/jg-rp/liquid/issues/39).
+- Improve Liquid syntax error messages and exposes source index, line numbers and column numbers through methods on Liquid exceptions. See [#53](https://github.com/jg-rp/liquid/issues/53).
+- Change comment tag parsing to better match Shopify/Liquid. See [#133](https://github.com/jg-rp/liquid/issues/133).
+- Remove `BoundTemplate.analyze_with_context()`. Shout if you need contextual analysis and we'll restore this feature.
+- Remove the `cache_size` argument to `liquid.Environment` and `liquid.Template`. Template caching is now handled by template loaders.
+- Remove the `expression_cache_size` argument to `liquid.Environment` and `liquid.Template`. Environment-level expression caching is no longer available as it does not play nicely with detailed error messages. If you need to cache parsing of Liquid expressions, it is now recommended to implement a cache per tag, where it makes sense to do so for your use case.
+- Make markupsafe>=3 a dependency. Previously markupsafe was an optional dependency. Version 3 of markupsafe brings some subtle changes to the `replace`, `replace_first` and `replace_last` filters when they receive a "safe" string wrapped in `Markup()`.
+- Add new filters `reject`, `has`, `find` and `find_index`.
+- Add the new `doc` tag.
 
 ### API changes
 
+Also see the [migration guide].
+
 #### Miscellaneous
 
 - Added `liquid.parse(source)`, `liquid.render(source, **data)` and `liquid.render_async(source, **data)`. These are shorthand functions that use `liquid.DEFAULT_ENVIRONMENT`.
@@ -27,6 +28,9 @@ This major release:
 - Added `liquid.Environment.render(source, **data)` and `liquid.Environment.render_async(source, **data)`. These are convenience methods equivalent to `liquid.Environment.from_string(source).render(**data)`.
 - Renamed `liquid.Context` to `liquid.RenderContext`.
 - Change the `liquid.RenderContext` constructor (previously `liquid.Context`) to require an instance of `BoundTemplate` as its only positional argument instead of an instance of `Environment`. All other arguments are now keyword only.
+- Renamed `liquid.exceptions.Error` to `liquid.exceptions.LiquidError`.
+- Renamed `liquid.exceptions.TemplateNotFound` to `liquid.exceptions.TemplateNotFoundError`.
+- Renamed `liquid.exceptions.NoSuchFilterFunc` to `liquid.exceptions.UnknownFilterError`.
 
 #### Template loaders
 

README.md

@@ -1,13 +1,9 @@
-> [!IMPORTANT]  
-> 🎉 Announcing the release of [Python Liquid2](https://github.com/jg-rp/python-liquid2) 🎉 See the [migration guide](https://jg-rp.github.io/python-liquid2/migration/) and the list of [new features](https://jg-rp.github.io/python-liquid2/migration/#new-features).
-
----
-
 <h1 align="center">Python Liquid</h1>
 
 <p align="center">
-A Python engine for <a href="https://shopify.github.io/liquid/">Liquid</a>, the safe customer-facing template language for flexible web apps.
-<br>We follow <a href="https://github.com/Shopify/liquid">Shopify/Liquid</a> closely and test against the <a href="https://github.com/jg-rp/golden-liquid">Golden Liquid</a> test suite.
+Python Liquid is a Python engine for <a href="https://shopify.github.io/liquid/">Liquid</a>, the safe, customer-facing template language.
+<br>
+We follow <a href="https://github.com/Shopify/liquid">Shopify/Liquid</a> closely and test against the <a href="https://github.com/jg-rp/golden-liquid">Golden Liquid</a> test suite.
 </p>
 <p align="center">
   <a href="https://github.com/jg-rp/liquid/blob/main/LICENSE">
@@ -46,10 +42,8 @@ A Python engine for <a href="https://shopify.github.io/liquid/">Liquid</a>, the
 
 - [Install](#install)
 - [Links](#links)
-- [Example](#example)
 - [Related Projects](#related-projects)
-- [Compatibility](#compatibility)
-- [Benchmark](#benchmark)
+- [Quick Start](#example)
 - [Contributing](#contributing)
 
 ## Install
@@ -75,78 +69,70 @@ $ conda install -c conda-forge python-liquid
 ## Links
 
 - Documentation: https://jg-rp.github.io/liquid/
+- Documentation for Python Liquid version 1.x: https://jg-rp.github.io/python-liquid-docs-archive/
 - Change Log: https://github.com/jg-rp/liquid/blob/main/CHANGES.md
 - PyPi: https://pypi.org/project/python-liquid/
 - Source Code: https://github.com/jg-rp/liquid
 - Issue Tracker: https://github.com/jg-rp/liquid/issues
 
-## Example
-
-```python
-from liquid import Template
+## Related Projects
 
-template = Template("Hello, {{ you }}!")
-print(template.render(you="World"))  # "Hello, World!"
-print(template.render(you="Liquid"))  # "Hello, Liquid!"
-```
+- [Python Liquid2](https://github.com/jg-rp/python-liquid2): A new Python engine for Liquid with [extra features](https://jg-rp.github.io/python-liquid2/migration/#new-features).
+- [LiquidScript](https://github.com/jg-rp/liquidscript): A JavaScript engine for Liquid with a similar high-level API to Python Liquid.
 
-## Related Projects
+## Quick Start
 
-- [Python Liquid2](https://github.com/jg-rp/python-liquid2): A new Python pakage for Liquid, with extra features.
-- [liquid-babel](https://github.com/jg-rp/liquid-babel): Internationalization and localization for Liquid templates.
-- [LiquidScript](https://github.com/jg-rp/liquidscript): A JavaScript and TypeScript engine for Liquid with a similar high-level API to Python Liquid.
-- [django-liquid](https://github.com/jg-rp/django-liquid): A Django template backend for Liquid. Render Liquid templates in your Django apps.
-- [Flask-Liquid](https://github.com/jg-rp/Flask-Liquid): A Flask extension for Liquid. Render Liquid templates in your Flask applications.
-- [golden-liquid](https://github.com/jg-rp/golden-liquid): A test suite for Liquid. See how various Liquid template engines compare to the reference implementation.
+### `render()`
 
-## Compatibility
+This example renders a template from a string of text with the package-level `render()` function. The template has just one placeholder variable `you`, which we've given the value `"World"`.
 
-We strive to be 100% compatible with the [reference implementation](https://shopify.github.io/liquid/) of Liquid, written in Ruby. That is, given an equivalent render context, a template rendered with Python Liquid should produce the same output as when rendered with Ruby Liquid.
+```python
+from liquid import render
 
-See the [known issues page](https://jg-rp.github.io/liquid/known_issues) for details of known incompatibilities between Python Liquid and Ruby Liquid, and please help by raising an issue if you notice an incompatibility.
+print(render("Hello, {{ you }}!", you="World"))
+# Hello, World!
+```
 
-## Benchmark
+### `parse()`
 
-You can run the benchmark using `hatch run benchmark` (or `python -O scripts/performance.py` if you don't have `make`) from the root of the source tree. On my ropey desktop computer with a Ryzen 5 1500X and Python 3.11.0, we get the following results.
+Often you'll want to render the same template several times with different variables. We can parse source text without immediately rendering it using the `parse()` function. `parse()` returns a `BoundTemplate` instance with a `render()` method.
 
-```text
-Best of 5 rounds with 100 iterations per round and 60 ops per iteration (6000 ops per round).
+```python
+from liquid import parse
 
-lex template (not expressions): 1.2s (5020.85 ops/s, 83.68 i/s)
-                    lex and parse: 5.0s (1197.32 ops/s, 19.96 i/s)
-                        render: 1.4s (4152.92 ops/s, 69.22 i/s)
-            lex, parse and render: 6.5s (922.08 ops/s, 15.37 i/s)
+template = parse("Hello, {{ you }}!")
+print(template.render(you="World"))  # Hello, World!
+print(template.render(you="Liquid"))  # Hello, Liquid!
 ```
 
-And PyPy3.7 gives us a decent increase in performance.
-
-```text
-Best of 5 rounds with 100 iterations per round and 60 ops per iteration (6000 ops per round).
+### Configure
 
-lex template (not expressions): 0.58s (10308.67 ops/s, 171.81 i/s)
-                    lex and parse: 3.6s (1661.20 ops/s, 27.69 i/s)
-                        render: 0.95s (6341.14 ops/s, 105.69 i/s)
-            lex, parse and render: 4.6s (1298.18 ops/s, 21.64 i/s)
-```
+Both `parse()` and `render()` are convenience functions that use the default Liquid environment. For all but the simplest cases, you'll want to configure an instance of `Environment`, then load and render templates from that.
 
-On the same machine, running `rake benchmark:run` from the root of the reference implementation source tree gives us these results.
+```python
+from liquid import CachingFileSystemLoader
+from liquid import Environment
 
-```text
-/usr/bin/ruby ./performance/benchmark.rb lax
+env = Environment(
+    autoescape=True,
+    loader=CachingFileSystemLoader("./templates"),
+)
+```
 
-Running benchmark for 10 seconds (with 5 seconds warmup).
+Then, using `env.parse()` or `env.get_template()`, we can create a `BoundTemplate` from a string or read from the file system, respectively.
 
-Warming up --------------------------------------
-                parse:     3.000  i/100ms
-            render:     8.000  i/100ms
-    parse & render:     2.000  i/100ms
-Calculating -------------------------------------
-                parse:     39.072  (± 0.0%) i/s -    393.000  in  10.058789s
-            render:     86.995  (± 1.1%) i/s -    872.000  in  10.024951s
-    parse & render:     26.139  (± 0.0%) i/s -    262.000  in  10.023365s
+```python
+# ... continued from above
+template = env.parse("Hello, {{ you }}!")
+print(template.render(you="World"))  # Hello, World!
+
+# Try to load "./templates/index.html"
+another_template = env.get_template("index.html")
+data = {"some": {"thing": [1, 2, 3]}}
+result = another_template.render(**data)
 ```
 
-I've tried to match the benchmark workload to that of the reference implementation, so that we might compare results directly. The workload is meant to be representative of Shopify's use case, although I wouldn't be surprised if their usage has changed subtly since the benchmark fixture was designed.
+Unless you happen to have a relative folder called `templates` with a file called `index.html` within it, we would expect a `TemplateNotFoundError` to be raised when running the example above.
 
 ## Contributing
 

contributing.md

@@ -1,6 +1,6 @@
 # Contributing to Python Liquid
 
-Hi. Your contributions and questions are always welcome. Feel free to ask questions, report bugs or request features on the [issue tracker](https://github.com/jg-rp/liquid/issues) or on [Github Discussions](https://github.com/jg-rp/liquid/discussions).
+Your contributions and questions are always welcome. Feel free to ask questions, report bugs or request features on the [issue tracker](https://github.com/jg-rp/liquid/issues) or on [Github Discussions](https://github.com/jg-rp/liquid/discussions).
 
 **Table of contents**
 
@@ -52,9 +52,7 @@ Then open `htmlcov/index.html` in your browser.
 
 ## Documentation
 
-[Documentation](https://jg-rp.github.io/liquid/) is built using [Docusaurus](https://docusaurus.io/). Find the source in the [docs branch](https://github.com/jg-rp/liquid/tree/docs) of this repository.
-
-The `docs` folder in the root of this repository contains docs generated from Python docstrings, hosted on [Read the Docs](https://liquid.readthedocs.io/en/latest/). The plan is to mirror this API documentation to the Docusaurus site with the help of [Griffe](https://mkdocstrings.github.io/griffe/).
+[Documentation](https://jg-rp.github.io/liquid/) is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/). Find the source in the `docs` folder of this repository.
 
 ## Style Guides
 
@@ -64,6 +62,6 @@ There are no hard rules for git commit messages, although you might like to indi
 
 ### Python Style
 
-All Python files are formatted using [Black](https://github.com/psf/black), with its default configuration.
+All Python files are formatted using [Ruff](https://github.com/astral-sh/ruff), configured in `pyproject.toml`
 
 Docstrings must use [Google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).

docs/.overrides/main.html

@@ -0,0 +1,5 @@
+::: liquid.Node
+::: liquid.BlockNode
+::: liquid.ConditionalBlockNode
+::: liquid.ast.Partial
+::: liquid.ast.PartialScope

docs/analysis.md

@@ -0,0 +1 @@
+::: liquid.builtin.register

docs/api.md

@@ -0,0 +1,4 @@
+::: liquid.parse
+::: liquid.render
+::: liquid.render_async
+::: liquid.extract_liquid

docs/api/ast.md

@@ -0,0 +1 @@
+::: liquid.Environment