docs(lib): library overview as far as possible

Everything we have, feature wise, is now documented in a first version
at least.

We shall keep this uptodate with what we are implementing, which also
helps figuring out a good api.

src/mako/README.md.mako

@@ -1,10 +1,13 @@
-<%! import util as pyutil %>\
+<%
+	from util import (markdown_comment, new_context)
+	c = new_context(resources)
+%>\
 <%namespace name="lib" file="lib/lib.mako"/>\
 <%namespace name="util" file="lib/util.mako"/>\
-<%block filter="pyutil.markdown_comment">\
+<%block filter="markdown_comment">\
 <%util:gen_info source="${self.uri}" />\
 </%block>
 The `${util.library_name()}` library allows access to all features of *${canonicalName}*.
 
-<%lib:docs />
+${lib.docs(c)}
 <%lib:license />

src/mako/lib.rs.mako

@@ -1,19 +1,18 @@
 <% 
-	import util 
-	nested_schemas = list(util.iter_nested_types(schemas))
+	from util import (iter_nested_types, new_context, rust_comment, rust_module_doc_comment, )
+	nested_schemas = list(iter_nested_types(schemas))
 
-	sta_map, fqan_map = util.build_activity_mappings(resources)
-	c = util.Context(sta_map, fqan_map)
+	c = new_context(resources)
 %>\
 <%namespace name="lib" file="lib/lib.mako"/>\
 <%namespace name="mutil" file="lib/util.mako"/>\
 <%namespace name="schema" file="lib/schema.mako"/>\
-<%block filter="util.rust_comment">\
+<%block filter="rust_comment">\
 <%mutil:gen_info source="${self.uri}" />\
 </%block>
 
-<%block filter="util.rust_module_doc_comment">\
-<%lib:docs />\
+<%block filter="rust_module_doc_comment">\
+${lib.docs(c)}
 </%block>
 #![feature(core)]
 #![allow(non_snake_case)]

src/mako/lib/lib.mako

@@ -1,17 +1,79 @@
-<%! import util %>\
-<%namespace name="util" file="lib/util.mako"/>\
+<%! from util import (activity_split, put_and, md_italic, split_camelcase_s)  %>\
+<%namespace name="util" file="util.mako"/>\
 
-<%def name="docs()">\
-TODO: Library level fully fledged documentation, incuding **summary** and **usage**.
-And another line, for testing
+<%def name="docs(c)">\
+<%
+    # fr == fattest resource, the fatter, the more important, right ?
+    fr = None
+    fr = sorted(schemas.values(), key=lambda s: (len(c.sta_map.get(s.id, [])), len(s.get('properties', []))), reverse=True)[0]
 
