From d1efa4b2c8f647fae74f2bd6ef8c305316dcc3ab Mon Sep 17 00:00:00 2001 From: Ole-Jakob Olsen Date: Tue, 11 Jun 2024 23:57:54 +0200 Subject: [PATCH] Docs for html2htpy --- docs/html2htpy.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 188 insertions(+) create mode 100644 docs/html2htpy.md diff --git a/docs/html2htpy.md b/docs/html2htpy.md new file mode 100644 index 0000000..8f69bfa --- /dev/null +++ b/docs/html2htpy.md @@ -0,0 +1,187 @@ + +# Convert HTML to HTPY + +Maybe you already have a bunch of html, or templates that you would like to migrate to htpy. +We got you covered. HTPY ships with a utility command `html2htpy` that can be used to transform existing +html into python code (htpy!). + +``` +$ html2htpy -h +usage: html2htpy [-h] [-s] [-f] [input] + +positional arguments: + input input html from file or stdin + +options: + -h, --help show this help message and exit + -s, --shorthand Use shorthand syntax for class and id attributes + -f, --format Format output code (requires black installed) +``` + + +Lets say you have an existing html file: + +```html title="index.html" + + + + + + HTPY Recipes + + + + +
+

Recipe of the Day: Spaghetti Carbonara

+

This classic Italian dish is quick and easy to make.

+
+ + + + +``` + +Now, if you run the command, it outputs the corresponding python code (htpy). + +``` +$ html2htpy -f index.html +``` + +```py +html(lang="en")[ + head[ + meta(charset="UTF-8"), + meta(name="viewport", content="width=device-width, initial-scale=1.0"), + title["HTPY Recipes"], + ], + body[ + div(id="header")[ + h1["Welcome to the cooking site"], + p["Your go-to place for delicious recipes!"], + ], + div(id="recipe-of-the-day", class_="section")[ + h2[ + "Recipe of the Day: ", + span(class_="highlight")["Spaghetti Carbonara"], + ], + p["This classic Italian dish is quick and easy to make."], + ], + div(id="footer")[p["© 2024 My Cooking Site. All rights reserved."]], + ], +] +``` + +## Piping input/stdin stream + +You can also pipe input to htpy, for example `cat demo.html | html2htpy`. + +This can be combinded with other workflows in the way that you find most suitable. +For example, you might pipe from your clipboard to htpy, and optionaly direct the output to a file. + +#### Linux + +``` +xclip -o -selection clipboard | html2htpy > output.py +``` + +#### Mac + +``` +pbpaste | html2htpy > output.py +``` + +#### Windows + +``` +powershell Get-Clipboard | html2htpy > output.py +``` + + +## Formatting the output +`html2htpy` can format the output python code using `black`. It needs to be available in your python environment +when you run `html2htpy` with the `-f`/`--format` flag. You might have it in your environment already, or you can install it +as part of the htpy extras: `pip install htpy[extras]`. + +By default, output code is not formatted. + + +## Shorthand syntax + +If you prefer the htpy "shorthand" syntax for the id and class properties, you can get it by passing the `-s`/`--shorthand` flag + + +```html title="shorthand.html" +
+
+
+

Welcome

+
+
+
+``` + +...becomes: + +```py +$ html2htpy -f -s example.html +section(".hero.is-fullheight.is-link")[ + div(".hero-body")[ + div(".container")[ + p(".subtitle.is-3.is-spaced")["Welcome"], + ] + ] +] +``` + +## Template interpolation to f-strings + +You might have some templates laying around after using jinja or some other templating language. + +`html2htpy` will try to convert the `template {{ variables }}`... + +...to pythonic f-strings: `f"template { variables }"` + +Note that other template template syntax, such as loops `{% for x in y %}` can not be transformed at +this time, so you will often have to clean up a bit after `html2htpy` is done with its thing. + +See the example below: + +```html title="jinja.html" + +

{{ heading }}

+

Welcome to our cooking site, {{ user.name }}!

+ +

Recipe of the Day: {{ recipe.name }}

+

{{ recipe.description }}

+ +

Instructions:

+
    + {% for step in recipe.steps %} +
  1. {{ step }}
    2. + {% endfor %} +
+ +``` + +```py +$ html2htpy -f -s jinja.html +body[ + h1[f"{ heading }"], + p[f"Welcome to our cooking site, { user.name }!"], + h2[f"Recipe of the Day: { recipe.name }"], + p[f"{ recipe.description }"], + h3["Instructions:"], + ol[ + """ {% for step in recipe.steps %} """, + li[f"{ step }"], + """ {% endfor %} """, + ], +] +``` + diff --git a/mkdocs.yml b/mkdocs.yml index fd1a2f4..fb2f2ad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,7 @@ nav: - static-typing.md - django.md - streaming.md + - html2htpy.md - faq.md - references.md markdown_extensions: