Skip to content

Commit 7750b53

Browse files
MaddyGuthridgeMaddyGuthridge
committed
Make a simple documentation site
1 parent ebd2fb1 commit 7750b53

File tree

10 files changed

+534
-243
lines changed

10 files changed

+534
-243
lines changed

‎README.md‎

Lines changed: 3 additions & 240 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ inspired by (and similar to)
55
[Cenk Altı's PyHTML library](https://github.com/cenkalti/pyhtml), but
66
with improved documentation and type safety.
77

8+
Learn more by visiting the documentation website (up soon).
9+
810
## Features
911

1012
* Inline documentation and type safety for all tags.
@@ -15,7 +17,7 @@ with improved documentation and type safety.
1517

1618
* No dependencies.
1719

18-
* 100% test coverage
20+
* 100% test coverage.
1921

2022
## Usage
2123

@@ -51,242 +53,3 @@ with improved documentation and type safety.
5153
</html>
5254

5355
```
54-
55-
### Creating elements
56-
57-
Every HTML tag is represented by a `class` that generates that HTML code. For
58-
example, to create a `<br>` element, you could use:
59-
60-
```py
61-
>>> line_break = p.br()
62-
>>> print(str(line_break))
63-
<br/>
64-
65-
```
66-
67-
### Adding children to elements
68-
69-
Any arguments to a tag are used as a child element to the created HTML element.
70-
For example, to create a heading with the text `"My awesome website"`, you
71-
could use
72-
73-
```py
74-
>>> heading = p.h1("My awesome website")
75-
>>> print(str(heading))
76-
<h1>
77-
My awesome website
78-
</h1>
79-
80-
```
81-
82-
### Adding attributes to elements
83-
84-
Any keyword arguments to a tag are used as an attribute of the created HTML
85-
element. For example, to create a form submit button, you could use
86-
87-
```py
88-
>>> submit_button = p.input(type="submit")
89-
>>> print(str(submit_button))
90-
<input type="submit"/>
91-
92-
```
93-
94-
### Adding attributes and children
95-
96-
In HTML, attributes are specified within the opening tag. Contrastingly, Python
97-
requires keyword arguments (attributes) to be specified after regular arguments
98-
(children). To maintain similarity to writing regular HTML, you can call an
99-
element in order to add more attributes and children. For example, to create
100-
a link to PyHTML's GitHub page, you could use
101-
102-
```py
103-
>>> my_link = p.a(href="https://github.com/COMP1010UNSW/pyhtml-enhanced")("Take a look at the code")
104-
>>> print(str(my_link))
105-
<a href="https://github.com/COMP1010UNSW/pyhtml-enhanced">
106-
Take a look at the code
107-
</a>
108-
109-
```
110-
111-
### HTML comments
112-
113-
You can add comments to HTML (useful for debugging) by using the `Comment` tag.
114-
115-
```py
116-
>>> comment = p.Comment("This is an HTML comment")
117-
>>> print(str(comment))
118-
<!--
119-
This is an HTML comment
120-
-->
121-
122-
```
123-
124-
### Rendering HTML
125-
126-
Converting your PyHTML into HTML is as simple as stringifying it!
127-
128-
```py
129-
>>> print(str(p.i("How straightforward!")))
130-
<i>
131-
How straightforward!
132-
</i>
133-
134-
```
135-
136-
### Custom tags
137-
138-
Since this library includes all modern HTML tags, it is very unlikely that
139-
you'll need to do create a custom tag. However if you really need to, you can
140-
create a class deriving from `Tag`.
141-
142-
```py
143-
>>> class fancytag(p.Tag):
144-
... ...
145-
>>> print(fancytag())
146-
<fancytag></fancytag>
147-
148-
```
149-
150-
#### Tag base classes
151-
152-
You can derive from various other classes to get more control over how your tag
153-
is rendered:
154-
155-
* `Tag`: default rendering.
156-
157-
* `SelfClosingTag`: tag is self-closing, meaning that no child elements are
158-
accepted.
159-
160-
* `WhitespaceSensitiveTag`: tag is whitespace-sensitive, meaning that its
161-
child elements are not indented.
162-
163-
#### Class properties
164-
165-
* `children`: child elements
166-
* `attributes`: element attributes
167-
168-
#### Rendering control functions
169-
170-
You can also override various functions to control the existing rendering.
171-
172-
* `_get_tag_name`: return the name to use for the tag. For example returning
173-
`"foo"` would produce `<foo>`.
174-
175-
* `_get_default_attributes`: return the default values for attributes.
176-
177-
* `_get_tag_pre_content`: return the pre-content for the tag. For example, the
178-
`<html>` tag uses this to add the `<!DOCTYPE html>` before the opening tag.
179-
180-
* `_escape_children`: return whether the string child elements should be
181-
escaped to prevent HTML injection.
182-
183-
* `_render`: render the element and its children, returning the list of lines
184-
to use for the output. Overriding this should be a last resort, as it is easy
185-
to subtly break the rendering process if you aren't careful.
186-
187-
Refer to the documentation for `Tag` for more information.
188-
189-
## Differences to PyHTML
190-
191-
There are some minor usage differences compared to the original PyHTML library.
192-
193-
Uninstantiated classes are only rendered if they are given as the child of an
194-
instantiated element.
195-
196-
```py
197-
>>> p.br
198-
<class 'pyhtml.__tags.generated.br'>
199-
>>> print(str(p.html(p.body(p.br))))
200-
<!DOCTYPE html>
201-
<html>
202-
<body>
203-
<br/>
204-
</body>
205-
</html>
206-
207-
```
208-
209-
Calling an instance of a `Tag` will return a new tag containing all elements of
210-
the original tag combined with the new attributes and children, but will not
211-
modify the original instance, as I found the old behaviour confusing and
212-
bug-prone.
213-
214-
```py
215-
>>> para = p.p("Base paragraph")
216-
>>> para2 = para("Extra text")
217-
>>> para2
218-
<p>
219-
Base paragraph
220-
Extra text
221-
</p>
222-
>>> para
223-
<p>
224-
Base paragraph
225-
</p>
226-
227-
```
228-
229-
## Known issues
230-
231-
There are a couple of things I haven't gotten round to sorting out yet
232-
233-
* [ ] Add default attributes to more tags
234-
* [ ] Some tags (eg `<pre>`, `<script>`) currently aren't properly implemented
235-
and escape their contents.
236-
237-
## How it works
238-
239-
Since there are so many HTML tags, it would be extremely tedious to document
240-
them all manually. In the `meta` directory, you will find code that solves this
241-
problem with the following steps:
242-
243-
1. Download the Markdown source for
244-
[MDN's documentation of all HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
245-
246-
2. Parse the markdown to gather all tag names and descriptions, discarding
247-
garbage data and obsolete tags.
248-
249-
3. Use data from a YAML configuration file ([`meta/tags.yml`](meta/tags.yml))
250-
to gather information on suggested attributes and base classes to use for
251-
each tag.
252-
253-
4. Generate Python code to represent all of these tags, including their
254-
documentation.
255-
256-
## Credits
257-
258-
### [Cenkalti/PyHTML](https://github.com/cenkalti/pyhtml)
259-
260-
Cenk Altı's work was used as a source of inspiration and reference. Although
261-
all the code in `pyhtml-enhanced` was written by me, I want to thank them for
262-
the significant help their hard work provided while creating this project,
263-
going as far as to give design advice on request.
264-
265-
### [MDN Web Docs](https://developer.mozilla.org/en-US/)
266-
267-
Almost all of the documentation was gathered from the MDN Web Docs. It's super
268-
neat that all their documentation is open (licensed as
269-
[CC-BY-SA-2.5](https://creativecommons.org/licenses/by-sa/2.5/) if you're
270-
interested).
271-
272-
### COMP1010 students and staff
273-
274-
COMP1010's students and staff members have uncovered and helped to resolve many
275-
bugs, and have suggested many improvements. I'd like to thank them for all of
276-
their help!
277-
278-
## License
279-
280-
### Source code
281-
282-
Copyright (c) 2023 Maddy Guthridge, COMP1010 UNSW
283-
284-
Source code for the library is open source, using the
285-
[MIT license](https://choosealicense.com/licenses/mit/). A copy of the license
286-
text is available in [LICENSE.md](https://github.com/COMP1010UNSW/pyhtml-enhanced/blob/main/LICENSE.md)
287-
288-
### Documentation
289-
290-
Documentation is copied from MDN Web Docs, and is license under
291-
[CC-BY-SA-2.5](https://creativecommons.org/licenses/by-sa/2.5/). A copy of the
292-
license text is available in [LICENSE_DOCS.md](https://github.com/COMP1010UNSW/pyhtml-enhanced/blob/main/LICENSE_DOCS.md)

‎docs/compatibility.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Compatibility with PyHTML
2+
3+
There are some minor usage differences compared to the original PyHTML library.
4+
5+
## Rendering of uninstantiated classes
6+
7+
Uninstantiated classes are only rendered if they are given as the child of an
8+
instantiated element.
9+
10+
```py
11+
>>> p.br
12+
<class 'pyhtml.__tags.generated.br'>
13+
>>> print(str(p.html(p.body(p.br))))
14+
<!DOCTYPE html>
15+
<html>
16+
<body>
17+
<br/>
18+
</body>
19+
</html>
20+
21+
```
22+
23+
## Calling tag instances
24+
25+
Calling an instance of a `Tag` will return a new tag containing all elements of
26+
the original tag combined with the new attributes and children, but will not
27+
modify the original instance, as I found the old behaviour confusing and
28+
bug-prone.
29+
30+
```py
31+
>>> para = p.p("Base paragraph")
32+
>>> para2 = para("Extra text")
33+
>>> para2
34+
<p>
35+
Base paragraph
36+
Extra text
37+
</p>
38+
>>> para
39+
<p>
40+
Base paragraph
41+
</p>
42+
43+
```

‎docs/credits.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Credits
2+
3+
## [Cenkalti/PyHTML](https://github.com/cenkalti/pyhtml)
4+
5+
Cenk Altı's work was used as a source of inspiration and reference. Although
6+
all the code in `pyhtml-enhanced` was written by me, I want to thank them for
7+
the significant help their hard work provided while creating this project,
8+
going as far as to give design advice on request.
9+
10+
## [MDN Web Docs](https://developer.mozilla.org/en-US/)
11+
12+
Almost all of the documentation was gathered from the MDN Web Docs. It's super
13+
neat that all their documentation is open (licensed as
14+
[CC-BY-SA-2.5](https://creativecommons.org/licenses/by-sa/2.5/) if you're
15+
interested).
16+
17+
## COMP1010 students and staff
18+
19+
COMP1010's students and staff members have uncovered and helped to resolve many
20+
bugs, and have suggested many improvements. I'd like to thank them for all of
21+
their help!

‎docs/how.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# How it works
2+
3+
Since there are so many HTML tags, it would be extremely tedious to document
4+
them all manually. In the `meta` directory, you will find code that solves this
5+
problem with the following steps:
6+
7+
1. Download the Markdown source for
8+
[MDN's documentation of all HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
9+
10+
2. Parse the markdown to gather all tag names and descriptions, discarding
11+
garbage data and obsolete tags.
12+
13+
3. Use data from a YAML configuration file ([`meta/tags.yml`](meta/tags.yml))
14+
to gather information on suggested attributes and base classes to use for
15+
each tag.
16+
17+
4. Generate Python code to represent all of these tags, including their
18+
documentation.
19+
20+
## Code generation
21+
22+
See the `meta` directory in the code.
23+
24+
## Rendering
25+
26+
See the `render` function of the `Tag` class.

‎docs/index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# `<PyHTML/>`
2+
3+
A library for building HTML documents with a simple and learnable syntax,
4+
inspired by (and similar to)
5+
[Cenk Altı's PyHTML library](https://github.com/cenkalti/pyhtml), but
6+
with improved documentation and type safety.
7+
8+
## Usage
9+
10+
Consider visiting the [learn PyHTML page](./learn).
11+
12+
```py
13+
>>> import pyhtml as p
14+
>>> my_website = p.html(
15+
... p.head(
16+
... p.title("Hello, world!"),
17+
... p.script(src="http://example.com/script.js"),
18+
... ),
19+
... p.body(
20+
... p.h1("Hello, world!"),
21+
... p.p("This is my amazing website!"),
22+
... ),
23+
... )
24+
>>> print(str(my_website))
25+
<!DOCTYPE html>
26+
<html>
27+
<head>
28+
<title>
29+
Hello, world!
30+
</title>
31+
<script type="text/javascript" src="http://example.com/script.js"></script>
32+
</head>
33+
<body>
34+
<h1>
35+
Hello, world!
36+
</h1>
37+
<p>
38+
This is my amazing website!
39+
</p>
40+
</body>
41+
</html>
42+
43+
```

0 commit comments

Comments
 (0)