Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve tabs #793

Merged
merged 9 commits into from
Sep 20, 2024
Merged

Improve tabs #793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
efa56d3
Changed tab functionality:
atteggiani Sep 10, 2024
94743fb
Updated README with new tab functionality
atteggiani Sep 10, 2024
d5f64fc
Updated 'docs/getting_started/are.md' with new tab functionality
atteggiani Sep 11, 2024
6a098f6
Updated 'docs/getting_started/set_up_nci_account.md' with new tab fun…
atteggiani Sep 11, 2024
75c4355
Updated docs/models/configurations/access-om.md' with new tab functio…
atteggiani Sep 11, 2024
e167f8c
Updated 'docs/models/model_components/ocean.md' with new tab function…
atteggiani Sep 11, 2024
915bd28
Updated 'docs/models/model_components/sea-ice.md' with new tab functi…
atteggiani Sep 11, 2024
dde42cf
Fix tabFunctionality JS function to open the first tab in case there …
atteggiani Sep 19, 2024
ee12925
Added possibility to add multiple (spaced-out) IDs in 'tabcontentfor'…
atteggiani Sep 19, 2024
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
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ The following custom tags are available:
|**Code block**|\```<br>&emsp;code block<br>```|\<pre><br>&emsp;\<code>code block\</code><br>\</pre>|<pre><code>code block</code></pre>|
|**[Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (not collapsible)**|!!! warning<br>&emsp;this is a warning admonition|\<div class="admonition warning"><br>&emsp;this is a warning<br>&emsp;admonition<br>\<div>|![warning admonition](docs/assets/assets_for_readme/warning_admonition.png)|
|**Collapsible [Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)**|??? warning title<br>&emsp;this is a collapsible warning admonition|\<details class="warning"><br>&emsp;\<summary><br>&emsp;&emsp;\<p><br>&emsp;&emsp;&emsp;this is a collapsible<br>&emsp;&emsp;&emsp;warning admonition<br>&emsp;&emsp;\</p><br>&emsp;\</summary><br>\</details>|![collapsible warning admonition](docs/assets/assets_for_readme/collapsible_warning_admonition.gif)|
|**Tabs**|N/A|\<div class="tabLabels" label="your-tab-label"><br>&emsp;\<button>Tab1\</button><br>&emsp;\<button>Tab2\</button><br>\</div><br>\<div class="tabContents" label="your-tab-label"><br>&emsp;\<div><br>&emsp;&emsp;Content for tab1<br>&emsp;\</div><br>&emsp;\<div><br>&emsp;&emsp;Content for tab2<br>&emsp;\</div><br>\</div>|![tabs](docs/assets/assets_for_readme/tabs.gif)|
|**Tabs**|N/A|\<div class="tabLabels" label="your-tab-label"><br>&emsp;\<button id="id-tab1">Tab1\</button id="id-tab2"><br>&emsp;\<button>Tab2\</button><br>\</div><br>\<div contentfor="id-tab1"><br>&emsp;&emsp;Content for tab1<br>&emsp;\</div><br>&emsp;\<div contentfor="id-tab2"><br>&emsp;&emsp;Content for tab2<br>&emsp;\</div>|![tabs](docs/assets/assets_for_readme/tabs.gif)|


# License
Expand Down
14 changes: 4 additions & 10 deletions docs/css/access-nri.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1097,6 +1097,7 @@ img.terminalSwitch {
img.terminalSwitch:hover {
cursor: pointer;
}

/* ===============================================================
General styling for html tabs
*/
Expand Down Expand Up @@ -1142,18 +1143,11 @@ img.terminalSwitch:hover {
}

/* Style the tab content */
.tabContents > * {
[tabcontentfor] {
display: none;
}

.tabContents > .activeTabContent {
display: block;
}

.version-tabs {
margin-bottom: 0.3rem;
font-size: 1.2em;
width: 100%;
[tabcontentfor].activeTab {
display: contents;
}

/* ===============================================================
Expand Down
155 changes: 66 additions & 89 deletions docs/getting_started/are.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,30 +14,24 @@ To use ARE, you must have an NCI account and be a member of a project with compu
<button id="vdi"><i>Virtual Desktop (VDI)</i></button>
<button id="jupyterlab"><i>JupyterLab</i></button>
</div>
<!-- Tab contents -->
<div class="tabContents" label="are-apps">
<!-- VDI -->
<div>
To start an ARE VDI session go to the <a href="https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new" target="_blank">ARE VDI Desktop</a> page.
</div>
<!-- Jupyterlab -->
<div>
To start an ARE JupyterLab session go to the <a href="https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new" target="_blank">ARE JupyterLab</a> page.
</div>
<div tabcontentfor="vdi" markdown>
To start an ARE VDI session go to the [ARE VDI Desktop](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new) page.
</div>
<div tabcontentfor="jupyterlab" markdown>
To start an ARE JupyterLab session go to the [ARE JupyterLab](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new) page.
</div>
<!-- End of tab contents -->

### Session options
Launching an ARE session is similar to submitting an interactive [PBS job](https://opus.nci.org.au/display/Help/4.+PBS+Jobs) that enables you to connect to a _Gadi_ computing node.<br>
Hence, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/PBS+Directives+Explained) and other options you can select:

- **<span markdown id="walltime-option">Walltime (hours)</span>**<br>
- **<span id="walltime-option">Walltime (hours)</span>**<br>
Number of hours your VDI session will run for (unless manually ended earlier).<br>
The maximum number of hours an ARE session can run for depends on the selected Queue. For more information, check [Gadi Queue Limits](https://opus.nci.org.au/display/Help/Queue+Limits).

!!! warning
Once the session ends any operation still in progress on the session's computing node(s) will be immediately terminated.

- **Queue**<br>
Gadi queue that your session will be scheduled in. For more information check [Gadi Queue Structure](https://opus.nci.org.au/display/Help/Queue+Structure).

Expand All @@ -53,10 +47,11 @@ Hence, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/
The specified project must have allocated _Service Units (SU)_.<br>
For more information, check [how to join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects).

- **<span markdown id="storage-option">Storage</span>**<br>
- **Storage**<br>
`/g/data` (inserted as _gdata/&lt;project-ID&gt;_) `/scratch` (inserted as _scratch/&lt;project-ID&gt;_) data storage projects that will be available to the session.<br>
In ARE, data storage locations need to be explicitly defined. This means that you need to insert any `/g/data` and `/scratch` project folders you want to execute data I/O operations from.<br>
Multiple storage projects are separated by a plus (_+_) (e.g., _gdata/tm70+gdata/hh5+scratch/xp65_).
{: id="storage-option"}

!!! warning
Generally, you need to be a member of the specified projects to access their storage data.<br>
Expand All @@ -68,64 +63,41 @@ Hence, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/
Multiple licenses are separated by a colon (_:_).

### Advanced options
<!-- Tab contents -->
<div class="tabContents" label="are-apps">
<!-- VDI -->
<div>
</div>
<!-- Jupyterlab -->
<div>
<ul>
<li>
<b>Extra arguments</b>
<br>
Additional arguments to pass on the JupyterLab command line (e.g., <i>--debug</i>, <i>--log-level=INFO</i>)
</li>
<li>
<b id="module-directories-option">Module directories</b>
<br>
Include module directories.
<br>
It is the eqivalent of <code>module use &lt;/path/to/module/directory&gt;</code> run on the command line.
<div class='admonition warning'>
You also need to include the project directory of each module directory in the <a href="#storage-option"><i>Storage</i></a> option.
</div>
</li>
<li>
<b>Modules</b>
<br>
Include modules.
It is the equivalent of <code>module load &lt;module-name&gt;</code> run on the command line.
<div class='admonition warning'>
If the module is not inside <i>Gadi</i>'s default module directory <code>/apps/Modules/modulefiles</code>, you need to include the module directory in the <a href="#module-directories-option"><i>Module directories</i></a> option.
</div>
</li>
<li>
<b id="venv-base-option">Python or Conda virtual environment base</b>
<br>
Path to a Python or conda base environment to be activated for the JupyterLab session.
<br>
It is the equivalent of <code>source &lt;path/to/environment/bin/activate&gt;</code> run on the command line.
<div class='admonition warning'>
You also need to include the project directory of the virtual environment in the <a href="#storage-option"><i>Storage</i></a> option.
</div>
</li>
<li>
<b>Conda environment</b>
<br>
Name of a specific conda environment to be activated for the JupyterLab session.
<br>
It is the equivalent of <code>conda activate &lt;environment-name&gt;</code> run on the command line.
<div class='admonition warning'>
You need to include the path to the conda base environment in the <a href="#venv-base-option"><i>Python or Conda virtual environment base</i></a> option.
</div>
</li>
</ul>
</div>
</div>
<!-- End of tab contents -->
<div tabcontentfor="jupyterlab" markdown>

- **Extra arguments**<br>
Additional arguments to pass on the JupyterLab command line (e.g., `--debug_`, `--log-level=INFO`)

- **<span id="module-directories-option">Module directories<span>**<br>
Include module directories.<br>
It is the eqivalent of `module use </path/to/module/directory>` run on the command line.

!!! warning
You also need to include the project directory of each module directory in the [_Storage_](#storage-option) option.

- **Modules**<br>
Include modules.<br>
It is the equivalent to running `module load <module-name>` on the command line.

- **Environment variables**<br>
!!! warning
If the module is not inside _Gadi_'s default module directory `/apps/Modules/modulefiles`, you need to include the module directory in the [_Module directories_](#module-directories-option) option.

- **<span id="venv-base-option">Python or Conda virtual environment base</span>**<br>
Path to a Python or conda base environment to be activated for the JupyterLab session.<br>
It is the equivalent to running `source <path/to/environment/bin/activate>` on the command line.

!!! warning
You also need to include the project directory of the virtual environment in the [_Storage_](#storage-option) option.

- **Conda environment**<br>
Name of a specific conda environment to be activated for the JupyterLab session.<br>
It is the equivalent to running `conda activate <environment-name>` on the command line.

!!! warning
You need to include the path to the conda base environment in the [_Python or Conda virtual environment base_](#venv-base-option) option.
</div>

- **Environment variables** <br>
Environment variables passed to the session. Identical to the [`-v` PBS directive](https://opus.nci.org.au/display/Help/PBS+Directives+Explained#PBSDirectivesExplained--v%3Cvar=10,%22var2='A,B'%22%3E).<br>
Multiple environment variables are separated by a comma (_,_).

Expand All @@ -144,24 +116,18 @@ Hence, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/
1. Click on the <i>Launch</i> button to launch the session. You will be prompted to your Interactive Sessions page and you will see your last requested session at the top.

2.
<!-- Tab contents -->
<div class="tabContents" label="are-apps">
<!-- VDI -->
<div>
Wait until your session starts and then click on the <i>Launch VDI Desktop</i> button to open a new tab with the VDI interface.
<br>
Inside the VDI interface, you can open the terminal by clicking on the black terminal icon at the top of the window.
<img src="/assets/launch_are_vdi_desktop.gif" alt="Launch ARE VDI Desktop" class="example-img" loading="lazy"/>
</div>
<!-- Jupyterlab -->
<div>
Wait until your session starts and then click on the <i>Open JupyterLab</i> button to open a new tab with the JupyterLab interface.
<br>
Inside the JupyterLab interface, you can open a new notebook by clicking on the Python3 Notebook button in the Launcher panel (to open a new Laucher panel, click on the plus button <img src="/assets/jupyterlab_plus_button.png" alt="Plus button" style="height:1em"/> next to your current tab).
<img src="/assets/launch_are_jupyterlab.gif" alt="Launch ARE JupyterLab" class="example-img" loading="lazy"/>
</div>
<div tabcontentfor="vdi">
Wait until your session starts and then click on the <i>Launch VDI Desktop</i> button to open a new tab with the VDI interface.
<br>
Inside the VDI interface, you can open the terminal by clicking on the black terminal icon at the top of the window.
<img src="/assets/launch_are_vdi_desktop.gif" alt="Launch ARE VDI Desktop" class="example-img" loading="lazy"/>
</div>
<div tabcontentfor="jupyterlab">
Wait until your session starts and then click on the <i>Open JupyterLab</i> button to open a new tab with the JupyterLab interface.
<br>
Inside the JupyterLab interface, you can open a new notebook by clicking on the Python3 Notebook button in the Launcher panel (to open a new Laucher panel, click on the plus button <img src="/assets/jupyterlab_plus_button.png" alt="Plus button" style="height:1em"/> next to your current tab).
<img src="/assets/launch_are_jupyterlab.gif" alt="Launch ARE JupyterLab" class="example-img" loading="lazy"/>
</div>
<!-- End of tab contents -->

## Delete an ARE session
You can delete a session before its automatic expiration (based on the specified [Walltime](#walltime-option) by clicking on the session's ![Session Delete button](/assets/session_delete_button.png){: style="height:1em"} button in the [Interactive Sessions](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sessions) page.
Expand All @@ -170,4 +136,15 @@ You can delete a session before its automatic expiration (based on the specified
- [https://opus.nci.org.au/display/Help/ARE+User+Guide](https://opus.nci.org.au/display/Help/ARE+User+Guide)
- [https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/desktop_vnc/ncigadi/session_contexts/new)
- [https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/jupyter/ncigadi/session_contexts/new)
</custom-references>
</custom-references>

<!-- Add specific style to fix big gap between ul elements divided because of the tab content-->
<style>
ul:has(#venv-base-option) {
margin-bottom: 0;
}
div[tabcontentfor="jupyterlab"] + ul,
div[tabcontentfor="jupyterlab"] + ul > li:first-child > p:first-child {
margin-top: 0;
}
</style>
87 changes: 27 additions & 60 deletions docs/getting_started/set_up_nci_account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,12 @@ You will be prompted to create a passphrase linked to the SSH key, which you wil
As you will see in the next step, you will not need to enter the passphrase every time you login to _Gadi_.

#### Add the SSH key to the SSH-agent

<div class="tabLabels" label="systems">
<button id="macos">MacOS</button>
<button id="linux-windows">Linux / Windows</button>
</div>

An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server.<br>
To add the SSH key to the SSH-agent:

Expand All @@ -129,38 +135,19 @@ To add the SSH key to the SSH-agent:
<terminal-line>Agent pid &lt;agent-PID&gt;</terminal-line>
</terminal-window>
2. Add your SSH key to the SSH-agent by running:
<!-- Tab labels -->
<div class="tabLabels" label="systems">
<button id="macos">MacOS</button>
<button id="linux-windows">Linux / Windows</button>
</div>
<!-- Tab content -->
<div class="tabContents" label="systems">
<!-- MacOS -->
<div>
<pre><code>ssh-add --apple-use-keychain ~/.ssh/id_gadi</code></pre>
You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent:
<terminal-window>
<terminal-line data="input">ssh-add --apple-use-keychain ~/.ssh/id_gadi</terminal-line>
<terminal-line>Enter passphrase for &lt;$HOME&gt;/.ssh/id_gadi:</terminal-line>
<terminal-line lineDelay=3000>Identity added: &lt;$HOME&gt;/.ssh/id_gadi &lt;$USER@hostname&gt;</terminal-line>
</terminal-window>
<div class='admonition warning'>
If you are using a MacOS version prior to Monterey (12.0), substitute the <code>--apple-use-keychain</code> flag with <code>-K</code>.
</div>
</div>
<!-- Linux/Windows -->
<div>
<pre><code>ssh-add ~/.ssh/id_gadi</code></pre>
You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent:
<terminal-window>
<terminal-line data="input">ssh-add ~/.ssh/id_gadi</terminal-line>
<terminal-line>Enter passphrase for &lt;$HOME&gt;/.ssh/id_gadi:</terminal-line>
<terminal-line lineDelay=3000>Identity added: &lt;$HOME&gt;/.ssh/id_gadi &lt;$USER@hostname&gt;</terminal-line>
</terminal-window>
</div>
<pre><code>ssh-add <span tabcontentfor="macos" markdown>--apple-use-keychain</span> ~/.ssh/id_gadi</code></pre>

You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent:
<terminal-window>
<terminal-line data="input">ssh-add <span tabcontentfor="macos" markdown>--apple-use-keychain</span> ~/.ssh/id_gadi</terminal-line>
<terminal-line>Enter passphrase for &lt;$HOME&gt;/.ssh/id_gadi:</terminal-line>
<terminal-line lineDelay=3000>Identity added: &lt;$HOME&gt;/.ssh/id_gadi &lt;$USER@hostname&gt;</terminal-line>
</terminal-window>
<div tabcontentfor="macos" markdown>

!!! warning
If you are using a MacOS version prior to Monterey (12.0), substitute the `--apple-use-keychain` flag with `-K`.
</div>
<!-- End of tab content -->

#### Create/Update the SSH config file
The `~/.ssh/config` is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all.<br>
Expand All @@ -173,35 +160,15 @@ touch ~/.ssh/config
If you already have an existing `~/.ssh/config` file, the above command will not have any effect.

The following lines should be added to your `~/.ssh/config` to describe the SSH configuration for _Gadi_ (replace `<your-NCI-username>` with your NCI _username_, e.g., `ab1234`):
<div class="tabContents" label="systems">
<!-- MacOS -->
<div markdown>
```
Host gadi
Hostname gadi.nci.org.au
User &lt;your-NCI-username&gt;
ForwardX11 true
ForwardX11Trusted yes
IdentityFile ~/.ssh/id_gadi
AddKeysToAgent yes
UseKeychain yes
```
</div>
<!-- Linux/Windows -->
<div markdown>
```
Host gadi
Hostname gadi.nci.org.au
User &lt;your-NCI-username&gt;
ForwardX11 true
ForwardX11Trusted yes
IdentityFile ~/.ssh/id_gadi
AddKeysToAgent yes
```
</div>
</div>
</code></pre>
<!-- End of tab content -->

<pre><code>Host gadi
Hostname gadi.nci.org.au
User <your-NCI-username>
ForwardX11 true
ForwardX11Trusted yes
IdentityFile ~/.ssh/id_gadi
AddKeysToAgent yes
<span tabcontentfor="macos">UseKeychain yes</span></code></pre>

!!! warning
If you already have an existing `~/.ssh/config` file which contains configurations for any `Host` (e.g., by using `Host *`), make sure you delete any of the keywords present in that SSH configuration from the `Gadi` configuration above.
Expand Down
Loading
Loading