* wip

Author: jkmnt

README.md

@@ -1,2 +1,42 @@
 # vscode-python-fstring-dsl
 Syntax highlighting for HTML, SQL, JS, CSS in Python f-strings
+
+## Usage
+To trigger the syntax highlight you must wrap your
+DSL-string in a specific function (or method) call: `html(...),` `sql(...)`, `js(...)`, `css(...)`. This function may be noop like the Python's `typing.cast()` or do something useful, i.e. trimming whitespaces.
+
+```python
+def html(s: str):
+    return s
+```
+
+If the string is template (f-string), the internal f-expressions will be syntax highlighted too.
+
+## Sample
+![sample.png](https://raw.githubusercontent.com/jkmnt/vscode-python-fstring-dsl/sample.png)
+
+This sample shows the well-typed server-side Dialog component with
+bootsrap styling, htmx magic and text escaping.
+
+
+## Note
+
+- The syntax matching is naive. It will work only for the simple common cases. If something don't color the way it should, the best solution is to simplify the template.
+
+- This extension deals with the highlighting  only, so no Intellisence, hovers, etc.
+
+- f-strings are not very useful with CSS and JS. These languages are brace-heavy - too many braces to be escaped.
+
+- To underline the embedded areas as in the sample above, add following to the VSCode settings.json:
+    ```json
+    "editor.tokenColorCustomizations": {
+        "textMateRules": [
+            {
+                "scope": "meta.embedded.inline.f-expression",
+                "settings": {
+                    "fontStyle": "underline",
+                },
+            },
+        ]
+    },
+    ```

sample.png

@@ -0,0 +1,51 @@
+# stubs
+
+
+def html(s: str):
+    return s
+
+
+def _(s: str):
+    return s
+
+
+def e(s: str):
+    return s
+
+
+class SafeStr(str):
+    pass
+
+
+# actual sample
+
+
+def Dialog(*, post_url: str, title: str, body: SafeStr, cancel_text: str | None = None, ok_text: str | None = None):
+    cancel_text = cancel_text or _("Cancel")
+    ok_text = cancel_text or _("Ok")
+
+    return html(
+        f"""
+        <div class="modal fade" tabindex="-1">
+            <div class="modal-dialog modal-md modal-dialog-centered">
+                <form class="form modal-content"
+                    autocomplete="off"
+                    hx-post="{ post_url }"
+                    hx-select=".modal-content"
+                    hx-swap="outerHTML">
+                    <div class="modal-header">
+                        <h5 class="modal-title">{ e(title) }</h5>
+                    </div>
+                    <div class="modal-body">
+                        { body }
+                    </div>
+                    <div class="modal-footer">
+                        <button type="button"
+                                class="btn btn-outline-secondary"
+                                data-bs-dismiss="modal">{ e(cancel_text) }</button>
+                        <button type="submit" class="btn btn-primary">{ e(ok_text) }</button>
+                    </div>
+                </form>
+            </div>
+        </div>"""
+    )