docs(book): include PRQL changelog in book (#2348)

Close #2344

Since `prql` code blocks in md files included in the Book will evaluated
and replace with html, this PR introduce a new Option `no-eval` that
modifies the Book preprocessor to not evaluate Changelog's `prql` code
blocks.
Also add a pre-commit hook to avoid using bare `prql` code blocks on
`CHANGELOG.md`.

---------

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/build-web.yaml

@@ -5,6 +5,7 @@ on:
     paths:
       - "web/**"
       - ".github/workflows/build-web.yaml"
+      - "**.md"
   workflow_call:
 
 concurrency:

.pre-commit-config.yaml

@@ -53,6 +53,17 @@ repos:
         types: ["rust"]
         # A regex searching sql files for either `prj-` or 'tgs-'.
         entry: "dbg!"
+  - repo: local
+    hooks:
+      - id: prql-codeblock
+        name: Prevent prql codeblocks evaluating in book
+        description:
+          prql code blocks are evaluated and replaced in the book; instead use
+          `prql no-eval`
+        language: pygrep
+        entry: "```prql$"
+        files: 'CHANGELOG\.md$'
+
   # This is quite strict, and doesn't fix a large enough share of the issues it
   # finds, so we don't include it. But it's reasonable to run every now & again
   # manually and take its fixes.

CHANGELOG.md

@@ -298,17 +298,21 @@ This release has 74 commits from 12 contributors. Selected changes:
   formats. _format-arg_ can be `format:csv` or `format:json`. _string-arg_ can
   be a string in any format. (@aljazerzen & @snth, #1514)
 
-  ```prql
+  ```prql no-eval
   from_text format:csv """
   a,b,c
   1,2,3
   4,5,6
   """
+  ```
 
+  ```prql no-eval
   from_text format:json '''
       [{"a": 1, "b": "x", "c": false }, {"a": 4, "b": "y", "c": null }]
   '''
+  ```
 
+  ```prql no-eval
   from_text format:json '''{
       "columns": ["a", "b", "c"],
       "data": [
@@ -341,7 +345,7 @@ This release has 74 commits from 12 contributors. Selected changes:
 
 - Inferred column names include the relation name (@aljazerzen, #1550):
 
-  ```prql
+  ```prql no-eval
   from albums
   select title # name used to be inferred as title only
   select albums.title # so using albums was not possible here
@@ -380,7 +384,7 @@ below in this release).
   a variable to a value based on one of several expressions (@aljazerzen,
   #1278).
 
-  ```prql
+  ```prql no-eval
   derive var = case [
     score <= 10 -> "low",
     score <= 30 -> "medium",
@@ -411,15 +415,15 @@ below in this release).
 - _Experimental:_ Columns can be excluded by name with `select` (@aljazerzen,
   #1329)
 
-  ```prql
+  ```prql no-eval
   from albums
   select ![title, composer]
   ```
 
 - _Experimental:_ `append` transform, equivalent to `UNION ALL` in SQL.
   (@aljazerzen, #894)
 
-  ```prql
+  ```prql no-eval
   from employees
   append managers
   ```
@@ -431,7 +435,7 @@ below in this release).
 - Numbers can contain underscores, which can make reading long numbers easier
   (@max-sixty, #1467):
 
-  ```prql
+  ```prql no-eval
   from numbers
   select [
       small = 1.000_000_1,
@@ -444,7 +448,7 @@ below in this release).
 - `dialect` is renamed to `target`, and its values are prefixed with `sql.`
   (@max-sixty, #1388); for example:
 
-  ```prql
+  ```prql no-eval
   prql target:sql.bigquery  # previously was `dialect:bigquery`
 
   from employees
@@ -456,7 +460,7 @@ below in this release).
 - Tables definitions can contain a bare s-string (@max-sixty, #1422), which
   enables us to include a full CTE of SQL, for example:
 
-  ```prql
+  ```prql no-eval
   let grouping = s"""
     SELECT SUM(a)
     FROM tbl
@@ -533,7 +537,7 @@ improvements]
 
 - Support for using s-strings for `from` (#1197, @aljazerzen)
 
-  ```prql
+  ```prql no-eval
   from s"SELECT * FROM employees WHERE foo > 5"
   ```
 
@@ -677,7 +681,7 @@ fix rather than a breaking change in semantic versioning.
   last; for example `round 2 foo_col` / `cast int foo`. This is consistent with
   other functions, and makes piping possible:
 
-  ```prql
+  ```prql no-eval
   derive [
     gross_salary = (salary + payroll_tax | as int),
     gross_salary_rounded = (gross_salary | round 0),

web/book/src/SUMMARY.md

@@ -84,3 +84,5 @@
   - [Name resolving](./internals/name-resolving.md)
   - [Functions](./internals/functional-lang.md)
   - [Syntax highlighting](./internals/syntax-highlighting.md)
+
+- [Changelog](./changelog.md)

web/book/src/changelog.md

@@ -0,0 +1 @@
+{{#include ../../../CHANGELOG.md}}

web/book/src/lib.rs

@@ -116,7 +116,7 @@ fn replace_examples(text: &str) -> Result<String> {
             cmark_acc.push(event.to_owned());
             continue;
         };
-        if !lang_tags.contains(&"prql".to_string()) {
+        if !lang_tags.contains(&"prql".to_string()) || lang_tags.contains(&"no-eval".to_string()) {
             cmark_acc.push(event.to_owned());
             continue;
         }