-# Activities
+    # resouce -> [activity, ...]
+    amap = dict()
+    for an in c.fqan_map:
+        resource, activity = activity_split(an)
+        amap.setdefault(resource, list()).append(activity)
+%>\
+# Features
+
+Handle the following *Resources* with ease ... 
+
+% for r in sorted(amap.keys()):
+* ${split_camelcase_s(r)} (${put_and(md_italic(sorted(amap[r])))})
+% endfor
+
+# Structure of this Library
+
+The API is structured into the following primary items:
+
+* **Hub**
+    * a central object to maintain state and allow accessing all *Activities*
+* **Resources**
+    * primary types that you can apply *Activities* to
+    * a collection of properties and *Parts*
+    * **Parts**
+        * a collection of properties
+        * never directly used in *Activities*
+* **Activities**
+    * operations to apply to *Resources*
+
+Generally speaking, you can invoke *Activities* like this:
+
+```Rust,ignore
+let r = hub.resource().activity(...).${api.terms.action}()
+```
+
+Or specifically ...
+
+```ignore
+% for an, a in c.sta_map[fr.id].iteritems():
+<%
+    resource, activity = activity_split(an)
+%>\
+let r = hub.${resource}().${activity}(...).${api.terms.action}()
+% endfor
+```
+
+The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities` 
+supports various methods to configure the impending operation. It is made such that all required arguments have to be 
+specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
+The `${api.terms.action}()` method performs the actual communication with the server and returns the respective result.
+
+# Usage (*TODO*)
+
+${'##'} Instantiating the Hub
+
+${'##'} About error handling
+
+${'##'} About costumization
+
+[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
+[google-go-api]: https://github.com/google/google-api-go-client
 
 </%def>
 
 <%def name="license()">\
 # License
-The **${util.library_name(name, version)}** library was generated by ${util.put_and(copyright.authors)}, and is placed 
+The **${util.library_name()}** library was generated by ${put_and(copyright.authors)}, and is placed 
 under the *${copyright.license_abbrev}* license.
 You can read the full text at the repository's [license file][repo-license].
 

src/mako/lib/schema.mako

@@ -1,12 +1,12 @@
-<%! import util %>\
+<%! from util import (schema_markers, rust_doc_comment, mangle_ident, to_rust_type, put_and, IO_TYPES, activity_split) %>\
 ## Create new schema with everything.
 ## 's' contains the schema structure from json to build
 <%def name="new(s, c)">\
 <% 
 	assert s.type == "object" 
-	markers = util.schema_markers(s, c)
+	markers = schema_markers(s, c)
 %>\
-<%block filter="util.rust_doc_comment">\
+<%block filter="rust_doc_comment">\
 ${doc(s, c)}\
 </%block>
 #[derive(RustcEncodable, RustcDecodable, Default, Clone)]
@@ -14,8 +14,8 @@ pub struct ${s.id}\
 % if 'properties' in s:
  {
 % for pn, p in s.properties.iteritems():
-	${p.get('description', 'no description provided') | util.rust_doc_comment}
-	pub ${util.mangle_ident(pn)}: ${util.to_rust_type(s.id, pn, p)},
+	${p.get('description', 'no description provided') | rust_doc_comment}
+	pub ${mangle_ident(pn)}: ${to_rust_type(s.id, pn, p)},
 % endfor
 }
 % else:
@@ -34,10 +34,10 @@ ${s.get('description', 'There is no detailed description.')}
 # Activities
 
 This type is used in activities, which are methods you may call on this type or where this type is involved in. 
-The list links the activity name, along with information about where it is used (one of ${util.put_and(list('*%s*' % t 
-																							for t in util.IO_TYPES))}).
+The list links the activity name, along with information about where it is used (one of ${put_and(list('*%s*' % t 
+																							for t in IO_TYPES))}).
 
-${''.join("* %s (%s)\n" % (util.activity_split(a)[1], iot and '|'.join(iot) or 'none') 
+${''.join("* %s (%s)\n" % (activity_split(a)[1], iot and '|'.join(iot) or 'none') 
 													for a, iot in c.sta_map[s.id].iteritems())}
 % else:
 

src/mako/lib/util.py

@@ -69,6 +69,13 @@ def put_and(l):
         return l[0]
     return ', '.join(l[:-1]) + ' and ' + l[-1]
 
+def md_italic(l):
+    return ['*%s*' % s for s in l]
+
+def split_camelcase_s(s):
+    s1 = re.sub('(.)([A-Z][a-z]+)', r'\1 \2', s)
+    return re.sub('([a-z0-9])([A-Z])', r'\1 \2', s1).lower()
+
 ## -- End Natural Language Utilities -- @}
 
 
@@ -237,6 +244,11 @@ def activity_name_to_type_name(an):
 
 Context = collections.namedtuple('Context', ['sta_map', 'fqan_map'])
 
+# return a newly build context from the given data
+def new_context(resources):
+    sta_map, fqan_map = build_activity_mappings(resources)
+    return Context(sta_map, fqan_map)
+
 # Expects v to be 'v\d+', throws otherwise
 def to_api_version(v):
     assert len(v) >= 2 and v[0] == 'v'