update documentation

Author: fabiommendes

README.rst

@@ -10,33 +10,53 @@
 .. image:: https://codecov.io/gh/fabiommendes/hyperpython/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/fabiommendes/hyperpython
  :alt: Code coverage
+.. module:: hyperpython
 
 
-HyperPython
+Hyperpython
 ===========
 
-HyperPython is a Python interpretion of
-`Hyperscript <http://https://github.com/hyperhype/hyperscript>`_. If you are not
-familiar with Hyperscript, think of it as React, but using pure Javascript
-instead of JSX. Hyperpython allow us to generate, manipulate and query
-HTML documents using a small DSL embedded in Python. And just like in Hyperscript,
-the default entry point of Hyperpython the `h` function:
+Hyperpython is a Python interpretation of Hyperscript_. If you are not
+familiar with Hyperscript, think of it as a pure Javascript alternative to JSX.
+Hyperpython allow us to generate, manipulate and query HTML documents using a
+small DSL embedded in Python. Just like Hyperscript, the default entry point is
+the :func:`hyperpython.h` function:
 
 >>> from hyperpython import h
->>> elem = h('p', {'class': 'hello'}, 'Hello World!')
+>>> elem = h('p', {'class': 'hello'}, ['Hello World!'])
+
+.. _Hyperscript: https://github.com/hyperhype/hyperscript
 
 This can be converted to HTML by calling ``str()`` on the element:
 
 >>> print(elem)
 <p class="hello">Hello World!</p>
 
-The p tag can also be created by the standalone p function (and we have a
-corresponding function to each valid HTML5 tag).
+It accepts Hyperscript's ``h(tag, attributes, list_of_children)`` signature,
+but we encourage to use more idiomatic Python version that uses keyword arguments to
+represent attributes instead of a dictionary. If the list of children contains a
+single element, we can also omit the brackets:
+
+>>> h('p', 'Hello World!', class_='hello') == elem
+True
+
+Notice in the snippet above that we had to escape the "class" attribute because
+it is a reserved word in Python. Hyperpython maps Python keyword arguments by replacing
+underscores with dashes and by escaping Python reserved words such as "class", "for"
+"from", etc with a trailing underscore.
 
->>> print(p({'class': 'hello'}, 'Hello World!'))
+Elements can be be more conveniently created with standalone functions representing
+specific tags:
+
+>>> print(p('Hello World!', class_='hello'))
 <p class="hello">Hello World!</p>
 
-There is also no problem with nested structures:
+In Python, keyword arguments cannot appear after positional arguments. This means
+that attributes are placed *after* the list of children, which isn't natural to
+represent HTML. For simple elements like the ones above, it does not hinders
+legibility, but for larger structures it can be a real issue. Hyperpython
+provides two alternatives. The first uses the index notation:
+
 
 >>> from hyperpython import div, p, h1
 >>> fragment = \
@@ -45,10 +65,24 @@ There is also no problem with nested structures:
 ... p('Now you can write HTML in Python!'),
 ... ]
 
-HyperPython returns a DOM-like structure which we can introspect, query and
-modify later. The main usage, of course, is to generate strings of HTML source
-code. We can apply the str() function for a compact representation of the output
-code or call ``.pretty()`` method to to get a more human-friendly output.
+The second alternative is to use the "children" pseudo-attribute. This is the
+approach taken by some Javascript libraries such as React:
+
+>>> fragment = \
+... div(class_="alert-box",
+... children = [
+... h1('Hello Python'),
+... p('Now you can write HTML in Python!'),
+... ])
+
+
+Hyperpython returns a DOM-like structure which we can introspect, query and
+modify later. The main usage, of course, is to render strings of HTML source
+code. We expect that the main use of Hyperpython will be to complement (or even replace)
+the templating language in a Python web application. That said, Hyperpython generates a
+very compact HTML that is efficient to generate and transmit over the wire. To
+get a more human-friendly output (and keep your sanity while debugging), use
+the .pretty() method:
 
 >>> print(fragment.pretty())
 <div class="alert-box">
