HIP user documentation

User documentation for the Human Intracerebral EEG Platform, written with Sphinx. The dedicated website hip-infrastructure.github.io is automatically built and deployed when a pull-request is merged into the master branch (this takes a few minutes).

Development

Headings Convention

Please repect the following heading convention when making changes

===============
Level 1 Heading
===============

Level 2 Heading
---------------

Level 3 Heading
:::::::::::::::

Level 4 Heading
...............

Setting up your environment

Using dev container (VS Code)

1. Read Getting started with dev containers.
2. Open the command palette (Ctrl+Shift+P on Windows, Command+Shift+P on MacOS)
3. Click on "Dev Containers: Open Folder in Container"
4. Select the current folder
5. Start typing "Ubuntu"
6. Select "Ubuntu" container
7. Accept the default release
8. Select "Create Dev Container"
9. Wait, this can take a while the first time you create a container
10. Make sure that you are now in the dev container by looking at the bottom left of the VS Code window

The old school way

You need Python3, GIT and Sphinx installed on the computer you plan to use. Preferably, a computer running Ubuntu 20.04+ as it will make things easier.

sudo apt-get update
sudo apt-get install -y python3
sudo apt-get install -y python3-pip
sudo apt-get install -y python3-sphinx
pip3 install -r ./requirements.txt
sudo apt-get install -y git

Editing the source files

The docs directory can contain two important folders

• The source folder contains the source files used to build the html pages. You want to edit those files. Source files have an .rst extension.
• The build folder contains the html pages used for the website. Those files are generated by the command described below. Do not edit those files directly.

Sphinx uses reStructuredText (reST) markup language and you may take a look at the documentation to learn how to edit .rst files. You can also take the existing .rst files as examples. You can use any text editor to edit those files, but do not change the extension.

Validating your changes locally

Once you have edited or created new .rst files, you need to build the project using the following command:

make html

You can then check the result by opening the HIP-infrastructure.github.io/docs/build/html/index.html file in any web browser.

open index.html

You will be able to navigate a local version of the website. If you are making several builds, don't forget to refresh the webpage you are viewing so the changes are taken into account. If this does not work, you may try to re-build the html pages from scratch using the commands:

make clean
make html

Publishing the documentation

Simply push your changes to the remote repository. Your new source files will be automatically built and deployed once merge into the master branch.

Acknowledgement

This research was supported by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).

This platform received funding from the Swiss State Secretariat for Education, Research and Innovation (SERI) as part of the Horizon Europe project “EBRAINS 2.0”, contract number 23.00638.