Skip to content

Commit 7259f90

Browse files
pelmepelme
committed
Split the html2htpy docs into how-to and reference.
This is following the Diataxis framework. This commit bootstraps the reference section. It also improves the help text provided by the tool itself.
1 parent 56cc031 commit 7259f90

File tree

5 files changed

+295
-211
lines changed

5 files changed

+295
-211
lines changed

‎docs/how-to/convert-html.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Convert HTML to htpy code
2+
3+
Maybe you already have a bunch of HTML, or templates that you would like to migrate to htpy. We got you covered. This page describes how you can convert existing HTML to htpy code.
4+
5+
The utility command `html2htpy` ships with `htpy`, and can be used to transform existing HTML into Python code (htpy!).
6+
7+
Lets say you have an existing HTML file:
8+
9+
```html title="index.html"
10+
<!DOCTYPE html>
11+
<html lang="en">
12+
<head>
13+
<meta charset="UTF-8" />
14+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
15+
<title>htpy Recipes</title>
16+
</head>
17+
<body>
18+
<div id="header">
19+
<h1>Welcome to the cooking site</h1>
20+
<p>Your go-to place for delicious recipes!</p>
21+
</div>
22+
23+
<div id="recipe-of-the-day" class="section">
24+
<h2>
25+
Recipe of the Day: <span class="highlight">Spaghetti Carbonara</span>
26+
</h2>
27+
<p>This classic Italian dish is quick and easy to make.</p>
28+
</div>
29+
30+
<div id="footer">
31+
<p>&copy; 2024 My Cooking Site. All rights reserved.</p>
32+
</div>
33+
</body>
34+
</html>
35+
```
36+
37+
Now, if you run the command, it outputs the corresponding Python code (htpy).
38+
39+
```
40+
$ html2htpy index.html
41+
```
42+
43+
```py
44+
from htpy import body, div, h1, h2, head, html, meta, p, span, title
45+
46+
html(lang="en")[
47+
head[
48+
meta(charset="UTF-8"),
49+
meta(name="viewport", content="width=device-width, initial-scale=1.0"),
50+
title["htpy Recipes"],
51+
],
52+
body[
53+
div("#header")[
54+
h1["Welcome to the cooking site"], p["Your go-to place for delicious recipes!"]
55+
],
56+
div("#recipe-of-the-day.section")[
57+
h2["Recipe of the Day: ", span(".highlight")["Spaghetti Carbonara"]],
58+
p["This classic Italian dish is quick and easy to make."],
59+
],
60+
div("#footer")[p["© 2024 My Cooking Site. All rights reserved."]],
61+
],
62+
]
63+
```
64+
65+
## Convert HTML snippets from the clipboard
66+
67+
This can be combined with other workflows in the way that you find most suitable.
68+
For example, you might pipe from your clipboard to htpy, and optionally direct the output to a file.
69+
70+
### Linux
71+
72+
```
73+
xclip -o -selection clipboard | html2htpy > output.py
74+
```
75+
76+
### Mac
77+
78+
```
79+
pbpaste | html2htpy > output.py
80+
```
81+
82+
### Windows
83+
84+
```
85+
powershell Get-Clipboard | html2htpy > output.py
86+
```
87+
88+
## Converting Django/Jinja templates
89+
90+
`html2htpy` will convert Django/Jinja-style template variables to f-strings:
91+
92+
``` html title="input"
93+
<div>hi {{ name }}!</div>
94+
```
95+
96+
``` py title="html2htpy output"
97+
98+
from htpy import div
99+
100+
div[f"hi { name }!"]
101+
102+
```
103+
104+
### Limitations
105+
106+
Other typical template syntax, such as loops `{% for x in y %}`, can not be transformed this way,
107+
so you will often have to clean up a bit after `html2htpy` is done with its thing.
108+
109+
See the example below:
110+
111+
```html title="jinja.html"
112+
<body>
113+
<h1>{{ heading }}</h1>
114+
<p>Welcome to our cooking site, {{ user.name }}!</p>
115+
116+
<h2>Recipe of the Day: {{ recipe.name }}</h2>
117+
<p>{{ recipe.description }}</p>
118+
119+
<h3>Instructions:</h3>
120+
<ol>
121+
{% for step in recipe.steps %}
122+
<li>{{ step }}</li>
123+
{% endfor %}
124+
</ol>
125+
</body>
126+
```
127+
128+
```py title="$ html2htpy jinja.html"
129+
from htpy import body, h1, h2, h3, li, ol, p
130+
131+
body[
132+
h1[f"{ heading }"],
133+
p[f"Welcome to our cooking site, { user.name }!"],
134+
h2[f"Recipe of the Day: { recipe.name }"],
135+
p[f"{ recipe.description }"],
136+
h3["Instructions:"],
137+
ol[" {% for step in recipe.steps %}", li[f"{ step }"], " {% endfor %}"],
138+
]
139+
```
140+
141+
## VSCode Extension
142+
143+
If you are using VSCode, you can install the [html2htpy](https://marketplace.visualstudio.com/items?itemName=dunderrrrrr.html2htpy) extension to quickly convert HTML to htpy code.

‎docs/html2htpy.md‎

Lines changed: 0 additions & 205 deletions
This file was deleted.

0 commit comments

Comments
 (0)