User documentation for the Human Intracerebral EEG Platform, written with Sphinx.
The dedicated website hip-infrastructure.github.io is automatically deployed when a commit is pushed to the master
branch (this takes a few minutes).
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.
In a Terminal
:
sudo apt-get install -y python3
sudo apt-get install -y git
sudo apt-get install -y python3-sphinx
First you need to clone the repository, so you have a local version of the documentation on your computer:
git clone [email protected]:HIP-infrastructure/HIP-infrastructure.github.io.git
Then you need to move inside the docs
directory:
cd HIP-infrastructure.github.io/docs
In the docs
directory, you will find a source
folder and a build
folder:
- The
build
folder contains the html pages used for the website. You do not want to edit those files. - 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.
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.
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.
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
In order to publish your edits, you need to push your local version of the documentation to the remote repository:
cd ..
git add .
git commit -m "My edits."
git push
Replace My edits.
with a message giving insights on the modifications you have made to the documentation.
Wait a couple of minutes before checking the new version of the documentation at hip-infrastructure.github.io