From 11074ebf21cd1c7135784400ccc4b1d57f022a12 Mon Sep 17 00:00:00 2001 From: Boxiang Sun Date: Wed, 28 Aug 2019 10:44:21 +0200 Subject: [PATCH] erp5_notebook_tutorial: Add documentation about erp5 notebook --- ...otebook.Tutorial.1.Hello.World.001.en.html | 76 +++++ ...Notebook.Tutorial.1.Hello.World.001.en.xml | 322 ++++++++++++++++++ erp5_notebook_tutorial/bt/copyright_list | 1 + erp5_notebook_tutorial/bt/description | 1 + erp5_notebook_tutorial/bt/license | 1 + .../bt/template_format_version | 1 + ..._keep_last_workflow_history_only_path_list | 1 + erp5_notebook_tutorial/bt/template_path_list | 1 + erp5_notebook_tutorial/bt/title | 1 + 9 files changed, 405 insertions(+) create mode 100644 erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.html create mode 100644 erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.xml create mode 100644 erp5_notebook_tutorial/bt/copyright_list create mode 100644 erp5_notebook_tutorial/bt/description create mode 100644 erp5_notebook_tutorial/bt/license create mode 100644 erp5_notebook_tutorial/bt/template_format_version create mode 100644 erp5_notebook_tutorial/bt/template_keep_last_workflow_history_only_path_list create mode 100644 erp5_notebook_tutorial/bt/template_path_list create mode 100644 erp5_notebook_tutorial/bt/title diff --git a/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.html b/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.html new file mode 100644 index 0000000..bf037df --- /dev/null +++ b/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.html @@ -0,0 +1,76 @@ +

This is a tutorial to introduce how to create an ERP5 notebook.

+ +

Introduction

+ +

ERP5 notebook is unlike the tranditional notebook, such as Jupyter or Pyodidie. It is more like a static "report generate" tool rather than dynamically, interactively notebook tool. This article going to describe what should we do to use ERP5 notebook properly.

+ +

Create a notebook

+ +

Same as other ERP5 module, we can create a new ERP5 notebook under the Notebook Module.

+ +

ERP5 notebook is different from Pyodide notebook. Currently, Pyodide notebook is more interactively than ERP5 notebook, it executes cells successively and redirect the output to a widget which named "console". This "console" is not the browser's console, it created by Pyodide notebook to display all text output. In Pyodide notebook, the execution can be stopped in any cell. In ERP5 notebook, we are aim to provide a report generate tool. So ERP5 notebook will process the notebook as a whole. It not stoppable between any cells. And if we want to display something in the final report, we need to add the content explicity except the Python matplotlib figure. It means in a JS cell, we should create a HTML node, add content to it, then add this node to the DOM.

+ +

Despite this difference, we still using the iomd format(the former name is jsmd). This means the erp5 notebook contains different cells, like # js, # py, # md etc. Which represent JavaScript, Python, Markdown block, respectively. The text/code insides these cells will executed by corresponding parser. The Markdown contents will convert to HTML and get rendered in the final report.

+ +

If we only using the JS cell, the notebook could process it directly. If we need to process any Python cell, the notebook will loads and initializes the Pyodide core webassembly module. This step was automatically processed when the notebook met the first %% py cell. If we load Python extension explicity in a JS cell(see blow), the notebook will loads Pyodide core webassembly module if it haven't been done yet, and then loads the Python extension webassembly module.

+ +

It will take sometime to load the webassembly modules. The exact time is depends on your network. And it will take longer time if loads other Python extension.

+ +

JS cell

+

The notebook can launch the JS code which inside # js normally. We can put JS code in the JS cell, calculate something or modify the document DOM. But it doesn't display anything in the report page by default. If you want show anything, you have to create an element and add it to document.body. Like below:

+ + +# js +var div = document.createElement('div'), + pre = document.createElement('pre'), + result_element = document.createElement('code'), + result; + +result = 2 + 299492456; +result_element.innerHTML = result; +pre.appendChild(result_element); +div.appendChild(pre); +document.body.appendChild(div); + + +

Python cell

+ +

Python cell is similar to JS cell. But all Python text output, aka the value printed by print function, will redirect to the browser's console. E.g:

+ + + +print(4 + 38) + + +

This line of code will print value 42 in the browser's console.

+ +

But for the figure generated by Matplotlib. The notebook will render the content to the report directly.

+ +

Import Python extension

+ +

For the Python standard library, we can call import statement directly. But for the 3rd party extension, like matplotlib, numpy. We need to create a JS cell to import the extension explicity first. For example:

+ + +%% js +pyodide.loadPackage("matplotlib") + + +

The notebook will handle the dependency automatically. No need to import numpy manually first. Then we can call import matplotlib in the following Python cell. This pyodide.loadPackage is used for import the matplotlib webassembly module.

+ +

Currently, ERP5 notebook supports these 3rd party extension: cycler, kiwisolver, matplotlib, numpy, pyparsing, python-dateutil, pytz, scikit-learn, scipy.

