Attention

The SEPAL team documentation section was developed for SEPAL team members only. While contributors and collaborators are encouraged to review these articles, they are not mandatory for general SEPAL users.

Contribute#

Learn how to make contributions to SEPAL documentation

The SEPAL team values user feedback and contributions to SEPAL documentation.

Before contributing, please review the SEPAL Code of conduct.

Then, communicate feedback or proposed contributions via:

Introduction#

The sepal-doc repository has a fixed structure that needs to be respected to follow Sphinx builder requirements.

All modifications should be made in the folder, sepal-doc/docs/source/.

Images associated with a page should be stored in the corresponding folder, sepal-doc/docs/source/_images/.

If files are misplaced, their build into .html pages cannot be guaranteed.

Please carefully review the following instructions before contributing to SEPAL documentation.

Tools#

The sepal-doc repository creates and organizes .rst files by leveraging:

Important

To contribute to SEPAL documentation, you will need:

  • basic knowledge of any lightweight markup language (e.g. markdown, latex), which will help you understand .rst files;

  • the Sphinx directives documentation;

  • a GitHub account; and

  • a basic understanding of terminal commands.

Guidelines#

There are only two guidelines to follow that are not directly specified in the .rst documentation or template:

  • Indentation: Insert 4 spaces for bullet points and directives (options and content); and

  • Headings: Use the appropriate symbols for section heading formatting, as seen below.

Heading 1
=========

Heading 2
---------

Heading 3
^^^^^^^^^

