3a3cd4c9fc6c0d4af9a953eb901e9d3cc59f9f6e — Logan Connolly 2 months ago 54ae0ac
docs: improve the package module documentation
1 files changed, 33 insertions(+), 7 deletions(-)

M src/haitch/__init__.py
M src/haitch/__init__.py => src/haitch/__init__.py +33 -7
@@ 2,19 2,45 @@
haitch - a lazy HTML element builder.

Import any element you like from the root module:
Import haitch like so:

>>> import haitch as H

Lazily build a dom tree by passing children and/or attributes to the
`__init__` and/or `__call__` methods:
Now you have access to any element you like:

>>> dom = H.a(href="https://example.com")("Check out my website")
>>> H.img(src="my-image.png", alt="cool image") # valid
>>> H.foo("Custom element!") # valid

In order render the object to HTML, you need to invoke the `__str__` method:
Both these statements would render correctly; however, the `<img>`
element would have typing and documentation, while the `<foo>` one
would not because it is not a standard element.

>>> str(dom)
'<a href="https://example.com">Check out my website</a>'
Lazily build a dom tree by passing children (args) and/or
attributes (kwargs):

>>> dom = H.a(
...     H.strong("Check out my website"), # arg
...     href="https://example.com", # kwarg
... )

A called element validates its input, attaches the values to itself,
and then returns itself. This enables us to chain calls together:

>>> dom = H.a(href="https://example.com")(
...     H.strong("Check out my website"),
... )

Both instances of `dom` will render the same HTML. I prefer the second
way because it looks more like HTML, and it keeps the attributes closer
to the parent element.

Until now we have only lazily built the dom tree. In order to render it
to HTML, you need to invoke the underlying `__str__` method:

>>> str(dom) # or print(dom)
<a href="https://example.com">
  <strong>Check out my website</strong>

from haitch._components._fragment import fragment