Tips and Tutorials \ PLUTO Contribute - Adding a new tutorial to the portal

This tutorial will show you all the simple steps to add a new tutorial to the portal.

Tools:

Difficulty: Easy
Type: How-To

Prerequisites

basic knowledge of git and Gitlab
having a CNES Gitlab account (if you don't, contact us at l-pluto-support@cnes.fr)

You may have some tips to share with the community, either for configuring a tool in your environment, or in using several tools in a same processing chain. All of these information may help other developers or users. Give us your tips & tricks, or contribute to tutorials on specific tools by following these simple steps:

Get the source code of the PLUTO portal and create your own working branch
Create a new markdown file describing your tutorial
Test the code on your local browser
Push your code and create a Merge Request to publish it on the official website

1) Get the code

First clone PLUTO repository on your machine. To do so, create a folder anywhere and in a terminal type :

git clone git@gitlab.cnes.fr:pluto/portal.git

Notes :

it is important to use the ssh command (not https)
from outside CNES network, add your username in the clone command line : git clone gu=<username>@git@gitlab-ssh.cnes.fr:pluto/portal.git
in this beta version, you need to be a member of the pluto group. Contact l-pluto-support@cnes.fr if you are not in the group.
you can find more details here if you have difficulties getting the source code.

Create a new branch from the cloned folder :

cd portal
git checkout -b my_tool_branch

2) Create a new markdown file

Look for a directory in the docs/data section in which you tutorial would be relevant : it can be in the main tool used in your tutorial. If you are not sure, you can use the miscellaneous folder.

In that repository, create a markdown file with the name of your tutorial in lowercase without spaces. For example, if you tutorial is related to Dask :

docs
|-- data
    |--dask
        |-- mytutorial.md

3) Fill the markdown file with metadata

The easiest way for you to add a tutorial is to get the template mardown and fill it.

Here is an example for DASK :

---
title: Dask Cookbook by Project Pythia
section: tutorials
description: Presents the basics of DASK.
contacts:
 - Emmanuelle SARRAZIN <emmanuelle.sarrazin@cnes.fr>
 - Yannick TANGUY <yannick.tanguy@cnes.fr>
 - David YOUSSEFI <david.youssefi@cnes.fr>
type: gallery
location: https://projectpythia.org/dask-cookbook/README.html
difficulty: easy
tools:
 - dask
related_tutorials:
 - other_dask_tutorial
tile_image: 'dask_logo.svg'
tile_image_opaque: false
categories:
  - Code Optimization and Distribution
tags:
  - Optimization
vre:
  name: dask_cookbook
  choice: OT
  git: https://github.com/ProjectPythia/dask-cookbook
template: overrides/pluto/tutorial.html
---

The metadata must be written inside --- tags. Here is a description of all values. Some are compulsory, some are optional, fill free to adapt to your own case. The order in which metadata are written is not important.

Warning

Common markdown syntax (for example, adding a link in the description) will not work in the metadata section. Please respect below format.

Metadata	Description	selectable values	Status
description	A short description of the Tutorial		mandatory
difficulty	The difficulty of the tutorial.	easy, Easy, intermediate, Intermediate, advanced, Advanced	mandatory
template	This line should always be overrides/pluto/tutorial.html		mandatory
title	The name of the tutorial		mandatory
type	The type of the tutorial. Note that tips should have ../../assets/images/tips.png as a tile_image	Notebook, How-To, how-to, Tip, tip, Gallery, gallery	mandatory
tile_image	The relative path to an image to display on the tutorial tile and page. The image should be stored in the tutorial directory, alongside the markdown file. It can be png, jpeg, or svg		recommended/optional
categories	The list of categories for this tool. Listed items start with a -	Python Stack, Data Access, Preprocessing, Features Extraction, Processing Chains (pipelines), Visualization Tools, Code Optimization and Distribution	optional
contacts	A list of contacts in the format `NAME NAME <emailaddres>`, or a links in the format `https://link/to/the/contact/page`. Listed items start with a -		optional
external	If true, this tutorial page is available on the external website		optional
license	If the tutorial has a license you can display it by filling this metadata. License should have one of the following values : Apache-2.0, BSD-4-Clause, BSD-3-Clause, BSD-2-Clause, 0BSD, GPL-3.0, GPL-2.0,MIT, No License, Proprietary		optional
location	A link to the tutorial if it is an external resource		optional
producer	The producer of the tutorial		optional
related_tutorials	A list of other tutorials (give filename without extension) present in PLUTO. Listed items start with a -		optional
section	This should always have the value 'tutorials'		optional
tags	A list of free tags. List tags begin with a -. These tags will be used as keywords by the portal search feature, allowing to retreive your tutorial easily		optional
tile_image_opaque	Set to true to have the tile image displayed with a white background to make it more visible over the banner (False by default).		optional
tools	The list of tools used in the tutorial. If the tool exist on PLUTO, the tool name must match the tool repository name in /docs/data/. Listed items start with a -.		optional
vre	The information required to run the tutorial in the VRE		optional
vre.choice	The VRE to use for this tutorial	OT, natif	mandatory
vre.git	The URL of the git repository containing the tutorial		mandatory
vre.name	A unique name given to the directory on TREX where the tutorial will be copied		mandatory
vre.kernel	Name of the kernel used to run the tutorial		optional

Optionnaly, you can add free content in the markdown format after the metadata section. We recommend that you follow the pattern :

---
(Metadata Section)
---

## Motivation
A description of the goals of the tutorial.

## Prerequisites
Any knowledge it is better to have before doing the tutorial.

Click here for some markdown tips

If you are new to Markdown, here are some documentation and a free online editor.

The markdown syntax to add an image is:
```
![image](./path/to/the/image/file.png)
```
If you want to specify the width of the image (resp. height) and want to align your image to the left, you can use this syntax:
```
![image](./assets_myfirstpost.png){: style="width:300px;margin-left:0"}
```
Adding a link in the text is also simple:
```
[link](https://link)
```

Note

Information stored in the metadata will appear on the tutorial page. For a good visual result, try not to repeat the metadata information in the free section.
If you mention other tools from PLUTO you can create a link with the markdown pattern [link_text](/project/relative/path/to/tool/md/file), for example here is a link to the OTB tool, from a tutorial page: [OTB](../otb/otb.md)

4) Test it

Install mkdocs : on a terminal, run pip install mkdocs-material mkdocs-rss-plugin mkdocs-include-markdown-plugin pydantic pandas tabulate ruamel.yaml. We advise to create a new virtual environment.

At the root of the project (portal folder), use the command mkdocs serve -w . --no-directory-urls to display the result on your local browser.

You can check if your tutorial appears in the Tips&Tutorial section and if all information are correctly displayed when you open the page. If not, you may have a mistake in the format of one of the metadata.

Commit and push your code, then create a Merge Request on Gitlab. An automatic CI pipeline will run as a first check. If you have errors, please check the log by clicking on the pipeline on the Merge Request page. You can update the Merge Request with new commits.

Note that you can download the CI build artifact on Gitlab to get your local version of the site in a zipped folder.

Your code will now be reviewed before merging to the official website. If any modification is needed, an admin will contact you to explain the needed steps.

Any trouble ? Ask the community or contact us on the forum.

Contacts

Questions ? Get help on the Forum