Structure of a module repository#

In this tutorial we will explain how the files are structured in the module and how to use each module to build an app

If you just created you module you should have the following tree :

├── [app_name]
|     |
|     ├── component
|     |     ├── model
|     |     |     ├── __init__.py
|     |     |     └── default_process_model.py
|     |     |
|     |     ├── message
|     |     |     ├── __init__.py
|     |     |     ├── en
|     |     |     |    └── locale.json
|     |     |     ├── es
|     |     |     |    └── locale.json
|     |     |     ├── fr
|     |     |     |    └── locale.json
|     |     |     └── test_translation.ipynb
|     |     |
|     |     ├── parameter
|     |     |     ├── __init__.py
|     |     |     └── default_directory.py
|     |     |
|     |     ├── scripts
|     |     |     ├── __init__.py
|     |     |     └── default_process.py
|     |     |
|     |     ├── tile
|     |     |     ├── __init__.py
|     |     |     ├── default_process_tile.py
|     |     |     └── default_result_tile.py
|     |     |
|     |     └── widget
|     |           └── __init__.py
|     |
|     ├── doc
|     |
|     ├── utils
|     |     └── ABOUT.md
|     |
|     ├── .gitignore
|     ├── LICENCE
|     ├── README.md
|     |
|     ├── about_ui.ipynb
|     ├── aoi_ui.ipynb
|     ├── default_process.ipynb
|     |
|     ├── no_ui.ipynb
|     └── ui.ipynb

Project parameter files#

License#

By default we use a MIT license as in all Sepal development. You’ll need to customize this file to replace:

the year
your name/company name

If your project require a specific license file you can edit this one to reflect what you need. I strongly suggest to edit this file directly in GitHub as the website provide a number of templates

If you use a custom license, you’ll nee to change the badge in the README.md. copy paste any badge from this github repository instead of the classic MIT one :

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`.gitignore`#

We use the default Python Github .gitignore. It will prevent any cache file to be pushed in the GitHub repository. If your module requires API keys, it is strongly suggested to add the api_key.txt file inside the .gitignore to avoid security breaches.

README.md#

This file will e displayed in your GitHub front page. It’s useful to provide insight to people about what your module is doing. it uses the markdown format. you can use the offical cheatsheet to help you refactor your README.

Utils#

You can add anything useful for your project in this folder (API code, workbench tools). at the moment it only host the ABOUT.md file.

Partial ui#

about_ui.ipynb
aoi_ui.ipynb
default_process.ipynb

these files are partial UI file. They will be used to create each step of our app. more information in How to sepalize a process.

Final ui#

no_ui.ipynb
ui.ipynb

These files are gathering all the partial ui to create a fully functional app. The ui.ipynb file is designed to be display using voila when the no_ui.ipynb can be launched as a simple Python Notebook. More information in How to sepalize a process and Map visualization.

Component#

In this folder live all your app logic. Everything is well split for the sake of maintenance. Python developer have already recognize the __init__.py file in each of it’s folder which means that every component is a package and can be used as such in any Python file.

Model#

In this package every Model object that will be used in the project are gathered learn more in What are the Model object and how to use them ?.

Message#

In this package all the messages that will be displayed in the app are gathered in json dictionaries. More information in Translate my application.

Parameter#

For the sake of maintenance, hard-coded parameter shouldn’t be used in the scripts or in the tiles. Instead they should be gathered in the parameter package. More information in How to sepalize a process.

Scripts#

This is where your app logic lives. More information in this tutorial.

Tile#

This is where all the tiles that will be displayed in the app are created. More information in How to sepalize a process and Map visualization.

Note

In the sepal_ui framework, app are designed using the tile-based UX. A user interface that places icons in rows and columns with no space in between, exemplified by Windows Phone and Windows 8 Metro. we will refers to these unit as “tile” for the rest of the documentation.