update documentation

Author: fabiommendes

INSTALL.rst

@@ -20,6 +20,8 @@ option and execute as superuser by prepending the command with ``sudo``.
 Troubleshoot
 ------------
 
+Hyperpython requires Python 3.6+. Make sure you use an updated distribution.
+
 Windows users may find that these command will only works if typed from Python's
 installation directory.
 

README.rst

@@ -13,32 +13,30 @@
 
 
 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 being something similar to React to
-Python, but without the JSX. This lib 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 `h` function:
+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:
 
 >>> from hyperpython import h
 >>> elem = h('p', {'class': 'hello'}, 'Hello World!')
 
 This can be converted to HTML by calling ``str()`` on the element:
 
->>> print(str(elem))
+>>> print(elem)
 <p class="hello">Hello World!</p>
 
-Notice that the p tag could also be imported as a function from the hyperpython
-namespace.
+The p tag can also be created by the standalone p function (and we have a
+corresponding function to each valid HTML5 tag).
 
-Python and HTML have very different semantics. HTML's syntax gravitates
-around tag attributes + children nodes and does not have a very natural
-counterpart in most programming languages. It is obviously very easy to build
-HTML tag in a imperative style, but the end result often feels awkward.
-HyperPython embeds a simple DSL mini-language to declare HTML fragments in a
-more natural way:
+>>> print(p({'class': 'hello'}, 'Hello World!'))
+<p class="hello">Hello World!</p>
+
+There is also no problem with nested structures:
 
 >>> from hyperpython import div, p, h1
 >>> fragment = \
@@ -47,19 +45,56 @@ more natural way:
 ... p('Now you can write HTML in Python!'),
 ... ]
 
-HyperPython stores the DOM node for a later use. We can introspect, query and
-modify the result.
-
->>> fragment.attrs['id'] = 'element-id'
->>> len(fragment.children)
-2
-
-str() prints a very compact HTML. Use ``.pretty()`` to get a more human-friendly
-version of the HTML.
+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.
 
 >>> print(fragment.pretty())
 <div class="alert-box" id="element-id">
  <h1>Hello Python</h1>
  <p>Now you can write HTML in Python!</p>
 </div>
-<BLANKLINE>
+<BLANKLINE>
+
+
+Secret goal: replace templating
+===============================
+
+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
+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.
+
+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.
+
+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 ;).
+
+
+Can it be used on Django? Flask? Etc?
+=====================================
+
+Yes! 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
+is possible to pass Hyperpython fragments to existing templates in Django, Jinja2
+and others.

docs/apidoc.rst

@@ -24,27 +24,27 @@ Functions
 ~~~~~~~~~
 
 The generic entry point is the :func:`h` function. It also has functions with
-same names of HTML tags.
+same names of all HTML tags.
 
 .. autofunction:: h
 
 
+Communication with external Python objects
+------------------------------------------
 
-Components
-----------
-
-Basic interfaces
-................
-
-.. automodule:: hyperpython.components
- :members: render, render_html
+.. module:: hyperpython.components
+.. autofunction:: render
+.. autofunction:: render_html
 
 
 Hyperlinks
-..........
+----------
 
-.. automodule:: hyperpython.components
- :members: hyperlink, url, a_or_p, a_or_span, breadcrumbs
+.. autofunction:: hyperlink
+.. autofunction:: url
+.. autofunction:: a_or_p
+.. autofunction:: a_or_span
+.. autofunction:: breadcrumbs
 
 
 HTML data structures
@@ -53,8 +53,9 @@ HTML data structures
 Those functions convert Python data structures to their natural HTML
 representations.
 
-.. automodule:: hyperpython.components
- :members: html_list, html_map, html_table
+.. autofunction:: html_list
+.. autofunction:: html_map
+.. autofunction:: html_table
 
 
 Icons
@@ -63,12 +64,15 @@ Icons
 Generic icon support using the <i> tag and helper functions for Font Awesome
 icons.
 
-.. automodule:: hyperpython.components
- :members: icon, icon_link, fa_icon, fab_icon, fa_link, fab_link
+.. autofunction:: icon
+.. autofunction:: icon_link
+.. autofunction:: fa_icon
+.. autofunction:: fab_icon
+.. autofunction:: fa_link
+.. autofunction:: fab_link
 
 
 Text
 ....
 
-.. automodule:: hyperpython.components
- :members: markdown
+.. autofunction:: markdown

docs/faq.rst

@@ -17,8 +17,8 @@ Will it ever support Python 3.5 or lower?
 
 Probably not. Hyperpython uses a functional programming library called Sidekick_
 which requires Python 3.6+. It is not impossible to port this library to 3.5,
-but it is a very low priority for the developers. You can make this happen by
-sending pull requests ;)
+but it is a very low priority for the developers. Of course, you can make this
+happen by sending pull requests ;)
 
 
 .. _Sidekick: https://github.com/fabiommendes/sidekick/

docs/index.rst

@@ -12,9 +12,9 @@ a Python sub-language.
 
  Overview <overview.rst>
  Installation instructions <install.rst>
- Templating <templating.rst>
- Django integration <django.rst>
+ Tutorial <tutorial.rst>
  API documentation <apidoc.rst>
+ Django integration <django.rst>
  Frequently asked questions <faq.rst>
  Roadmap <roadmap.rst>
  License <license.rst>

docs/templating.rst renamed to docs/tutorial.rst

@@ -1,34 +1,8 @@
 .. module:: hyperpython
 
