Skip to content
This repository has been archived by the owner on May 6, 2024. It is now read-only.

Included contributing section into README: #13

Merged
merged 3 commits into from
May 3, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
* [ ] Have you followed our guidelines in Section "Contributing" from README.md?
* [ ] Have you checked already existing notebooks to get an idea about our tutorial style?
* [ ] Have you extensively used markdown elements to structure and explain your notebook?
* [ ] Have you self-reviewed your code / notebook and corrected any misspellings?
* [ ] Have you uploaded your example data to [zenodo]( https://zenodo.org/ ) (see README) if needed?
* [ ] Have you checked if your notebook is running in the recommended standard conda enviroment [see here]((docs/RunningTutorials.md) and updates the [list of required python packages](./requirements.txt) if needed?
* [ ] Have you carefully checked that sphinx-based rendering is still working correctly?
* [ ] Have you written descriptive commit messages?
* [ ] Have you kept your pull request small and limited so that it is easy to review?
* [ ] Have the newest changes been merged into this branch?
36 changes: 35 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# tobac-tutorials

Tobac tutorials show different application cases for the cloud and precipitation tracking software tobac using jupyter notebooks. Th rendered versions of our tutorials are provided at [https://fsenf-tobac-tutorials.readthedocs.io](https://fsenf-tobac-tutorials.readthedocs.io). Please have a look there, first!
Tobac tutorials show different application cases for the cloud and precipitation tracking software tobac using jupyter notebooks. The rendered versions of our tutorials are provided at [https://fsenf-tobac-tutorials.readthedocs.io](https://fsenf-tobac-tutorials.readthedocs.io). Please have a look there, first!


## Getting Started
Expand All @@ -13,3 +13,37 @@ A step-by-step description to run the tutorials with jupyter is located [here](d
## Limitations

If you are using tobac 1.x, the notebooks here won#t work because of changes in the code structure. The equivalent notebooks can be found in the [examples](https://github.com/climate-processes/tobac/tree/master/examples) folder in the [tobac master branch](https://github.com/climate-processes/tobac/tree/master/examples).


## Contributing
You contribution is welcome!

Each additional tutorial notbeook helps new `tobac` users to understand the capability of the tracking software and supports creative use of feature identification and tracking in the atmospheric science context.


### Pull Request Requirements

Please provide a separate pull request:

* **with your example notebook included**
* please extensively use markdown elements to structure and explain your notebook
* check already existing notebooks to get an idea about our tutorial style
* please upload your example data to [zenodo]( https://zenodo.org/ ) (see next paragraph)
* please check if your notebook is running in the recommended standard conda enviroment [see here]((docs/RunningTutorials.md) and update the [list of required python packages](./requirements.txt) if needed

* **with your suggestions to change the documentation elements**, e.g. `index.rst`
* please care that sphinx-based rendering is still working correctly, [see here](docs/Testing-Sphinx-based-Rendering.md) for an intro to sphinx-based rendering of our tutorial content



### Example Data

Our tutorials live from realistic examples and example data.

We recommend:
* to upload your example data (preferably as netcdf file) to [zenodo]( https://zenodo.org/ )
* to label the data such that "tobac" is included in the zenodo title

Already existing `tobac` data can be found here:
* [**tobac on zenodo**]( https://zenodo.org/search?page=1&size=20&q=tobac )

103 changes: 103 additions & 0 deletions docs/Testing-Sphinx-based-Rendering.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@

# How to Check if Sphinx-based Rendering of `tobac-tutorials` is Working?

## Setup

The workflow has been tested in a linux system. We aim to build a static website out of the documentation material (incl. jupyter notebooks) present in `tobac-tutorials`.


### 1. Preparing the Local Environment

* **choose a separate place for your testing**

I will use the temporary directory `/tmp/website-testing` which I need to create. You can use a dedicated place of your choice ...

```bash
> mkdir /tmp/website-testing
> cd /tmp/website-testing
```
I will indicate my position now with the `/tmp/website-testing>` prompt.

* **get the official repository**

```bash
/tmp/website-testing> git clone https://github.com/climate-processes/tobac-tutorials
```

* **Python environment**
* create a python virtual env
```bash
/tmp/website-testing> python -m venv .python3-venv
```

* and install requirements
```bash
# deactivation conda is only necessary if your loaded conda before ...
/tmp/website-testing> conda deactivate

# activate the new env and upgrade `pip`
/tmp/website-testing> source .python3-venv/bin/activate
/tmp/website-testing> pip install --upgrade pip

# now everything is installed into the local python env!
/tmp/website-testing> pip install -r tobac-tutorials/requirements.txt

```
`pip`-based installation takes a bit of time, but is much faster than `conda`. If the installation runs without problems, you are ready to build the website.


### 2. Building the Website

Actually, only few steps are needed to build the website, i.e.


* **running sphinx for rendering**

```bash
/tmp/website-testing> cd tobac-tutorials

/tmp/website-testing/tobac-tutorials> make html
```

If no severe error appeared


* **view the HTML content**

```bash
/tmp/website-testing/tobac-tutorials> firefox _build/html/index.html
```


### 3. Parsing Your Local Changes

Now, we connect to your locally hosted `tobac-tutorials` repository and your development branch.

* **connect to your local repo**:
Assume your repo is located at `/tmp/tobac-tutorial-testing/tobac-tutorials`, then add a new remote alias and fetch all content with

```bash
/tmp/website-testing/tobac-tutorials> git remote add local-repo /tmp/tobac-tutorial-testing/tobac-tutorials
/tmp/website-testing/tobac-tutorials> git fetch --all
```
* **check your development branch out**:
Now, assume the your development branch is called `my-devel`, then do

```bash
# to get a first overview on available branches
/tmp/website-testing/tobac-tutorials> git branch --all

# and then actually get your development branch
/tmp/website-testing/tobac-tutorials> git checkout -b my-devel local-repo/my-devel
```

You should see your developments, now ...

* **build and view website again**

```bash
/tmp/website-testing/tobac-tutorials> make clean
/tmp/website-testing/tobac-tutorials> make html
/tmp/website-testing/tobac-tutorials> firefox _build/html/index.html
```