add doc

README.md

@@ -1,3 +1,56 @@
 # sepal_ui
 
-wrapper for ipyvuetify widgets to unify the display of voila dashboards in the sepal plateform
+wrapper for ipyvuetify widgets to unify the display of voila dashboards in the sepal plateform.
+
+![full_app](./doc/img/full_app.png)
+
+
+## Installation 
+
+the framework is available on Pypi:
+```
+$ pip install sepal_ui
+```
+
+The usage of this framework require that the earthengine api and it's authentification. Run:
+```
+$ earthengine authenticate
+```
+and follow the instructions
+
+## Usage 
+
+Click on the links to discover the different usage of the framework :
+- Create an aoi selector [doc](./doc/aoi.md)
+- Create an about section [doc](.doc.about.md)
+- Link you process to a tile [doc](./doc/process.md)
+- Create app framework with a title, a footer and a drawer menu [doc](./doc/app.md)
+
+
+An example of app using this framwork can be found [here](https://github.com/12rambau/sepal_ui_template).
+
+## suggested structure 
+
+To use this framework it is highly recommanded to follow the following folder scructure:
+```bash
+├── app
+│   ├── doc
+│   │   ├── img
+│   │   │   └── *.png 
+│   │   │
+│   │   └── *.md
+│   │   
+│   ├── scripts
+│   │   └── you app process (*.py, *.cpp, *.r)
+│   │
+│   ├── [tile_name]_UI.ipynb
+│   ├── UI.ipynb
+│   │
+│   └── ReadME.md
+```
+
+The `UI.ipynb` will be the entry point of you're app and it will call all the differents tiles created in the `[tile_name].ipynb` files.
+
+
+For more specific and customized app. you can directly create your own component using the [ipyvuetify lib](https://github.com/mariobuikhuizen/ipyvuetify).
+

doc/about.md

@@ -0,0 +1,23 @@
+# Create an about section 
+
+For you're application you'll may need a disclaimer or an about section to explain you're module to the end-user. 
+It is long and unrelevant to write this section in plain html and import it to a Voila dashboard
+
+using this framework you'll be able to create an about Tile by only writing an about file in the very simple [markdown format](https://www.markdownguide.org/cheat-sheet/).
+
+## Code 
+
+```py
+from sepal_ui import widgetFactory as wf
+
+#create the Html body of your about section 
+pathname = 'utils/about.md' #path to your markdown file
+fao_about = wf.TileAbout(pathname)
+
+#will only be displayed if voila is launch from this tile
+fao_about
+```
+
+The TileAbout function will take a .md file as an input, transform it into HTML plaint code and return a `ipyvuetify` Layout that can be displayed as a tile in a Voila notebook or in a `sepal_ui` app.
+
+![about](./img/about.png)

doc/aoi.md

@@ -0,0 +1,112 @@
+# Create aoi selector
+
+The framework provides a stand alone aoi selector tile. It will create a aoi in you gee asset that will then be available for any process. 
+
+## Code 
+
+```py
+from sepal_ui import widgetFactory as wf
+
+#create the asset variable object 
+aoi_IO = wf.Aoi_IO()
+
+#create the tile 
+fao_aoi = wf.TileAoi(aoi_IO)
+
+#this tile will only be displayed if voila is launch from this notebook 
+fao_aoi
+
+```
+
+In order to make the variable available for all the notebooks, they need to be nested in a IO class. The aoi_IO class provide all the necessary inputs for the aoi_tile to run and provide an output with assetID member. 
+
+FYI 
+
+```py
+#create the aoi selectors IO
+class Aoi_IO:
+    def __init__(self):
+        #set up aoi inputs
+        self.file_input = None
+        self.file_name = 'Manual_{0}'.format(datetime.now().strftime("%Y-%m-%d_%H-%M-%S"))
+        self.country_selection = None
+        self.selection_method = None
+        self.drawn_feat = None
+
+        #set up aoi output
+        self.assetId = None
+```
+
+The TileAoi function return an `ipyvuetify` Layout that can be displayed as a tile in a Voila notebook or in a `sepal_ui` app.
+
+## Usage 
+
+On this initial tile, select the method you want to use to select your AOI. you can choose between four methods that are going to be explain in the followings.
+
+## 1.1 Country boundaries
+Once you reach the `country boundaries` value in the dropdown and select it, a new dropdown appears. 
+There you can select a country name in the list provided. They correspond to every available country in the LSIB-2017 list. 
+
+After validating your country, the map will zoom on the country you've validated and will create an aoi_[country_code] asset on your GEE account. It will be available for other projects.
+
+> :warning: The output can select the wrong country, before validating your selection please verify in the blue alert that the `selected country` is the one you want to use. If wrong try to select it again.
+
+![country boundaries](./img/country_boundaries.png) 
+
+## 1.2 Draw a shape
+
+Once you have selected `draw a shape` in the dropdown, two new input will appear: 
+ - Select a filename
+ - The drawing tool on the map
+
+ The filename will be the name of your AOI in your GEE drive and for the rest of the process. An auto-generated value is already set up by default. If you want to change it you can write anything in alphanumeric characters
+
+ The drawing tool on the map allows you to draw shapes (rectangles, polygons and circle) 
+
+ > :warning: Multiple geometries could lead to various bug or crash. If needed please consider running your analysis in two steps
+ 
+After validating your shape, the map will zoom on the AOI you've validated and will create an aoi_[filename] asset on your GEE account. It will be available for other projects.
+
+![draw a shape](./img/draw_shape.png)
+
+## 1.3 Import shapefile
+Importing your own shapefile in this module will be perform in two steps. 
+First you need to import the shape to your sepal folder and then use it. 
+
+In a new application tab (1), select 'jupyter notebook' (2).
+![applications](./img/applications.png)
+
+You should obtain a description of your local folder in Sepal (3). click on `upload` (4) and select the required files.
+
+![jupyter](./img/jupyter.png)
+
+
+> :warning: in order to perform the construction of your AOI, the module will require you to upload .shp, .dbf and .shx with the same name in the same folder
+
+> :question: It is strongly advised to put all your shapefile in a new folder such as `[process]_input`
+
+Second step you can go back to your app module and select 'upload file' in the first dropdown menu.  
+The dropdown will automatically include the available .shp files in your sepal folders. You'll may need to restart the app to update the list.
+![folder_struct](./img/filepath.png)
+![shapefile_import](./img/shapefile.png)
+
+After validating your shape, the map will zoom on the AOI you've have validated and will create an aoi_[filename] asset on your GEE account. It will be available for other projects.
+
+## 1.4 import GEE asset
+
+Once you have selected `use GEE asset` in the dropdown, just enter the name (2) of your asset as it appears on your GEE account (1) 
+
+![custom asset](./img/custom_asset.png)
+
+
+After validating your AOI the map will zoom on the AOI you have validated
+
+---
+[ go to  → readme.md](../README.md)  
+
+
+
+
+
+
+

doc/app.md

@@ -0,0 +1,56 @@
+# Create an app framwork
+
+Using this framework, you'll be able to build an app framework using Ipyvuetify components pre-selected for the sepal environment. 
+
+# code 
+
+```py
+from sepal_ui import widgetFactory as wf
+from sepal_ui import widgetBinding as wb
+
+#create an appBar 
+fao_appBar, fao_toggleButton = wf.AppBar('My fake module')
+
+#create a footer 
+fao_footer = wf.Footer('The sky is the limit \u00A9 2020')
+
+#add your tiles
+%run 'aoi_UI.ipynb'
+%run 'process_UI.ipynb'
+%run 'about_UI.ipynb'
+
+fao_content = [fao_aoi, fao_process, fao_results, fao_about] #use the name created in the other .ipynb files
+
+#select the tile to display first 
+select = 'process_widget' #id of the tile you want to display
+wf.hideCards(select, fao_content)
+
+#create a drawer 
+item_aoi = wf.DrawerItem('AOI selection', 'mdi-map-marker-check', card="aoi_widget")
+item_tile = wf.DrawerItem('Process', 'mdi-cogs', card="process_widget")
+item_result = wf.DrawerItem('Results', 'mdi-chart-bar', card="result_widget")
+item_about = wf.DrawerItem('About', 'mdi-help-circle', card="about_widget")
+
+code_link = 'https://github.com/12rambau/sepal_ui_template'
+wiki_link = 'https://github.com/12rambau/sepal_ui_template/blob/master/doc/fake_doc.md'
+issue = 'https://github.com/12rambau/sepal_ui_template/issues/new'
+
+items = [item_aoi, item_tile, item_result, item_about]
+fao_drawer = wf.NavDrawer(items, code = code_link, wiki = wiki_link, issue = issue)
+
+#build the app 
+fao_app = wf.App(
+    tiles=fao_content, 
+    appBar=fao_appBar, 
+    footer=fao_footer, 
+    navDrawer=fao_drawer
+)[0]
+
+#bind the components together
+wb.displayDrawer(fao_drawer, fao_toggleButton) #drawer 
+for item in items:                             #drawer clickable buttons
+    wb.display_tile(item, fao_content)
+
+#display the app
+fao_app
+```

doc/components.md

@@ -0,0 +1,105 @@
+# Components
+
+## Sepal_ui
+
+### Widgets
+
+```py
+from sepal_ui import widgetFactory as wf
+
+wf.AppBar(title='SEPAL module')
+
+wf.DrawerItem(title, icon=None, card='', href='')
+
+wf.NavDrawer(items, code = False, wiki = False, issue = None)
+
+wf.Footer (text='SEPAL \u00A9 2020')
+
+wf.App (tiles=[''], appBar=None, footer=None, navDrawer=None)
+
+wf.Tile(id_, title, inputs=[''], btn=None, output=None)
+
+wf.TileAbout(pathname)
+
+wf.DownloadBtn(text, url="#")
+
+wf.ProcessBtn(text="Launch process")
+
+wf.TileAOI(io)
+
+wf.Aoi_IO()
+
+wf.OutputWidget(text='Click it')
+
+```
+
+### functions 
+```py
+from sepal_ui import widgetFactory as wf
+from sepal_ui import widgetBinding as wb
+from sepal_ui.scripts import utils
+
+wf.hideCards(tileId, tiles)
+
+wb.displayDrawer(drawer, toggleButton)
+
+wb.display_tile(item, tiles)
+
+wb.bind(widget, obj, variable, output=None, output_message='The selected variable is: ')
+
+wb.toggle_inputs(input_list, widget_list)
+
+utils.displayIO(widget_alert, message, alert_type='info')
+
+utils.toggleLoading(btn)
+```
+
+Run `help(__func__)`to get more information on each function 
+
+## Ipyvuetify
+
+```py 
+import ipyvuetify as v
+
+v.Alert(
+    children=['message'], 
+    type='info', text=True, 
+    class_="mt-5"
+)
+
+v.TextField(
+    label='label', 
+    v_model=None,
+    class_='d-inline'
+)
+
+v.Select(
+    items=[elts], 
+    label='label', 
+    v_model=None,
+    class_='d-inline'
+)
+
+v.Slider(
+    label= 'slider', 
+    class_="mt-5 d-inline", 
+    thumb_label='always', 
+    v_model=0
+)
+
+v.Btn(
+    class_='ma-2',
+    xs5=True,
+    color='success',
+    href=url,
+    children=[
+        v.Icon(left=True, children=['mdi-download']),
+        text
+    ]
+)
+```
+
+they all can be bind with the `wb.bind` function or with `widget.on_event('change', callback)`.
+
+
+