+ +

Then let's see a simple Python example which use Matplotlib to draw a figure in the report:

+ + +import matplotlib.pyplot as plt + +plt.plot([1,23,2,4]) +plt.ylabel('some numbers') + +plt.show() + + +

This will display a simple figure in the final report.

+ +

Summary

+

This article introduced how to create a simple ERP5 notebook and launch JS, Python code. And the notebook are under development. Some features maybe changed. So this article will be update from time to time. Like we may redirect the output of a print function to the final report. And also add a parser in the notebook. If encountered a import statement which trying to import a 3rd party Python extension, let the notebook load it automatically.

\ No newline at end of file diff --git a/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.xml b/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.xml new file mode 100644 index 0000000..287f323 --- /dev/null +++ b/erp5_notebook_tutorial/PathTemplateItem/web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en.xml @@ -0,0 +1,322 @@ + + + + + + + + + + _Access_contents_information_Permission + + + Anonymous + Assignee + Assignor + Associate + Auditor + Manager + + + + + _Add_portal_content_Permission + + + Assignee + Assignor + Manager + + + + + _Change_local_roles_Permission + + + Assignor + Manager + + + + + _Modify_portal_content_Permission + + + Assignee + Assignor + Manager + + + + + _View_Permission + + + Anonymous + Assignee + Assignor + Associate + Auditor + Manager + + + + + content_md5 + + + + + + content_type + text/html + + + default_reference + erp5-Notebook.Tutorial.1.Hello.World + + + description + + + + + + id + erp5-Notebook.Tutorial.1.Hello.World.001.en + + + language + en + + + portal_type + Web Page + + + short_title + Hello World + + + title + ERP5 Notebook Tutorial 1 - Hello World + + + version + 001 + + + workflow_history + + AAAAAAAAAAI= + + + + + + + + + + + + + data + + + + document_publication_workflow + + AAAAAAAAAAM= + + + + edit_workflow + + AAAAAAAAAAQ= + + + + processing_status_workflow + + AAAAAAAAAAU= + + + + + + + + + + + + + + + + + + + action + publish_alive + + + actor + zope + + + comment + + + + error_message + + + + time + + + + + + + + + + + 1566921301.97 + UTC + + + + + + + validation_state + published_alive + + + + + + + + + + + + + + + + + action + edit + + + actor + zope + + + comment + + + + + + error_message + + + + serial + 978.2590.64831.3993 + + + state + current + + + time + + + + + + + + + + + 1566980773.87 + UTC + + + + + + + + + + + + + + + + + + + + + action + + + + + + actor + zope + + + comment + + + + error_message + + + + external_processing_state + empty + + + serial + 0.0.0.0 + + + time + + + + + + + + + + + 1566813446.81 + UTC + + + + + + + + + + + diff --git a/erp5_notebook_tutorial/bt/copyright_list b/erp5_notebook_tutorial/bt/copyright_list new file mode 100644 index 0000000..c787443 --- /dev/null +++ b/erp5_notebook_tutorial/bt/copyright_list @@ -0,0 +1 @@ +Copyright 2019, Nexedi SA \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/description b/erp5_notebook_tutorial/bt/description new file mode 100644 index 0000000..55db965 --- /dev/null +++ b/erp5_notebook_tutorial/bt/description @@ -0,0 +1 @@ +This bt5 contains ERP5 Notebook user documentation \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/license b/erp5_notebook_tutorial/bt/license new file mode 100644 index 0000000..61e66d6 --- /dev/null +++ b/erp5_notebook_tutorial/bt/license @@ -0,0 +1 @@ +Creative Common Attribution NonCommercial ShareAlike \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/template_format_version b/erp5_notebook_tutorial/bt/template_format_version new file mode 100644 index 0000000..56a6051 --- /dev/null +++ b/erp5_notebook_tutorial/bt/template_format_version @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/template_keep_last_workflow_history_only_path_list b/erp5_notebook_tutorial/bt/template_keep_last_workflow_history_only_path_list new file mode 100644 index 0000000..fbda00e --- /dev/null +++ b/erp5_notebook_tutorial/bt/template_keep_last_workflow_history_only_path_list @@ -0,0 +1 @@ +web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/template_path_list b/erp5_notebook_tutorial/bt/template_path_list new file mode 100644 index 0000000..fbda00e --- /dev/null +++ b/erp5_notebook_tutorial/bt/template_path_list @@ -0,0 +1 @@ +web_page_module/erp5-Notebook.Tutorial.1.Hello.World.001.en \ No newline at end of file diff --git a/erp5_notebook_tutorial/bt/title b/erp5_notebook_tutorial/bt/title new file mode 100644 index 0000000..9931fec --- /dev/null +++ b/erp5_notebook_tutorial/bt/title @@ -0,0 +1 @@ +erp5_notebook_tutorial \ No newline at end of file -- 2.30.9