@@ -58,41 +92,40 @@ code or call ``.pretty()`` method to to get a more human-friendly output.
 <BLANKLINE>
 
 
-Secret goal: replace templating
-===============================
+Replacing templates
+===================
 
 The goal of ``hyperpython`` is to replace a lot of work that would be traditionally
 done with a template engine such as Jinja2 by Python code that generates HTML
-fragments. Templating languages are obviously more efficient than pure Python for
-string interpolation, and should work fine for simple documents. For large systems,
-however, templating can be tedious to create and very hard to maintain.
-Templating is usually not a good answer to handle growing complexity.
-
-Many recent Javascript libraries had played with direct manipulation of DOM or
-virtual DOM nodes sidestepping the whole business of creating intermediate
-HTML strings. React was probably the library that popularized this idea. As they
+fragments. Templating languages are obviously more expressive than pure Python for
+string interpolation, and are a perfect match for ad hoc documents. For large systems,
+they offer little in terms of architecture, organization and code reuse.
+
+A recent trend in Javascript is to promote direct creation of DOM or
+virtual DOM nodes sidestepping the whole business of rendering intermediate
+HTML strings. React was probably the library that better popularized this idea. As they
 nicely put, "Templates separate technologies, not concerns". There is no point
-on choosing a deliberately underpowered templating language that has poorly
-communicates with your data sources and outputs your document in a flat string
-representation since it does not improve architecture or organization.
+on choosing a deliberately underpowered programming language that integrates
+poorly with your data sources just to output structured documents in a flat string
+representation.
 
 The same lesson can be applied to Python on the server side. With Hyperpython,
-we generate HTML directly in Python, instead of passing through an intermediate
-templating step.
+we can generate HTML directly in Python. Hyperpython plays nicely with
+existing templating systems, but it makes easy to migrate parts of your rendering
+sub-system to Python.
 
 For those afraid of putting too much logic on templates, we recognize that
 Hyperpython doesn't prevent anyone from shooting themselves on the foot, but neither
-do any minimally powerful templating language. The discipline we must exercise
-is to keep business logic separated from view logic (i.e., separate concerns).
-Our advice is to break your code in small pieces and compose those pieces in
-simple and predictable ways. Incidentally, this is a good advice for any piece
-of code ;).
+do any minimally powerful templating engine. It always requires some discipline to
+keep business logic separated from view logic. Our advice is to break code in
+small pieces and compose those pieces in simple and predictable ways.
+Incidentally, this is a good advice for any piece of code ;).
 
 
 Can it be used on Django? Flask? Etc?
 =====================================
 
-Yes! Hyperpython is completely framework agnostic. We have a few optional
+Of course! Hyperpython is completely framework agnostic. We have a few optional
 integrations with Django, but it does not prevent Hyperpython of being used
 in other frameworks or without any framework at all. It implements the __html__
 interface which is recognized by most templating engines in Python. That way, it

docs/apidoc.rst

@@ -29,16 +29,24 @@ same names of all HTML tags.
 .. autofunction:: h
 
 
-Communication with external Python objects
-------------------------------------------
+Creation of HTML elements for Python objects
+--------------------------------------------
 
-.. module:: hyperpython.components
+.. autofunction:: html
 .. autofunction:: render
-.. autofunction:: render_html
+.. autofunction:: fragment
+
+
+Hyperpython components
+----------------------
+
+.. module:: hyperpython.components
+
+All functions bellow belongs to the :mod:`hyperpython.components` module.
 
 
 Hyperlinks
-----------
+~~~~~~~~~~
 
 .. autofunction:: hyperlink
 .. autofunction:: url
@@ -48,7 +56,7 @@ Hyperlinks
 
 
 HTML data structures
-....................
+~~~~~~~~~~~~~~~~~~~~
 
 Those functions convert Python data structures to their natural HTML
 representations.
@@ -59,7 +67,7 @@ representations.
 
 
 Icons
-.....
+~~~~~
 
 Generic icon support using the <i> tag and helper functions for Font Awesome
 icons.
@@ -70,6 +78,6 @@ icons.
 
 
 Text
-....
+~~~~
 
 .. autofunction:: markdown