Heading 4
"""""""""

Heading 5
#########

Heading 6
+++++++++

Custom#

The following custom directives were added to help build the documentation.

Videos#

There are two ReST directives for embedding videos from YouTube (youtube) and Vimeo (vimeo).

The video ID must be included.

While the default height is 281, the default width is 500, and the default alignment is left, both directives can be customized by specifying the following:

  • height

  • width

  • align

Here is an example:

.. youtube:: Ub6N8aWThw4
    :height: 315
    :width: 560

Line breaks#

The ReST directive for creating a line break does not require any argument.

Here is an example:

.. line-break::

Graphviz#

There is also a directive to embed Graphviz code. The input code for dot is given as the content.

To better understand Graphviz, see Graphviz documentation.

Here is an example:

.. graphviz::

    digraph foo {
    "bar" -> "baz";
    }
digraph foo {
"bar" -> "baz";
}

Icons#

There is a ReST role to include in-line icons.

Use icons from the Font Awesome library.

Folder icon: :icon:`fa-solid fa-folder`

Folder icon:

Buttons#

There is a ReST role to include a button (with or without text).

Use buttons from the Font Awesome library.

Apply button: :btn:`<fa-solid fa-check> Apply`

App button: :btn:`<fa-solid fa-wrench>`

Apply button: Apply

App button:

Minor change#

Page edit#

If you would like to make modifications to an existing article in the documentation because you’ve seen a typo or would like to improve an explanation, select the Edit on GitHub button in the pane on the right side of your browser window (if the button isn’t visible, use your browser’s Zoom out function or open the pane using the triple bar button [☰] in the upper-right corner).

Edit page button

When you are finished modifying the file in the GitHub editor, select propose change at the bottom of the page.

This will create a Pull request (PR) that includes your modifications, which will be reviewed and evaluated by the SEPAL team before being published.

Edit a page directly on GitHub

Tip

To ensure that your modifications are clear, change the title of the Commit by completing the first field (i.e. inserting an explanation such as Typo, Change image, Code-block error – anything that concisely describes your modifications).

Create a branch

When correcting anything, create a Branch.

Once you’ve finished, a PR will be created in the Open Foris repository. Remove all comments, as you’re not making a real PR, but an adjustment (normally the title will automatically be set with the name of your Commit).

Select Create pull request.

PR for a typo

Note

Once your PR is accepted, you will be notified. Please consider deleting your Branch.

Delete branch

Module edit#

The Edit on GitHub button will not work for articles in the Modules section, as the files are retrieved from each module’s repository.

Their should be a link at the very bottom of the page to make modifications to the source file in the module repository following the same procedure mentioned above.

Once you’ve finished, notify the SEPAL team, who will need to manually rebuild the documentation to retrieve the latest version of the file you modified.

Note

If you want to add a new module to the documentation, see the following section.

Major changes#

Major changes include:

  • creating new documentation pages (i.e. articles);

  • modifying multiple images;

  • making new sections;

  • building new modules; and

  • adding new classes on Google Classroom.

For these major changes, the simple GitHub edit process does not work. Rather, you need to follow another workflow that allows you to modify multiple files at the same time and use the PR system to avoid publishing new pages without validation.

In this subsection, we will present the full process to make major changes.

Fork project#

To work on multiple files at the same time, you cannot work directly from GitHub. Rather, you need to install a local version of the source.

To avoid the publication of low-quality documentation, SEPAL users don’t have the rights to directly push edits to master files. Instead, you must fork the project into your own account by selecting the fork button in the upper-right corner of the GitHub page of the documentation:

GitHub fork button

In the Fork pop-up window, select the account you want to use:

Fork pop-up window

In the upper-left side of the following page, you can see your location. This repository is stored in your account, but it’s a fork of the original openforis/sepal-doc file.

Note

To learn more about the forking system in GitHub, see this article.

Landing page of the forked project

We are now ready for local installation.

Local installation#

Install the forked project locally to make your modifications.

On your computer, go to a terminal and run the following command.

Important

Don’t forget to change your account to the account name where you forked the project.

git clone https://github.com/<your account>/sepal-doc.git

Once the code is installed on your computer, install the packages that are required to build the documentation by running the following command:

pip install -U -r sepal-doc/requirements.txt

To check that the documentation can be built without error, go to the doc folder and run the following command:

cd sepal-doc/docs
make html

Note

The SEPAL team has attempted to minimize the chances of experiencing warnings in the master branch. If warnings are displayed, ignore them; the SEPAL team will address them as soon as possible.

A new folder, build, has been created in your sepal-doc folder.

Double-click on sepal-doc/docs/build/html/index.html.

Your browser should open and load the landing page of SEPAL documentation. (Note: It will be a local .html page. The URL at the top of the browser should start with file:// rather than https:// and there should be no advertisements in the side bar.)

Local build landing page

We can now start to code our modifications.

Tip

This procedure can also be performed in the SEPAL platform by starting a t1 instance and executing the same process.

To open the .html page, use JupyterLab, since it is able to load .html content (JupyterLab is also an excellent integrated development environment [IDE] to make modifications, since it recognizes .rst format).

Modify the doc#

Each type of modification will be treated separately, since they don’t imply the same code structure. While doing local modifications, don’t hesitate to run the following command in the sepal-doc/doc/ folder to check the page that you’re modifying, as it will help you see typos and mistakes with directives:

make html

If you would like to make many modifications, you should create multiple commits (from the sepal-doc/docs/ folder).

When making modifications, always include clear, concise commit messages (if you cannot find the appropriate commit message, you have done too many things and should consider creating multiple commits instead).

git add ../
git commit -m "<your message>"

Once you are done with your modifications, push the repository to GitHub and continue to the next section:

Get push

New page#

Open the sepal-doc folder in your preferred IDE.

Note

Any TextEdit software will work as well, though won’t be as user-friendly.

As previously explained, the folder has a specific structure corresponding to the Sphinx template, which we are using to build the final documentation.

The first step will be to identify the section where you would like to store your page.

The following sections are currently available:

  • Getting started – Everything you need to know to use SEPAL; located in the sepal-doc/docs/source/setup/ folder.

  • Cookbook – How to use different recipes available in SEPAL; located in the sepal-doc/docs/source/cookbook/ folder.

  • Modules – The modules available in the App dashboard; located in the sepal-doc/docs/source/modules/ folder.

  • CLI – All command-line interface (CLI) tools installed by default in SEPAL; located in the sepal-doc/docs/source/cli/ folder.

  • Workflows – Different combinations of SEPAL tools and recipes to perform complex data analyses; located in the sepal-doc/docs/source/workflows/ folder.

  • Features – Features that are available across various recipes and modules to analyse, combine and visualize different types of data; located in the sepal-doc/docs/source/feature/ folder.

  • Team – A hidden section only available to team members that helps them contribute to the platform; located in the sepal-doc/docs/source/team/ folder.

Note

In the Module section, only the index.rst file should be modified, as the others are downloaded from their repository (see the section New module below).

Attention

If you create a team page, the first line of your .rst file should always be:

.. include:: disclaimer.rst

Now that you have selected a section, you can create a new documentation page (<my_page>.rst) using all .rst directives available in Sphinx, as well as the directives presented in the first section of this article.

To maintain consistency across folders and help with image maintenance, the images you use should be stored in the following folder: sepal-doc/docs/source/_images/<section>/<page>/.

Add the page you’ve created to the toctree (Table of contents) directive in the <section>/index.rst file by adding your filename – without the extension – respecting the following indentation:

.. toctree::
    :maxdepth: 1
    :hidden:

    page1
    page2
    my_page
    page3

The title of your page should appear as a link in the Section navigation pane on the left side of your browser.

If you forget to link your page, you will see the following message:

<source_dir>/sepal-doc/docs/source/<section>/<my_page>.rst: WARNING:
The document is not included in any table of contents in the tree structure.

Tip

If you are struggling with .rst, get support by asking the Google Group community.

Modify images#

Images for each page are saved in the mirror folder, sepal-doc/docs/source/_images/, which reproduces the structure of sepal-doc/docs/source.

Open the page you want to modify and search for the .. image or .. figure directive for the image you want to modify. You just need to change the image in the _images/ folder and continue using the same name.

If you think an image is missing, you can add one to any page by placing the image in the appropriate folder, and then naming it using one of the following directives (making sure to include the alt text, which will be the only information displayed if your image fails to load).

  • The figure directive adds padding to the bottom of the image and allows you to add a caption.

    .. figure:: ../_images/<section>/<page>/<image>.png
        :alt: <The image callback text>
    
  • The image directive is easier to manipulate, but has fewer functionalities.

    .. image:: ../_images/<section>/<page>/<image>.png
        :alt: <The image callback>
    

New section#

Attention

The documentation should not require new sections; however, if you believe that something needs to be added, let the SEPAL team know via the GitHub Issue Tracker.

To add a new section, create a new folder in sepal-doc/docs/source/. This folder should contain at least one page that contains the following code:

<Section title>
===============

.. toctree::
    :maxdepth: 1
    :hidden:

This section page should be added to the Documentation index.

Modify the toctree of sepal-doc/docs/source/index.html by replacing <section> with the folder name and Section name with the name you would like to see in the navigation bar.

.. toctree::
    :maxdepth: 1
    :hidden:

    Getting started<setup/index>
    Cookbook<cookbook/index>
    Modules<modules/index>
    CLI<cli/index>
     <team/index>
    Section name<<section>/index>

New modules#

Have you created a new Shiny or Python-based module and been asked to add it to the App dashboard of SEPAL, following the Issue template?

One of the requirements to have your module accepted by the SEPAL team is to create a documentation file.

To maintain consistency across modules, we store the documentation in the module’s original repository.

To create the actual documentation page, follow the instructions provided in the sepal_ui doc.

Then, modify the sepal-doc/docs/source/data/modules/en.json file in sepal-doc to make your documentation available by adding a new line with the following shape:

{
    "module_name": "https://raw.githubusercontent.com/<account>/<repository>/master/doc/en.rst"
}

This file will be pulled at each build of the documentation in the sepal-doc/docs/source/modules/dwn folder.

New class on Google Classroom#

Have you have created a new class under the Google Classroom repository, following the Google Classroom doc? Would you like to add this class to the appropriate class table?

Go to your Google Classroom page and select the Share link. On the next page, copy and paste the following information for the course:

  • the number

  • the title

  • the invitation link

Google Classroom sharing links

You now have one single file to modify sepal-doc/docs/data/<type>/<locale>.csv:

  • replace <type> with your class type (general for a reusable piece of documentation and project if linked to a FAO activity)

  • replace <local> with your class language (only English [en], French [fr] and Spanish [es] are available)

  • add one extra line at the bottom, as follows:

<title>, `<ID> <<link>>`_, <modification date>
  • replace <ID> with the class number;

  • replace <link> with the invitation link;

  • replace <title> with the class title; and

  • add the latest <modification date> in YYYY-MM-DD format.

Create a pull request#

Create a pull request#

Note

This article of SEPAL documentation, Contribute, was requested in the GitHub Issue Tracker (Issue #19). It was then added to SEPAL documentation (PR #24).

Now that you have finished your modifications and pushed them to GitHub, go back to the web interface of the forked repository (https://github.com/<your account>/sepal-doc).

First, select the Pull requests button to open the PR interface:

Pull requests button

Open the Pull request (PR) interface.#

In the Pull request interface, select the New pull request button:

New pull request

Select what is going to be pushed and where. (If you’ve followed this article correctly, you have not created any branch in your fork.)

On the left side, leave openforis/sepal-doc/master.

On the right side, leave <account>/sepal-doc/master (see 1 in the following image; some extra information on the commit that will be added to the master is displayed in 2).

If everything is set properly (normally you don’t have to change anything), select the Create pull request button.

Compare branches

Finally, enter the title and description of the PR (1) (please respect the template provided, as shown in the following image).

As explained at the beginning of this article, you started your modifications to address an issue reported in the GitHub Issue Tracker, which should be referenced in your PR message (in Line 2 using the #<issue number>). This will help the SEPAL team, who will review your PR, by ensuring that they understand what you are adding to the documentation.

Note

You can select the preview button to see what your PR looks like with links.

The Allow edits by maintainers checkbox needs to always be checked (default behavior) (2). This will allow the SEPAL team to make modifications to your PR files (e.g. if you made a mistake in a .rst directive).

When everything is complete, select Create pull request (3) and validate the creation of the PR.

Valid PR

An automatic check will be performed to see if your PR can be built with ReadTheDoc and distributed in https://docs.sepal.io.

Continuous integration (CI) in PR

Once submitted, the SEPAL team will review your PR and make the appropriate modifications, if needed. The PR will then be accepted and the new page will be available in the main documentation.

Tip

Once the PR has been validated, please delete your fork in order to avoid merging previous issues when making later modifications.

Delete fork
Delete pop-up window

Important

If you are the owner of openforis, do not delete openforis/sepal-doc.

Last updated on Dec 18, 2023.