# Guidelines to develop RAMSES tutorials

## Style

Python notebooks are handy for tutorials. Please make sure that your tutorial starts with a markdown cell containing the title of the tutorial after a single hash sign. For example
```
# My New Tutorial
```
Then you should use markdown cells to structure the tutorial into sections and sub-sections, starting with `##` for sections, `###` for sub-sections, etc. For example:
```
## 1. Pre-requisites
### 1.1. compiling RAMSES with the right options ...
```
This will help the table of contents look good in the overall documentation.

Please, before pushing your tutorial to the common repo, make sure it works end-to-end. When you are happy with your tutorial, the best practice is to restart the kernel and clear all cells, then run cells one by one till the end, save the notebook, and commit this version.


## Turning your tutorial into documentation with sphinx

Each tutorial is in the form of a notebook within a directory, for example `Cosmological-Volumes/tutorial.ipynb`. The global documentation consists of all the tutorials listed in the file `doc/source/index.rst`. If you create a new tutorial `MyNewTutorial/tutorial.ipynb`, you should first add a symbolic link of your tutorial's directory into the `doc/source` directory:
```bash
cd doc/source
ln -s ../../MyNewTutorial .
```
Then you should edit the file `doc/source/index.rst` to insert a line in the list of existing tutorials (mind the spaces), for example as follows:
```
   Cosmological-Volume/tutorial.ipynb
   Idealised-Disc-Galaxy/tuto_disc.ipynb
   MyNewTutorial/tutorial.ipynb
```

In order to generate the documentation on your side, before committing and pushing to github, you should first install the required sphinx packages:
```bash
cd doc
pip install -r rtd_requirements.txt
```
Once this is done you should run the following commnand:
```bash
cd doc
sphinx-build -M html source  build
```
This will generate a the file `doc/build/html/index.html` that you can open in your browser to check the results. Please make sure your tutorial appears OK on this before you push your developments.

You can also generate a pdf file using the following commnand:
```bash
cd doc
sphinx-build -M latexpdf source  build
```
Again, please make sure this works before pushing.

## Credits

If you provide a new tutorial, you should add your name and
contribution to the **Credits section** by editing the file `doc/source/credits.rst`.