-==========
-Templating
-==========
-
-The goal of ``hyperpython`` is to replace a lot of work that would traditionally
-be 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 better for simple cases. For long documents,
-however, templating can be very repetitive. HTML is a structured format and we
-eliminate duplication by composing simple functions and using other standard
-techniques in Software Engineering.
-
-It is becoming increasingly common in the Javascript world to use more
-structured approaches to generate HTML code (or direct creation of DOM/virtual DOM nodes).
-React was probably the library that popularized this idea. As they elegantly put,
-"Templates separate technologies, not concerns". The point being that it is
-better to generate DOM nodes in Javascript instead of choosing a deliberately
-underpowered language that has a that poorly communicates with your data
-sources created in Javascript. The same lesson can be applied to Python on
-the server side.
-
-For those afraid of putting too much logic on templates, we recognize that
-Hyperpython doesn't prevent anyone from shooting itself on the foot, but neither
-does any minimally powerful templating language. The discipline we should exercise
-is to keep business logic separate from view logic. Our advice is:
-*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 ;).
-
-Let us dive in!
+========
+Tutorial
+========
 
 A simple example
 ================
@@ -55,17 +29,17 @@ actions (this is a random example taken from Bootstrap website).
  </ul>
  </div>
 
-Of course we could translate this directly into Hyperpython code by calling the
-corresponding ``div()``'s, ``button()``'s, etc. But first, let us break up this
-mess into smaller pieces.
+Of course we could translate this directly into Hyperpython by calling the
+corresponding ``div()``, ``button()``, etc functions. But first, let us break
+up this mess into smaller pieces.
 
 .. code-block:: python
 
  from hyperpython import button, div, p, ul, li, span, a, classes
 
  def menu_button(name, caret=True, class_=None, **kwargs):
  if caret:
- children = [name, ' ', span(caret)]
+ children = [name, ' ', span('caret')]
  else:
  children = [name]
 
@@ -129,8 +103,8 @@ Look how nice it is now :)
 How does it work?
 =================
 
-Hyperpython HTML syntax is just regular Python wrapped in a HTML-wannabe DSL.
-How does it work?
+Hyperpython syntax is just regular Python wrapped in a HTML-wannabe DSL. How
+does it work?
 
 Take the example:
 
@@ -143,8 +117,8 @@ Take the example:
  ]
 
 In Hyperpython, we can declare attributes as keyword arguments and children as a
-index access. This clever abuse of Python syntax is good to creating expressive
-representations of HTML documents. Under the hood, Python call div() and
+index access. This clever abuse of Python syntax is good for creating expressive
+representations of HTML documents. Under the hood, Python calls div() and
 generates an :class:`Element` instance. Indexing is used to insert the given
 elements as children and then return the tag itself as a result. We encourage
 using this syntax only during element creation in order to avoid confusion.
@@ -167,10 +141,9 @@ Tag functions also accept a few alternative signatures:
  Children can also be passed as a keyword argument.
  This generates ``<h1 class="foo">title</h1>``.
 
-In HTML, tag attributes are all stringly typed. This is far from ideal and can
-be easily fixed since we are representing HTML from a more rigorously typed
-language. Hyperpython does the following coercions when interpreting
-attributes:
+In HTML, all tag attributes are all stringly typed. This is far from ideal and can
+be easily fixed since we are representing HTML from a typed language.
+Hyperpython does the following coercions when interpreting attributes:
 
 "class" attribute:
  Hyperpython expects a list of strings. If a single string is given, it is
@@ -190,24 +163,22 @@ Imperative interface
 We encourage users to adopt the declarative API and generally treat tags
 as immutable structures. Hyperpython does not enforce immutability and actually
 offers some APIs to change data structures inplace. Once a tag is created, it
-is possible to change it's attributes dictionary and list of children. We
-encourage to use the appropriate method instead of manipulating those data
-structures directly.
+is possible to change it's attributes dictionary and list of children. There
+are also a few methods designed to manipulate Hyperpython data structures.
 
 >>> elem = div('foo', class_='elem')
 >>> elem.add_child('bar')
 >>> print(elem)
 <div class="elem">foobar</div>
 
-Similarly to the children property, attributes are also exposed:
+Attributes are also exposed in the .attrs dictionary:
 
 >>> elem.attrs['data-answer'] = 42
 >>> elem.attrs.keys()
 dict_keys(['class', 'data-answer'])
 
-Manipulating the list of classes and the element id also introduces specialized
-methods and attributes. The ``.id`` and ``.classes`` attributes expose those
-two properties.
+The "class" and "id" attributes are also exposed directly from the tag object
+since they are used so often:
 
 >>> elem = div('foo', class_='class', id='id')
 >>> elem.id, elem.classes

src/hyperpython/tags.py

@@ -10,13 +10,30 @@
 
 def h(tag, *args, children=None, **attrs):
  """
- Create a tag.
+ Creates a tag.
 
- * ``h('h1', 'content')``
- * ``h('h1', {'class': 'title'}, 'content')``
- * ``h('h1', 'title', class_='title')``
- * ``h('h1', class_='title')['content']``
- * ``h('h1', class_='title', children=['content'])``
+ It has many different signatures:
+
+ h('h1', 'content')
+ Content can be a string, a child node or a list of children.
+
+ h('h1', {'class': 'title'}, 'content')
+ If the second argument is a dictionary, it is interpreted as tag
+ attributes.
+
+ h('h1', 'title', class_='title')
+ Keyword arguments are also interpreted a attributes. The h function
+ makes a few changes: underscores are converted to dashes and trailing
+ underscores after Python keywords such as ``class_``, ``for_``, etc are
+ ignored.
+
+ h('h1', class_='title')['content']
+ Children can also be specified using squared brackets. It understands
+ strings, other tags, and lists of tags.
+
+ h('h1', class_='title', children=['content'])
+ Optionally, the list of children nodes can be specified as a keyword
+ argument.
  """
  attr_name = html_safe_natural_attr
  is_void = tag in VOID_ELEMENTS