merge main and finalise index

Author: bcumming

.github/CODEOWNERS

@@ -1,6 +1,7 @@
 * @bcumming @msimberg @RMeli
 docs/access/jupyterlab.md @rsarm
-docs/services/firecrest @jpdorsch @ekouts
+docs/services/firecrest.md @jpdorsch @ekouts @theely @iB0nes
+docs/services/devportal.md @jpdorsch @ekouts @theely @iB0nes
 docs/services/kubernetes @eliaoggian
 docs/software/communication @Madeeks @msimberg
 docs/software/devtools/linaro @jgphpc

.github/actions/spelling/allow.txt

@@ -76,6 +76,8 @@ NICs
 NVMe
 Nordend
 OpenFabrics
+OAuth
+OIDC
 OSS
 OSSs
 OTP
@@ -293,6 +295,7 @@ subtables
 supercomputing
 superlu
 sysadmin
+simberg
 tarball
 tcl
 tcsh
@@ -354,3 +357,4 @@ jobscript
 Scalasca
 tracefile
 Vampir
+XAmz

.github/actions/spelling/patterns.txt

@@ -14,6 +14,7 @@ Säntis
 ScaLAPACK
 VSCode
 aarch64
+WSO2
 
 # markdown figure
 !\[.*\]\(.*\)
@@ -41,3 +42,6 @@ https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0
 
 # img tag
 <img.*>
+
+# @name (e.g. github handles)
+@[A-Za-z0-9-_]+

docs/services/firecrest.md renamed to docs/access/firecrest.md

@@ -3,9 +3,9 @@
 
 FirecREST is a RESTful API for programmatically accessing High-Performance Computing resources, developed at CSCS.
 
-Users can make use of FirecREST to automate access to HPC, enabling [CI/CD pipelines](https://eth-cscs.github.io/firecrest-v2/use_cases/CI-pipeline/), [workflow managers](https://github.com/eth-cscs/firecrest/tree/master/examples/airflow-operators), and other tools against HPC resources.
+Users can make use of FirecREST to automate access to HPC, enabling [CI/CD pipelines](https://eth-cscs.github.io/firecrest-v2/use_cases/CI-pipeline/), [workflow orchestrators](https://eth-cscs.github.io/firecrest-v2/use_cases/workflow-orchestrator/), and other tools against HPC resources.
 
-Additionally, scientific platform developers can integrate FirecREST into [web-enabled portals](https://my.hpcp.cscs.ch) and [applications](https://github.com/eth-cscs/firecrest/tree/master/examples/UI-client-credentials), allowing them to securely access authenticated and authorized CSCS services such as job submission and data transfer on HPC systems.
+Additionally, scientific platform developers can integrate FirecREST into [web-enabled portals](https://eth-cscs.github.io/firecrest-ui/home/) and [web UI applications](https://eth-cscs.github.io/firecrest-v2/use_cases/UI-client-credentials/), allowing them to securely access authenticated and authorized CSCS services such as job submission and data transfer on HPC systems.
 
 Users can make HTTP requests to perform the following operations:
 
@@ -55,7 +55,7 @@ FirecREST is available for all three major [Alps platforms][ref-alps-platforms],
 
 ### Clients and access tokens
 
-For authenticating requests to FirecREST, **client applications** use an **access token** instead of directly using the user's credentials.
+For authenticating requests to FirecREST, [client applications][ref-devportal-application] use an **access token** instead of directly using the user's credentials.
 The access token is a signed JSON Web Token ([JWT](https://jwt.io/introduction)) which contains user information and is only valid for a short time (5 minutes).
 Behind the API, all commands launched by the client will use the account of the user that registered the client, inheriting their access rights.
 
@@ -65,77 +65,14 @@ Every client has a client ID (Consumer Key) and a secret (Consumer Secret) that
     ```
     curl -s -X POST https://auth.cscs.ch/auth/realms/firecrest-clients/protocol/openid-connect/token \
          --data "grant_type=client_credentials" \
-         --data "client_id=<your_client>" \
-         --data "client_secret=<your_secret>"
+         --data "client_id=<client_id>" \
+         --data "client_secret=<client_secret>"
     ```
 
 You can manage your client application on the [CSCS Developer Portal][ref-devportal].
 
-[](){#ref-devportal}
-### CSCS Developer Portal
 
-The [Developer Portal](https://developer.cscs.ch) facilitates CSCS users to manage subscriptions to an API at CSCS (such as FirecREST v1/v2).
-
-Start by browsing to [developer.cscs.ch](https://developer.cscs.ch), then sign in by clicking the "SIGN-IN" button on the top right hand corner of the page.
-
-Once logged in, you will see a list of APIs that are available to your user.
-
-!!! Warning
-    You might not see version 1 or version 2 of some API. You will be able to see all the versions when you *subscribe* your Application to the API.
-
-### Creating an Application
-
-Click on the "Applications" button at the top of the screen to manage your Applications.
-
-![FirecREST Main Page](../images/firecrest/f7t-apis.png)
-
-To create a new application, click on the "ADD NEW APPLICATION" button at the top of the Applications page, and complete the mandatory fields (marked with `*`).
-Make sure to give the application a unique name and select the number of requests per minute.
-When finished, click on the "Save" button.
-
-!!! note
-    To subscribe to an API you need at least one application, for which it is possible to use the DefaultApplication.
-
-!!! note
-    The quota of requests per minute will be shared by all subscribers to the Application over all APIs.
-
-### Configuring Production Keys
-
-Once the Application is created, create the Production Keys (`Client ID` and `Client Secret`) by clicking on "Production Keys" 
-
-![FirecREST production keys](../images/firecrest/f7t-keys.png)
-
-
-Use this if this is your first FirecREST application, or if you wish to create new keys.
-
-* click on the "Generate Keys" button at the bottom of the page
-
-![FirecREST existing keys](../images/firecrest/f7t-generate-keys.png)
-
-Once the keys are generated, you will see the pair "Consumer Key" and "Consumer Secret".
-
-![FirecREST keys](../images/firecrest/f7t-keys-overview.png)
-
-!!! warning
-    Store this pair of credentials securely, these are the access keys to your resources at CSCS.
-
-### Subscribe to an API
-
-Once you have set up your Application, is time to subscribe it to an API.
-
-To do so:
-
-* (8a) click on the "Subscriptions" option on the left panel
-* (8b) click the :fontawesome-solid-circle-plus: "Subscribe APIS" button
-* (8c) choose the API you want to subscribe to by clicking the "Subscribe" button
-
-![FirecREST subscriptions](../images/firecrest/f7t-api-subscriptions.png)
-
-Back on the Subscription Management page, you can review your active subscriptions and APIs that your Application has access to.
-
-![FirecREST subscription management](../images/firecrest/f7t-api-subscriptions-management.png)
-
-To use your Application to access FirecREST, follow the [API documentation](https://eth-cscs.github.io/firecrest-v2/openapi).
+To use your client credentials to access FirecREST, follow the [API documentation](https://eth-cscs.github.io/firecrest-v2/openapi).
 
 ## Getting Started
 
@@ -443,8 +380,9 @@ A staging area is used for external transfers and downloading/uploading a file f
 
 ## Further Information
 
-* [FirecREST UI for HPC Platform](https://my.hpcp.cscs.ch)
-* [FirecREST UI for ML Platform](https://my.mlp.cscs.ch)
+* [HPC Platform Dashboard](https://my.hpcp.cscs.ch)
+* [ML Platform Dashboard](https://my.mlp.cscs.ch)
+* [C&W Platform Dashboard](https://my.cwp.cscs.ch)
 * [FirecREST OpenAPI Specification](https://eth-cscs.github.io/firecrest-v2/openapi)
 * [FirecREST Official Docs](https://eth-cscs.github.io/firecrest-v2)
 * [Documentation of pyFirecREST](https://pyfirecrest.readthedocs.io/)

docs/access/index.md

@@ -26,6 +26,12 @@ This documentation guides users through the process of accessing CSCS systems an
 
     [:octicons-arrow-right-24: SSH][ref-ssh]
 
+-   :material-fire-circle: __FirecREST__
+
+    FirecREST is a RESTful API for programmatically accessing High-Performance Computing resources.
+
+    [:octicons-arrow-right-24: FirecREST][ref-firecrest]
+
 -   :simple-jupyter: __JupyterLab__
 
     JupyterLab is a feature-rich notebook authoring application and editing environment.

docs/build-install/applications/index.md

@@ -17,9 +17,3 @@ Modern HPC applications and software stacks are often very complicated, and ther
 
 </div>
 
-<div class="grid cards" markdown>
-
-- :fontawesome-solid-earth-americas: __[Community codes][ref-software-installation-guides]__ – guides on how to install commonly requested or difficult to install software.
-
-</div>
-

docs/build-install/index.md

@@ -4,6 +4,51 @@
 This documentation is developed using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework, and the source code for the docs is publicly available on [GitHub](https://github.com/eth-cscs/cscs-docs).
 This means that everybody, CSCS staff and the CSCS user community can contribute to the documentation.
 
+## Making suggestions or small changes
+
+If you have a suggestion, comment or small change to make when reading the documentation, there are three ways to reach out.
+
+1.  **Edit the page inline**: click on the :material-pencil: icon on the top right hand corner of each page, and make the change inline. When you click "commit", and create a pull request, which will then be reviewed by the CSCS docs team.
+1.  **Create a GitHub issue**: create an issue on the [issue page](https://github.com/eth-cscs/cscs-docs/issues) on the GitHub repository.
+1.  **Create a CSCS service desk ticket**: create a ticket on the CSCS service desk.
+    This is useful if you don't have a GitHub account, or would prefer not to use Github.
+
+## Before starting
+
+The CSCS documentation takes contributions from all CSCS staff, with a _core team_ of maintainers responsible for ensuring that the overall documentation is well organised, that pages are well written and up to date, and that contributions are reviewed and merged as quickly as possible.
+
+??? question "Who are the core team?"
+    The docs core team are:
+
+    * Ben Cumming (@bcumming);
+    * Mikael Simberg (@msimberg);
+    * and Rocco Meli (@RMeli).
+
+    We are volunteers for this role, who care about the quality of CSCS documentation!
+
+!!! tip "Before contributing"
+    Please read the [guidelines][] and [style guide][] before making any contribution.
+    Consistency and common practices make it easier for users to read and navigate the documentation, make it easier for regular contributors to write, and avoid style debates.
+    We try to strike a balance between following the guidelines and letting authors write in a style that is comfortable for them.
+
+    To speed up the merge process and avoid lengthy style discussions, we reserve the right to make changes to pull requests to bring it into line with the guidelines.
+    The core team will also update pages when they are out of date or when the style guidelines change.
+!!! tip "Before making large contributions"
+    If you plan to make large changes, like adding documentation for a new tool/service or refactoring existing documentation, __reach out to the core team__ before starting.
+
+    This will mean that the changes are consistent with other parts of the documentation, streamline the review process, and to avoid misunderstandings.
+
+### Code owners
+
+Many sections have individual staff that follow them.
+This is codified in the [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS) file in the repository.
+The code owners are notified when there is a change to their pages, and can review the changes.
+
+If you want to follow changes to a page or section, add your name to the CODEOWNERS.
+
+!!! note
+    Review from code owners is not required to merge, however the core team will try to get a timely review from code owners whenever possible.
+
 ## Getting started
 
 We use the GitHub fork and pull request model for development:
@@ -52,18 +97,22 @@ Then navigate to GitHub, and create a pull request.
 
 ## Review process
 
-Documentation is maintained by everybody - so don't be afraid to jump in and make changes or fixes where you see the need or the potential.
+After you have made a pull request, a CI/CD pipeline will run the [spell checker][ref-contributing-spelling] and build a copy of the docs with the PR changes.
+A temporary "TDS" copy of the docs is deployed, to allow reviewers to see the finished documentation, at the address `https://docs.tds.cscs.ch/$PR`, where `PR` is the number of the pull request.
 
-If you plan to make significant changes, please discuss them with an [issue](https://github.com/eth-cscs/cscs-docs/issues) beforehand, to ensure the changes will fit into the larger documentation structure.
+To make changes based on reviewer feedback, make a new commit on your branch, and push it to your fork.
+The PR will automatically be updated, the spell checker will run again, and the TDS documentation site will be rebuilt.
 
-If you think your documentation update could affect specific stakeholders, ping them for a review.
-The same applies if you are not getting get a timely reply for your pull request.
-You can get some hints of whom to contact by looking at [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS).
+!!! tip
+    If you think your documentation update could affect specific stakeholders, ping them for a review.
+    You can get some hints of whom to contact by looking at [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS).
+    If they don't reply in a timely manner, reach out to the core docs team to expedite the process.
 
 !!! note
     To minimise the overhead of the contributing to the documentation and speed up "time-to-published-docs" we do not have a formal review process.
     We will start simple, and add more formality as needed.
 
+[](){#ref-contributing-spelling}
 ### Spell checker
 
 A spell checker workflow runs on all PRs to help catch simple typos.
@@ -173,6 +222,17 @@ Screenshots can help readers follow steps on guides. Think if you need to show t
 
 Often, screenshots can quickly become obsolete, so you may want to complement (or maybe even replace) some with text descriptions.
 
+!!! tip
+    Screen shots take up space in the git repository.
+
+    It might be "only a few hundred kilobytes" for a picture, but over the lifetime of the git repository this adds up to slow down source code cloning and CI/CD pipelines.
+
+!!! tip
+    Avoid using screen shots that do not directly contribute to the documentation.
+
+    For example, showing a screen shot with markers that are used to explain non-trivial steps that a user should follow is good documentation.
+    On the other hand, a screenshot that says "this is a screenshot of the tool" adds no value, and draws the readers attention away from documentation.
+
 #### Diagrams
 
 Diagrams can help readers understand more abstract concepts like processes or architectures. We suggest you use [mermaid](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams). Such format makes diagrams easy to maintain and removes the need to commit image files in the repository.