feat(visuals): defs are now more readable

This works with a new `indent` and `unindent` filters respectively.
There are a few things to consider, but I have understood how it works
and can handle it.
There is some overhead just to give me nicer visuals ... might choose
a different route, like annotations.

src/mako/lib/lib.mako

@@ -1,10 +1,11 @@
 <%! from util import (activity_split, put_and, md_italic, split_camelcase_s, canonical_type_name, 
-                      rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block)  %>\
+                      rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block,
+                      unindent, indent)  %>\
 <%namespace name="util" file="util.mako"/>\
 
 ## If rust-doc is True, examples will be made to work for rust doc tests. Otherwise they are set 
 ## for github markdown.
-<%def name="docs(c, rust_doc=True)">\
+<%def name="docs(c, rust_doc=True)" filter="unindent">\
 <%
     # fr == fattest resource, the fatter, the more important, right ?
     fr = None
@@ -16,86 +17,83 @@
         resource, activity = activity_split(an)
         amap.setdefault(resource, list()).append(activity)
 %>\
-# Features
+    # Features
 
-Handle the following *Resources* with ease ... 
+    Handle the following *Resources* with ease ... 
 
-% for r in sorted(amap.keys()):
-* ${split_camelcase_s(r)} (${put_and(md_italic(sorted(amap[r])))})
-% endfor
+    % for r in sorted(amap.keys()):
+    * ${split_camelcase_s(r)} (${put_and(md_italic(sorted(amap[r])))})
+    % endfor
 
-# Structure of this Library
+    # Structure of this Library
 
-The API is structured into the following primary items:
+    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*
+    * **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:
+    Generally speaking, you can invoke *Activities* like this:
 
-```Rust,ignore
-let r = hub.resource().activity(...).${api.terms.action}()
-```
+    ```Rust,ignore
+    let r = hub.resource().activity(...).${api.terms.action}()
+    ```
 
-Or specifically ...
+    Or specifically ...
 
-```ignore
+    ```ignore
 % for an, a in c.sta_map[fr.id].iteritems():
-<%
-    resource, activity = activity_split(an)
-%>\
-let r = hub.${resource}().${activity}(...).${api.terms.action}()
+<% 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 (not shown here). 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.
+    The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities` 
+    supports various methods to configure the impending operation (not shown here). 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*)
+    # Usage (*TODO*)
 
-${'##'} Instantiating the Hub
+    ${'##'} Instantiating the Hub
 
-${self.hub_usage_example(rust_doc)}\
+${self.hub_usage_example(rust_doc) | indent}\
 
-**TODO** Example calls - there should soon be a generator able to do that with proper inputs
-${'##'} About error handling
+    **TODO** Example calls - there should soon be a generator able to do that with proper inputs
+    ${'##'} About error handling
 
-${'##'} About Customization/Callbacks
-
-[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
-[google-go-api]: https://github.com/google/google-api-go-client
+    ${'##'} About Customization/Callbacks
 
+    [builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
+    [google-go-api]: https://github.com/google/google-api-go-client
 </%def>
 
 ## Sets up a hub ready for use. You must wrap it into a test function for it to work
 ## Needs test_prelude.
-<%def name="test_hub(hub_type)">\
-use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
-use std::default::Default;
+<%def name="test_hub(hub_type)" filter="unindent">\
+    use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
+    use std::default::Default;
 
-use ${util.library_name()}::${hub_type};
+    use ${util.library_name()}::${hub_type};
 
-// Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, 
-// among other things.
-let secret: ApplicationSecret = Default::default();
-// Instantiate the authenticator. It will choose a suitable authentication flow for you, 
-// unless you replace  `None` with the desired Flow
-// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
-// You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
-let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
-                              hyper::Client::new(),
-                              <MemoryStorage as Default>::default(), None);
-let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\
+    // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`, 
+    // among other things.
+    let secret: ApplicationSecret = Default::default();
+    // Instantiate the authenticator. It will choose a suitable authentication flow for you, 
+    // unless you replace  `None` with the desired Flow
+    // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
+    // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
+    let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
+                                      hyper::Client::new(),
+                                      <MemoryStorage as Default>::default(), None);
+    let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\
 </%def>
 
 ## You will still have to set the filter for your comment type - either nothing, or rust_doc_comment !
@@ -116,11 +114,11 @@ ${self.test_hub(canonical_type_name(canonicalName))}\
 </%block>
 </%def>
 
-<%def name="license()">\
-# License
-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].
+<%def name="license()" filter="unindent">\
+    # License
+    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].
 
-[repo-license]: ${cargo.repo_base_url + 'LICENSE.md'}
+    [repo-license]: ${cargo.repo_base_url + 'LICENSE.md'}
 </%def>

src/mako/lib/util.mako

@@ -9,17 +9,17 @@ DO NOT EDIT !\
 </%def>
 
 ## This will only work within a substitution, not within python code
-<%def name="to_api_version(v)">\
+<%def name="to_api_version(v)" buffered="True">\
 	<% assert len(v) >= 2 and v[0] == 'v'%>\
 	## convert it once to int, just to be sure it is an int
 ${v[1:]}\
 </%def>
 
-<%def name="repository_url()">\
+<%def name="repository_url()" buffered="True">\
 ${cargo.repo_base_url}/${OUTPUT_DIR}\
 </%def>
 
-<%def name="library_name()">\
+<%def name="library_name()" buffered="True">\
 ${util.library_name(name, version)}\
 </%def>
 

src/mako/lib/util.py

@@ -2,6 +2,7 @@ import re
 import collections
 
 re_linestart = re.compile('^', flags=re.MULTILINE)
+re_first_4_spaces = re.compile('^    ', flags=re.MULTILINE)
 
 USE_FORMAT = 'use_format_field'
 TYPE_MAP = {'boolean' : 'bool',
@@ -43,6 +44,16 @@ def rust_comment(s):
 def hash_comment(s):
     return re_linestart.sub('# ', s)
 
+# remove the first indentation (must be spaces !)
+def unindent(s):
+    return re_first_4_spaces.sub('', s)
+
+# add 4 spaces to the beginning of a line.
+# useful if you have defs embedded in an unindent block - they need to counteract. 
+# It's a bit itchy, but logical
+def indent(s):
+    return re_linestart.sub('    ', s)
+
 # return s, with trailing newline
 def trailing_newline(s):
     if not s.endswith('\n'):