Document rendering control methods

MaddyGuthridge · MaddyGuthridge · commit f3c9364ae6be · 2024-05-03T17:21:10.000+10:00
diff --git a/README.md b/README.md
@@ -147,6 +147,43 @@ create a class deriving from `Tag`.
 
 ```
 
+#### Tag base classes
+
+You can derive from various other classes to get more control over how your tag
+is rendered:
+
+* `Tag`: default rendering.
+
+* `SelfClosingTag`: tag is self-closing, meaning that no child elements are
+  accepted.
+
+* `WhitespaceSensitiveTag`: tag is whitespace-sensitive, meaning that its
+  child elements are not indented.
+
+#### Class properties
+
+* `children`: child elements
+* `attributes`: element attributes
+
+#### Rendering control functions
+
+You can also override various functions to control the existing rendering.
+
+* `_get_tag_name`: return the name to use for the tag. For example returning
+  `"foo"` would produce `<foo>`.
+
+* `_get_default_attributes`: return the default values for attributes.
+
+* `_get_tag_pre_content`: return the pre-content for the tag. For example, the
+  `<html>` tag uses this to add the `<!DOCTYPE html>` before the opening tag.
+
+* `_escape_children`: return whether the string child elements should be
+  escaped to prevent HTML injection.
+
+* `_render`: render the element and its children, returning the list of lines
+  to use for the output. Overriding this should be a last resort, as it is easy
+  to subtly break the rendering process if you aren't careful.
+
 Refer to the documentation for `Tag` for more information.
 
 ## Differences to PyHTML
diff --git a/pyhtml/__init__.py b/pyhtml/__init__.py
@@ -1,8 +1,6 @@
 """
 # PyHTML Enhanced
 
-v2.0.3
-
 A library for building HTML documents with a simple and learnable syntax,
 inspired by (and similar to)
 [Cenk Altı's PyHTML library](https://github.com/cenkalti/pyhtml), but
@@ -35,6 +33,7 @@
 ...     ),
 ... )
 >>> print(str(my_website))
+<!DOCTYPE html>
 <html>
   <head>
     <title>
@@ -149,6 +148,43 @@
 
 ```
 
+#### Tag base classes
+
+You can derive from various other classes to get more control over how your tag
+is rendered:
+
+* `Tag`: default rendering.
+
+* `SelfClosingTag`: tag is self-closing, meaning that no child elements are
+  accepted.
+
+* `WhitespaceSensitiveTag`: tag is whitespace-sensitive, meaning that its
+  child elements are not indented.
+
+#### Class properties
+
+* `children`: child elements
+* `attributes`: element attributes
+
+#### Rendering control functions
+
+You can also override various functions to control the existing rendering.
+
+* `_get_tag_name`: return the name to use for the tag. For example returning
+  `"foo"` would produce `<foo>`.
+
+* `_get_default_attributes`: return the default values for attributes.
+
+* `_get_tag_pre_content`: return the pre-content for the tag. For example, the
+  `<html>` tag uses this to add the `<!DOCTYPE html>` before the opening tag.
+
+* `_escape_children`: return whether the string child elements should be
+  escaped to prevent HTML injection.
+
+* `_render`: render the element and its children, returning the list of lines
+  to use for the output. Overriding this should be a last resort, as it is easy
+  to subtly break the rendering process if you aren't careful.
+
 Refer to the documentation for `Tag` for more information.
 
 ## Differences to PyHTML
@@ -162,6 +198,7 @@
 >>> p.br
 <class 'pyhtml.__tags.generated.br'>
 >>> print(str(p.html(p.body(p.br))))
+<!DOCTYPE html>
 <html>
   <body>
     <br/>
@@ -254,7 +291,6 @@
 Documentation is copied from MDN Web Docs, and is license under
 [CC-BY-SA-2.5](https://creativecommons.org/licenses/by-sa/2.5/). A copy of the
 license text is available in [LICENSE_DOCS.md](https://github.com/COMP1010UNSW/pyhtml-enhanced/blob/main/LICENSE_DOCS.md)
-
 """
 # Disable Flake8, since it really doesn't like our docstring above
 # flake8: noqa
