Tips and Tutorials \ PLUTO Contribute - Adding a new tool to the Catalog

This tutorial will show you all the simple steps to add a new tool 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)

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

Get the source code of the PLUTO portal and create your own working branch
Create a new repository and markdown file describing your tool
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 repository and markdown file

Create a repository in the docs/data directory, with the name of your tools in lowercase without spaces. In that repository, create a markdown file with the exact same name.

docs
|-- data
    |--mytool
        |-- mytool.md

3) Fill the markdown file with metadata

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

Here is an example for the OTB :

---
title: Orfeo ToolBox
alias: otb
section: catalog
description: An open-source project for state-of-the-art remote sensing
producer: OTB core developers
repository: https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb
contacts:
  - Yannick TANGUY <yannick.tanguy@cnes.fr>
resources:
  - 'Website': https://www.orfeo-toolbox.org/
  - 'Documentation': https://www.orfeo-toolbox.org/documentation/
related_tools:
  - diapotb
license: Apache 2
categories:
  - Preprocessing
  - Features Extraction
maturity: Maintained
tags:
  - orthorectification
tile_image: 'logo-orfeo-toolbox.png'
tile_image_opaque: false
template: overrides/pluto/tool.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
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	mandatory
description	A short description of the tool		mandatory
license	The name of the license, following SPDX standard (https://spdx.org/licenses/)	0BSD, AGPL-3.0-only, BSD-2-Clause, BSD-3-Clause, BSD-4-Clause, Apache-2.0, GPL-2.0-only, GPL-3.0-only, LGPL-3.0-only, MIT, No License, Proprietary	mandatory
maturity	The maturity of the tool. "Prototype": code published, but missing some good practices (CI, test, doc, etc). "Stable": code published with at least tests, CI and doc. "Maintained": code published with a development or maintenance team.	Prototype, Stable, Maintained	mandatory
template	This line should always be overrides/pluto/tool.html		mandatory
title	The name of the tool		mandatory
repository	The link to the source code.		recommended/optional
tile_image	The relative path to an image to display on the tool tile and tool page. The image should be stored in the tool directory, alongside the markdown file. It can be png, jpeg, or svg		recommended/optional
alias	A second name for the tool if needed (for example the Orfeo Toolbox is commonly referred as `otb`)		optional
contacts	A list of contacts in the format `NAME NAME <emailaddres>`, or a link in the format `https://link/to/the/contact/page`. Listed items start with a -		optional
external	If true, this tool page is available on the external website		optional
producer	The producer of the code, for example a company or a dev team		optional
related_tools	A list of related tools. Listed items start with a -		optional
resources	A list of useful links. List items begin with a - and have the format `'name': https://link/to/the/ressource`		optional
section	This should always have the value 'catalog'		optional
tags	A list of free tags. Listed items start with a -. These tags will be used as keywords by the portal search feature, allowing to retreive your tool 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

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

---
(Metadata section)
---

## Overview
A description with more details than in the "description" metadata.

## Usage/Documentation
Some info about how to use the tool

## Installation
A short description about the install process, for example "You can easily install myTool with Pypi."

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 tool 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 another tool 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 tool appears in the Catalog and if all information are correctly displayed when you open the tool 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