Moving forward with documentation

docs/source/conf.py

@@ -108,7 +108,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ToscaWidgets2doc'
+htmlhelp_basename = 'tw2doc'
 
 
 # -- Options for LaTeX output ------------------------------------------------

docs/source/forms.rst

@@ -1,3 +1,5 @@
+.. _forms:
+
 Forms
 =====
 
@@ -42,8 +44,13 @@ to specify where the form should be submitted.
     you probably want the action to be a ``tg.lurl`` to
     ensure that prefix of your application is retained.
 
+Submitting Forms
+~~~~~~~~~~~~~~~~
+
+Here validation and submitting...
+
 Form Buttons
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 
 By default, each form comes with a **submit** button.
 
@@ -235,6 +242,10 @@ the children using ``w.children.child_name``::
 Bultin widgets
 --------------------------
 
+``tw2.forms`` package comes with a bunch of builtin
+widgets that can help you build the most common kind
+of forms.
+
 .. automodule:: tw2.forms.widgets
     :members:
     :member-order: bysource

docs/source/index.rst

@@ -50,6 +50,7 @@ Content
 .. toctree::
   :maxdepth: 2
 
+  getstarted
   widget
   validation
   forms

docs/source/widget.rst

@@ -9,8 +9,8 @@ a template that describes what should be displayed, one ore more
 resources (javascript or CSS) needed during display and might have
 some logic that has to be executed every time the widget is displayed.
 
-Declaring Widgets
------------------
+Using Widgets
+-------------
 
 A typical widget will look like::
 
@@ -36,7 +36,7 @@ file you can also set the ``inline_engine_name`` option
 to one of the template engines and provide the template
 as a string::
 
-    class HelloWidgetTemplate(twc.Widget):
+    class HelloWidgetTemplate(tw2.core.Widget):
         inline_engine_name = "kajiki"
         template = """
             <i>Hello <span py:for="i in range(1, 4)">${i}, </span></i>
@@ -46,9 +46,111 @@ Displaying a widget is as simple as calling the :meth:`.Widget.display`::
 
     HelloWidgetTemplate.display()
 
+Widget value
+~~~~~~~~~~~~
+
+Each Widget has a special paramter, which is ``value``. This parameter
+contains the current state of the widget. Value will usually be
+a single value or a dictionary containing multiple values 
+(in case of :class:`tw2.core.widgets.CompoundWidget`).
+
+You can use the value to drive what the widget should show once
+displayed::
+
+    class HelloWidgetValue(tw2.core.Widget):
+        inline_engine_name = "kajiki"
+        template = """
+            <i>Hello ${w.value}</i>
+        """
+
+    >>> HelloWidgetValue.display(value='World')
+    Markup('<i>Hello World</i>')
+
+:class:`tw2.core.CompoundWidget` can contain multiple subwidgets
+(children) and their value is typically a ``dict`` with values
+for each one of the children::
+
+    class CompoundHello(tw2.core.CompoundWidget):
+        inline_engine_name = "kajiki"
+        template = """
+            <div py:for="c in w.children">
+                ${c.display()}
+            </div>
+        """
+
+        name = HelloWidgetValue()
+        greeter = tw2.core.Widget(inline_engine_name="kajiki", 
+                                  template="<span>From ${w.value}</span>")
+
+    >>> CompoundHello(value=dict(name="Mario", greeter="Luigi")).display()
+    Markup('<div><span>Hello Mario</span></div><div><span>From Luigi</span></div>')
+
+Children of a compound widget (like :ref:`forms`) can be accessed
+both as a list iterating over ``w.children`` or by name using
+``w.children.childname``.
+
 Parameters
-----------
+~~~~~~~~~~
+
+Widgets might require more information than just their value to display,
+or might allow more complex kind of configurations. The options required
+to configure the widget are provided through :class:`tw2.core.Param` objects
+that define which options each widget supports.
+
+If you want your widget to be configurable, you can make available one or more
+options to your Widget and allow any user to set them as they wish::
+
+    class HelloWidgetParam(tw2.core.Widget):
+        inline_engine_name = "kajiki"
+        template = """
+            <i>Hello ${w.name}</i>
+        """
+
+        name = tw2.core.Param(description="Name of the greeted entity")
+
+The parameters can be provided any time by changing configuration of
+a widget::
+
+    >>> w = HelloWidgetParam(name="Peach")
+    >>> w.display()
+    Markup('<i>Hello Peach</i>')
+    >>> w2 = w(name="Toad")
+    >>> w2.display()
+    Markup('<i>Hello Toad</i>')
+
+Or can be provided at ``display`` time itself::
+
+    >>> HelloWidgetParam.display(name="Peach")
+    Markup('<i>Hello Peach</i>')
+
+Builtin Widgets
+~~~~~~~~~~~~~~~
+
+The ``tw2.core`` packages comes with the basic buildin blocks needed
+to create your own custom widgets.
 
 .. automodule:: tw2.core.widgets
     :members:
     :member-order: bysource
+    :exclude-members: WidgetMeta, WidgetBunch, DisplayOnlyWidgetMeta, default_content_type
+
+Resources
+---------
+
+ToscaWidgets comes with resources management for widgets too.
+
+Some widgets might be complex enough that they need external
+resources to work properly. Typically those are CSS stylesheets
+or Javascript functions.
+
+The need for those can be specified in the :attr:`.Widget.resources`
+param, which is a list of resources the widget needs to work properly
+
+Resource kinds
+~~~~~~~~~~~~~~
+
+.. automodule:: tw2.core.resources
+    :members:
+    :member-order: bysource
+    :exclude-members: JSSymbol, ResourcesApp, prepare
+    :no-inherited-members: