erp5_data_notebook: documentation about environment object and astor egg added

@Tyagov this is the slapos part of nexedi/erp5!131. It includes:

- Documentation on top on each Jupyter notebook about why and how we use the
environment object.

- astor egg, used to convert abstract syntax tree objects back to source
code.

/reviewed-on nexedi/slapos!76

software/ipython_notebook/software.cfg

@@ -17,6 +17,7 @@ parts =
 ; ipython notebook component
 eggs +=
   requests
+  astor
   ${scipy:egg}
   ${pandas:egg}
   ${scikit-learn:egg}
@@ -52,7 +53,7 @@ md5sum = ab6e78ea20855e07d388b5b86d1770fe
 [custom-js]
 <= download-file-base
 filename = custom.js.jinja
-md5sum = 0e8262d04a6dafbc1b77d95aea2192bc
+md5sum = a851a68667a4e676cfa86b34a86b4239
 
 [instance-jupyter]
 recipe = slapos.recipe.template:jinja2
@@ -176,3 +177,5 @@ pickleshare = 0.5
 # ipython==4.0.0
 # notebook==4.0.6
 traitlets = 4.1.0b1
+
+astor = 0.5

software/ipython_notebook/template/custom.js.jinja

@@ -86,7 +86,7 @@ $([IPython.events]).on('notebook_loaded.Notebook', function(){
   var display_text="<div class='output_subarea output_text output_result'>\
   <pre>Follow these steps to customize your notebook with ERP5 kernel :-</br>\
   1. Add <b>%erp5_url &lt;your_erp5_url&gt;/erp5/Base_executeJupyter</b>.</br>\
-  Make sure you have 'erp5_data_notebook' business template installed in your erp5</br>\
+  Make sure you have 'erp5_data_notebook' business template installed in your ERP5</br>\
   2. <b>%notebook_set_reference &lt;your_notebook_refernce&gt;</b></br>\
   It would be better to set the reference to match with erp5 reference pattern.</br>\
   3. <b>%erp5_user &lt;your_erp5_username&gt;</b></br>\
@@ -96,8 +96,26 @@ $([IPython.events]).on('notebook_loaded.Notebook', function(){
   <b>%my_notebooks</b> -This is used to display all the notebooks created by the specific user.</br>\
   NOTE: Do not dynamically alter imported module objects as they are not being saved in DB, </br>\
   so changes to them would be disregarded and would throw an error.</br>\
+  <p><u>About classes, functions and global state on modules:</u></p>\
+  Your code is going to be executed by ERP5, which can have many nodes </br>\
+  and there is no guarantee that your code is always going to be executed by the same server.</br>\
+  This means that objects which cannot be stored in the ZODB, like functions, classes and modules </br>\
+  won't be available across nodes. To solve this issue, you need to use a special object </br>\
+  called 'environment' to store your global setup. This object was designed to hold global </br>\
+  state and restore it for each code cell. Example:</br></br>\
+  <b>def my_setup():</br>\
+     # import modules, define functions and classes</br>\
+     # and set global state on modules</br>\
+     # return dict of variables to be available in code cells</br>\
+     {'my_var': 1}</br>\
+  environment.define(my_setup, 'my custom setup')</b></br></br>\
+  After you execute this cell, the <b>my_setup</b> function will run before each of the</br>\
+  following cells and the <b>my_var</b> variable will be created and set to 1.</br></br>\
+  <b>WARNING:</b> it is not recommended to have too many setup functions in the environment, </br>\
+  because they will be executed in every code cell and can cause a substantial slow down.\
   </pre></div>";
   if (kernelname=="erp5"){
   $('div#notebook-container').prepend(display_text);
   }
   });
+  
\ No newline at end of file

software/wendelin/software.cfg

@@ -19,6 +19,7 @@ initialization =
 extra-paths +=
   ${wendelin:location}
 eggs +=
+  astor
   ${scipy:egg}
   ${msgpack-python:egg}
   ${wendelin.core:egg}

stack/erp5/buildout.cfg

@@ -483,6 +483,7 @@ eggs =
   ${pycrypto-python:egg}
   ${scikit-learn:egg}
   lock_file
+  astor
   PyStemmer
   PyXML
   Pympler