Skip to content

Commit

Permalink
docs: Removes instructions for using the fileshare
Browse files Browse the repository at this point in the history 
This removes the instructions for running integration tests, which rely on data on the fileshare, in anticipation of that resource being deleted in the near future. It also removes some historical references to cmethods.
  • Loading branch information
@andrewphilipsmith
andrewphilipsmith committed Nov 27, 2024
1 parent 5d1a44e commit 30a8b2a
Showing 1 changed file with 8 additions and 102 deletions.
110 changes: 8 additions & 102 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title: "Contributing to our project"
title: "Contributing to clim-recal"
---

We welcome contributions to our repository and follow the [Turing Way Contributing Guidelines](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md). As the project develops we will expand this section with details more specific to our code base and potential use/application.
We welcome contributions to our repository and follow the [Turing Way Contributing Guidelines](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md).

# Documentation

Expand All @@ -12,9 +12,7 @@ Our documentation (including this file) is written in `md` and `qmd` file format

If you would like to render documentation locally you can do so via a [`conda`](https://docs.conda.io) or [`docker`](https://docker.com)

We appreciate your patience and encourage you to check back for updates on our ongoing documentation efforts.

### Locally via `conda`
### Running Quarto locally via `conda`

1. Ensure you have a [local installation](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) of `conda` or [`anaconda`](https://www.anaconda.com/download) .
1. Checkout a copy of our `git` repository
Expand All @@ -32,9 +30,9 @@ $ conda activate clim-recal
$ quarto preview
```

### Locally via `docker`
### Running Quarto locally via `docker`

If you have `docker` installed, you can run a version of the `jupyter` conifiguration and `quarto`. The simplest and quickest solution, assuming you have `docker` running, is:
If you have `docker` installed, you can run a version of the `jupyter` configuration and `quarto`. The simplest and quickest solution, assuming you have `docker` running, is:

```sh
$ git clone https://github.com/alan-turing-institute/clim-recal
Expand Down Expand Up @@ -97,7 +95,9 @@ isort (python)...........................................................Passed
# Running tests
Currently, only the `python` portions of `clim-recal` have unit tests, and some of those require direct access to `ClimateData` mounted on `/mnt/vmfileshare/ClimateData` (which matches our configuration on `linux`). There are ways of running those tests locally if you are able to mount the `ClimateData` drive to that path, either via `conda` or `docker` (`conda` if running `linux`, in theory any operating system if running `docker`). We will expand the details of this process in future, but for tests that do not require `ClimateData`, the instructions for running those are below:
Only some portions of the python `clim-recal` code has unit tests. Additionally there are integration tests which require direct access to [the data](/README#the-datasets) mounted on the hardcoded path `/mnt/vmfileshare/ClimateData` (which matches our configuration on `linux`). There are ways of running those integration tests locally if you are able to mount the `ClimateData` drive to that path, either via `conda` or `docker` (`conda` if running `linux`, in theory any operating system if running `docker`).
The instructions below cover running the tests that do not require additional data:
## Running tests in `conda`
Expand All @@ -110,47 +110,8 @@ $ conda create -n clim-recal -f environment.yml
$ conda activate clim-recal
$ cd python # Currently the tests must be run within the `python` folder
$ pytest
Test session starts (platform: linux, Python 3.9.18, pytest 7.4.3, pytest-sugar 0.9.7)
rootdir: code/clim-recal/python # Path printed is tweaked here for convenience
configfile: .pytest.ini
testpaths: tests, utils.py
plugins: cov-4.1.0, sugar-0.9.7
tests/test_debiasing.py ✓✓✓sss✓✓✓✓✓✓✓✓sss✓ 82% ████████▎
utils.py ✓✓✓✓ 100% ██████████
Saved badge to clim-recal/python/docs/assets/coverage.svg
---------- coverage: platform linux, python 3.9.18-final-0 -----------
Name Stmts Miss Cover
--------------------------------------------------------
conftest.py 32 4 88%
data_download/ceda_ftp_download.py 59 59 0%
debiasing/preprocess_data.py 134 134 0%
debiasing/run_cmethods.py 108 108 0%
load_data/data_loader.py 83 83 0%
resampling/check_calendar.py 46 46 0%
resampling/resampling_hads.py 59 59 0%
tests/test_debiasing.py 188 27 86%
--------------------------------------------------------
TOTAL 732 520 29%
5 files skipped due to complete coverage.
=========================== short test summary info ============================
SKIPPED [1] <doctest test_debiasing.RunConfig.mod_path[0]>:2: requires linux server mount paths
SKIPPED [1] <doctest test_debiasing.RunConfig.obs_path[0]>:2: requires linux server mount paths
SKIPPED [1] <doctest test_debiasing.RunConfig.preprocess_out_path[0]>:2: requires linux server mount paths
SKIPPED [1] <doctest test_debiasing.RunConfig.yield_obs_folder[0]>:2: requires linux server mount paths
SKIPPED [1] <doctest test_debiasing.RunConfig.yield_preprocess_out_folder[0]>:2: requires linux server mount paths
Results (0.14s):
16 passed
6 skipped
4 deselected
```
The `SKIPPED` messages of 6 [`doctests`](https://docs.python.org/3/library/doctest.html) show they are automatically skipped if the `linux server mount` is not found, specifically data to test in `/mnt/vmfileshare/ClimateData`.
## Running tests in Docker
With a `docker` install, tests can be run in two ways. The simplest is via `docker compose`:
Expand All @@ -164,58 +125,3 @@ $ docker compose exec jupyter bash -c "conda run -n clim-recal --cwd python pyte
```
This mirrors the way tests are run via `GitHub` `Actions` for continuous integration on <https://github.com/alan-turing-institute/clim-recal>.
To run tests that require mounting `ClimateData` (which are not enabled by default), you will need to have a local mount of the relevant drive. This is easiest to achieve by building the `compose/Dockerfile` separately (not using `compose`) with that drive mounted.
```sh
$ git clone https://github.com/alan-turing-institute/clim-recal
$ cd clim-recal
$ docker build -f compose/Dockerfile --tag 'clim-recal-test' .
$ docker run -it -p 8888:8888 -v /Volumes/vmfileshare:/mnt/vmfileshare clim-recal-test .
```
This will print information to the terminal including the link to the new `jupyter` session in this form:
```sh
[I 2023-11-16 13:46:31.350 ServerApp] http://127.0.0.1:8888/lab?token=a-long-list-of-characters-to-include-in-a-url
```
By copying your equivalent of `http://127.0.0.1:8888/lab?token=a-long-list-of-characters-to-include-in-a-url` you should be able to get a `jupyer` instance with all necessary packages installed running in your browser.
From there, you can select a `Terminal` options under `Other` to get access to the terminal within your local `docker` build. You can then change to the `python` folder and run the tests with the `server` option to include `ClimateData` tests as well (note the `a-hash-sequence` will depend on your build):
```sh
(clim-recal) jovyan@a-hash-sequence:~$ cd python
(clim-recal) jovyan@a-hash-sequence:~/python$ pytest -m server
Test session starts (platform: linux, Python 3.9.18, pytest 7.4.3, pytest-sugar 0.9.7)
rootdir: /home/jovyan/python
configfile: .pytest.ini
testpaths: tests, utils.py
plugins: cov-4.1.0, sugar-0.9.7
tests/test_debiasing.py ✓✓✓✓ 100% ██████████
Saved badge to /home/jovyan/python/docs/assets/coverage.svg
---------- coverage: platform linux, python 3.9.18-final-0 ---------
Name Stmts Miss Cover
--------------------------------------------------------------------
conftest.py 32 4 88%
data_download/ceda_ftp_download.py 59 59 0%
debiasing/preprocess_data.py 134 21 84%
debiasing/python-cmethods/cmethods/CMethods.py 213 144 32%
debiasing/run_cmethods.py 108 8 93%
load_data/data_loader.py 83 83 0%
resampling/check_calendar.py 46 46 0%
resampling/resampling_hads.py 59 59 0%
tests/test_debiasing.py 188 5 97%
utils.py 23 5 78%
--------------------------------------------------------------------
TOTAL 945 434 54%
5 files skipped due to complete coverage.
Results (955.60s (0:15:55)):
4 passed
22 deselected
```

0 comments on commit 30a8b2a

Please sign in to comment.