Skip to content

Commit ee160e5

Browse files
jourdainjourdain
committed
docs(website): add nersc section
1 parent e0ee1bd commit ee160e5

19 files changed

Lines changed: 250 additions & 12 deletions

‎docs/.vitepress/config.mjs‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,20 +15,22 @@ export default defineConfig({
1515
logo: "/icon-full.png",
1616
nav: [
1717
{ text: "Home", link: "/" },
18-
{ text: "NERSC", link: "/nersc/" },
18+
{ text: "NERSC", link: "/nersc/login" },
1919
{ text: "Guides", link: "/guides/data" },
2020
],
2121

2222
sidebar: {
2323
"/nersc/": [
2424
{
2525
text: "Connecting to NERSC",
26-
items: [{ text: "Login", link: "/nersc/login" }],
26+
items: [
27+
{ text: "Login", link: "/nersc/login" },
28+
{ text: "Installation", link: "/nersc/installation" },
29+
],
2730
},
2831
{
2932
text: "Perlmutter",
3033
items: [
31-
{ text: "Introduction", link: "/nersc/perlmutter" },
3234
{ text: "Quick View", link: "/nersc/perlmutter-run-quickview" },
3335
{
3436
text: "Quick Compare",
@@ -59,19 +61,10 @@ export default defineConfig({
5961
{ text: "Resources", link: "/guides/quickcompare/resources" },
6062
],
6163
},
62-
{
63-
text: "Installations",
64-
items: [
65-
{ text: "Desktop bundle", link: "/guides/installation/desktop" },
66-
{ text: "Conda package", link: "/guides/installation/conda" },
67-
],
68-
},
6964
{
7065
text: "Development",
7166
items: [
72-
{ text: "Introduction", link: "/guides/dev" },
7367
{ text: "Setup", link: "/guides/dev/setup" },
74-
{ text: "Publish to NERSC", link: "/guides/dev/nersc" },
7568
{ text: "Continuous Integration", link: "/guides/dev/ci" },
7669
],
7770
},

‎docs/guides/dev/ci.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Continuous integration
2+
3+
QuickView has 4 workflows:
4+
- __website (automatic):__ Update website when code get pushed to the repository.
5+
- __test (automatic):__ Validate PR and code based on the current tests implemented.
6+
- __release (manual):__ Will look at git history to generate version bump with associated changelog. This will publish a new version to PyPI. Then conda-forge will catchup the new version and will automatically publish it the next day or so.
7+
- __package (automatic):__ Will generate the desktop bundle and link them to the release entry inside Github.
8+
9+
## WebSite
10+
11+
The WebSite is using VitePress to present the various markdown files living under `./docs/**/*.md` into a website available at https://kitware.github.io/QuickView/.
12+
13+
## Release
14+
15+
This workflow needs to be [triggered manually on this page](https://github.com/Kitware/QuickView/actions/workflows/release.yml) by clicking on the __Run workflow__ button.

‎docs/guides/dev/setup.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Development setup
2+
3+
For Python development while you can use a mix of conda and pip install, it is generally not recommended. So we will provide 2 setups and it will be up to the user to choose what better match his usage.
4+
5+
## Conda setup
6+
7+
```sh
8+
# Grab the code you aim to work with
9+
git clone <repository-url>
10+
cd <repository-name>
11+
12+
# Set up conda environment
13+
conda env create -f quickview-env.yml
14+
conda activate quickview
15+
16+
# Install QuickView
17+
pip install -e .
18+
```
19+
20+
Then to run the application
21+
22+
```sh
23+
quickview # or the name of the executable your application is providing
24+
```
25+
26+
## UV setup + Downloaded ParaView
27+
28+
```
29+
# Grab the code you aim to work with
30+
git clone <repository-url>
31+
cd <repository-name>
32+
33+
# Setup your python environment
34+
uv venv -p 3.12 # force python version to match ParaView 6
35+
uv sync --all-extras --dev
36+
37+
# Activate environment
38+
source .venv/bin/activate
39+
40+
# Install commit analysis
41+
pre-commit install
42+
pre-commit install --hook-type commit-msg
43+
44+
# Allow live code edit
45+
uv pip install -e .
46+
```
47+
48+
Then to run the application, you will need ParaView. The example below provide an example for macOS.
49+
50+
```sh
51+
/Applications/ParaView-6.0.1.app/Contents/bin/pvpython --venv .venv -m e3sm_quickview.app
52+
```
53+
54+
With this setup, any commit will be automatically checked with the pre-commit hooks. But you can also run those manually via the command line below:
55+
56+
```sh
57+
pre-commit run --all-files
58+
```

‎docs/guides/index.md‎

Whitespace-only changes.

‎docs/guides/quickcompare/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# What is QuickCompare?

‎docs/guides/quickcompare/resources.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Application binaries
2+
3+
QuickCompare is available as a desktop bundle that can be downloaded for Windows,
4+
Mac and Linux directly from our release notes on GitHub.
5+
6+
[Releases (binary download)](https://github.com/Kitware/E3SMQuickCompare/releases)
7+
8+
## Sample data
9+
10+
To be filled
11+
12+
## Git repository
13+
14+
- [Repository](https://github.com/Kitware/E3SMQuickCompare)
15+
- [Bug reports / feature requests](https://github.com/Kitware/E3SMQuickCompare/issues)

‎docs/nersc/index.md‎

Whitespace-only changes.

‎docs/nersc/installation.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# NERSC setup explained
2+
3+
Since the QuickView applications are just Python packages, we install them inside conda environment related to their funding project (`/global/common/software/m4359/`).
4+
5+
## Custom conda environments
6+
7+
Create a directory for all the conda environments we aim to enable for our users.
8+
9+
```sh
10+
mkdir -p /global/common/software/m4359/conda-envs
11+
```
12+
13+
Then for each project we will create an environment inside that directory.
14+
15+
```sh
16+
module load conda
17+
conda create --prefix /global/common/software/m4359/conda-envs/e3sm-quickview python=3.13
18+
```
19+
20+
After that you can activate such environment and install the application like QuickView
21+
22+
```sh
23+
conda activate /global/common/software/m4359/conda-envs/e3sm-quickview
24+
conda install e3sm-quickview
25+
```
26+
27+
## Executable Shortcut
28+
29+
Inside `/global/common/software/m4359/` you can create shell script that will provide a shortcut for starting each application.
30+
31+
For example, we've created `/global/common/software/m4359/quickview` with the following content
32+
33+
```sh
34+
#!/usr/bin/env bash
35+
36+
module load conda
37+
conda activate /global/common/software/m4359/conda-envs/e3sm-quickview
38+
quickview -p 0
39+
```
40+
41+
And to make that file executable, you can run `chmod +x /global/common/software/m4359/quickview` to streamline its usage.
42+
43+
## Updating an application
44+
45+
In order to update a given application you will need to find the version you want to install and then run something like:
46+
47+
```sh
48+
module load conda
49+
conda activate /global/common/software/m4359/conda-envs/e3sm-quickview
50+
51+
conda install "e3sm-quickview>=1.3.3" # <== fix version
52+
```

‎docs/nersc/login.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# NERSC Accounts
2+
3+
In order to use the NERSC facilities, you need to obtain a NERSC account and your user account must be tied to a NERSC Allocation. Before logging into any compute resource, you will need to set a strong password. Please see our password rules if you need help creating a strong password. Once you have an account, you can log in to Iris to manage account details. This will include setting up multi-factor authentication (MFA) which is required to access all NERSC systems and services.
4+
5+
Please refer to [NERSC documentation on how to get started](https://docs.nersc.gov/getting-started/).
6+
7+
## Login
8+
9+
[![Connect to perlmutter](https://docs.nersc.gov/systems/perlmutter/images/PerlmutterCabinetsFinal.jpg)Connect to Perlmutter](https://jupyter.nersc.gov/hub/login)

‎docs/nersc/login/login-00.png‎

201 KB
Loading

0 commit comments

Comments
 (0)