docs: add how-to guides for users (#2436)

This is largely based on existing documentation for Pathoplexus mostly written by @emmahodcroft and partly by @anna-parker.

Co-authored-by: Emma Hodcroft <emmahodcroft@gmail.com>
Co-authored-by: Anna (Anya) Parker <50943381+anna-parker@users.noreply.github.com>

docs/astro.config.mjs

@@ -25,6 +25,20 @@ export default defineConfig({
                         { label: 'System overview', link: '/introduction/system-overview/' },
                     ],
                 },
+                {
+                    label: 'For users',
+                    items: [
+                        { label: 'Introduction', link: '/for-users/introduction/' },
+                        { label: 'Edit account', link: '/for-users/edit-account/' },
+                        { label: 'Create and manage groups', link: '/for-users/create-manage-groups/' },
+                        { label: 'Submit sequences', link: '/for-users/submit-sequences/' },
+                        { label: 'Revise sequences', link: '/for-users/revise-sequences/' },
+                        { label: 'Revoke sequences', link: '/for-users/revoke-sequences/' },
+                        { label: 'Approve submissions', link: '/for-users/approve-submissions/' },
+                        { label: 'Edit submissions', link: '/for-users/edit-submissions/' },
+                        { label: 'Authenticate via API', link: '/for-users/authenticate-via-api/' },
+                    ],
+                },
                 {
                     label: 'For administrators',
                     items: [

docs/src/components/Team.astro

@@ -40,7 +40,7 @@ const titleRight = titleSide === 'right';
             displayMembers.map((member) => (
                 <ConditionalLink link={member.link}>
                     <div
-                        class={`w-38 group !mt-0 mx-2 flex flex-col items-center text-center ${small ? 'md:w-32' : 'md:w-44'}`}
+                        class={`w-38 group mx-2 !mt-0 flex flex-col items-center text-center ${small ? 'md:w-32' : 'md:w-44'}`}
                     >
                         <img
                             class='rounded-full'

docs/src/content/docs/for-users/approve-submissions.md

@@ -0,0 +1,41 @@
+---
+title: Approve submissions
+---
+
+Once you've uploaded sequences (this applies for new submissions as well as revisions and revocations), you will have to approve them before they are fully submitted.
+
+# Website
+
+After submitting sequences, you'll be taken to a page showing the progress of processing every sequence. For each sequence, it will show whether its awaiting processing, being processed, or has finished processing.
+
+Sequences that have finished processing will show different icons to indicate whether there were any issues during the processing.
+
+-   Green checkmark - indicates that processing was entirely successful
+-   Yellow checkmark - indicates that processing encountered warnings
+-   Red label - indicates that there were errors during processing
+
+We highly recommend checking all sequences with warnings to see if they could be rectified or indicate a larger problem with the data.
+
+You can only approve and release sequences that have yellow or green checkmarks (no warnings or errors, or only errors) - you cannot approve and release sequences with errors.
+
+You can filter the processed sequences to only show those with warnings, errors, or which passed, to help you decide which actions to take.
+
+If you see something you'd like to change, or want to try and resolve a warning, you can [edit the sequence](../edit-submissions).
+
+### Actioning individual sequences
+
+For each sequence, you have 3 options (2 if the sequence has an error), indicated to the right: release (paper plane), edit (pencil and paper), and discard (waste bin). Clicking on any of these icons for one sequence, will execute the action on that sequence only. When you release or discard a sequence, it will no longer be shown on the page.
+
+### Actioning sequences in bulk
+
+You can also take action on multiple sequences at once, using the buttons above the displayed sequences.
+
+Discarding: You can choose to discard either all sequences, or those with errors. If you discard all sequences, you will need to start the submission process over.
+
+Releasing: You can release all valid sequences (those without warnings or errors, and those with warnings), leaving only those with errors.
+
+If you leave any sequences unreleased, you can view, edit, and release (if they have no errors) them at a later time.
+
+# API
+
+_Instructions coming soon_

docs/src/content/docs/for-users/authenticate-via-api.md

@@ -0,0 +1,18 @@
+---
+title: Authenticate via API
+---
+
+Some Loculus endpoints require authentication in order to use them. In order to use these endpoints you need to get a JSON web token.
+
+First, you need determine the URL to the [KeyClock](../../introduction/glossary/#keycloak) server and you can find it if you go to the Sign In page or [edit your account](../edit-account/). Given the URL, you can get the token with the following cURL call:
+
+```bash
+KEYCLOAK_TOKEN_URL="https://<Your_Keycloak_URL>/realms/loculus/protocol/openid-connect/token"
+USERNAME_LOCULUS="YOUR_USERNAME"
+PASSWORD_LOCULUS="YOUR_PASSWORD"
+
+jwt_keycloak=$(curl -X POST "$KEYCLOAK_TOKEN_URL" --fail-with-body -H 'Content-Type: application/x-www-form-urlencoded' -d "username=$USERNAME_LOCULUS&password=$PASSWORD_LOCULUS&grant_type=password&client_id=backend-client")
+echo "$jwt_keycloak"
+```
+
+This will print the JSON web token. The access token is in the field `access_token`.

docs/src/content/docs/for-users/create-manage-groups.md

@@ -0,0 +1,30 @@
+---
+title: Creating and managing groups
+---
+
+If your organization does not yet have a [submitting group](../../introduction/glossary/#submitting-group), you can create one. If they already have a group, you can contact someone within that group, and ask them to add you using your username. Everyone within a group is able to submit, edit, and revoke sequences uploaded by anyone else in that group.
+
+## Create a new group
+
+1. Log into your account and enter your account page by clicking 'My account' in the top-right corner of the webpage
+2. Click 'Create Group'
+3. Fill in the required information about your group
+4. Click 'Submit' to create your group
+
+## Add or remove a user
+
+Users cannot add themselves to groups; they must ask someone within a group to add them.
+
+To add a user to your group:
+
+1. Log into your account and navigate to your account page ('My account' in the top-right of the website)
+2. Within your groups, select the name of the group that you'd like to add a user to
+3. Using the 'user' interface at the bottom of the page, type in the username of the person you want to add
+4. The user is now part of your group
+
+To remove a user:
+
+1. Log into your account and navigate to your account page ('My account' in the top-right of the website)
+2. Within your groups, select the name of the group that you'd like to remove a user from
+3. Using the 'user' interface at the bottom of the page, click the red button next to the user you wish to remove
+4. The user is now removed

docs/src/content/docs/for-users/edit-account.md

@@ -0,0 +1,11 @@
+---
+title: 'Edit account'
+---
+
+You can edit your account to update your information anytime. Once logged in, you can click on 'My account' in the top-right of the webpage
+
+1. Click 'Edit account information'
+2. This will redirect you to [KeyClock](../../introduction/glossary/#keycloak), a secure program that handles our account security
+3. From here, you can edit your personal information, such as username, email and name.
+4. Be sure to save any changes after you make them.
+5. You can also explore your login options such as 2-factor authentication, and see where else you're logged in and what other accounts are linked

docs/src/content/docs/for-users/edit-submissions.md

@@ -0,0 +1,19 @@
+---
+title: Edit submissions
+---
+
+After [uploading sequences](../submit-sequences/) and while [approving them](../approve-submissions/), you may see something you'd like to edit, or fix a warning. You can do this by editing the sequence before releasing it.
+
+## Website
+
+After your submitted sequences have processed and are visible on the review page (with "Current Submissions" displayed to the top-left), you can edit any sequence by clicking the 'edit' button (pencil and paper) to the right of the sequence.
+
+This will take you to a new page where you can edit all the fields you uploaded, or add one that is missing. You can also edit the unaligned sequence.
+
+After making any edits you wish, press the 'Submit' button at the top-left, and confirm the submission. The sequence will go back to processing, and display on the page again when processing is complete. If the status of having a warning or error has changed, a new status symbol will be shown to the left of the sequence.
+
+You can then proceed to [approving sequences](../approve-submissions/).
+
+## API
+
+_Instructions coming soon_

docs/src/content/docs/for-users/introduction.md

@@ -0,0 +1,5 @@
+---
+title: Introduction
+---
+
+This section of the documentation is intended for users of a Loculus instance. If you are reading this page on https://loculus.org, you are viewing the documentation for the latest version of Loculus. Since different instances have different configurations and varying degrees of customization, and some instances might be running older versions, certain features may not be available or behave differently. There might be a specific documentation for the instance that you are using.

docs/src/content/docs/for-users/revise-sequences.md

@@ -0,0 +1,27 @@
+---
+title: Revise sequences
+---
+
+Sequences can be corrected or updated after they have been submitted to Loculus. Submitting these changes ("revisions") will cause the [version](../../introduction/glossary/#version) of the sequence to be incremented, and previous versions of the metadata and sequence data can always be accessed via previous version numbers.
+
+The process of submitting revisions is very similar to original submission. The main difference is that you must provide an `accession` column in the metadata file, which contains the Loculus [accession number(s)](../../introduction/glossary/#accession) assigned when the sequences were submitted originally.
+
+## Preparing the metadata file
+
+The metadata file should include all the metadata fields that were originally included, **both** those that you wish to update and that should remain the same. (Not including a metadata column will set its value to 'empty'.)
+
+The metadata file should only have rows of data for the sequences in the FASTA file. It needs to include an `accession` column, which includes the Loculus accessions assigned at initial submission. You should also include the `submissionId` column, which will match the sequence names in your FASTA file.
+
+## Preparing the FASTA file
+
+Create a FASTA file that contains only the sequences you'd like to revise, with whatever changes you'd like to make. There is no reason to edit the sequence names in the FASTA file, as long as they still match those in your metadata file.
+
+Even if you are not revising the sequence, you must provide a FASTA file that matches the metadata file you are uploading. It should only contain the sequences that are in the metadata file (if this is fewer than your original submission), and does not otherwise need to be edited.
+
+## Submitting the revision
+
+To submit a revision, navigate to the `Submit` section of the Loculus website using the link in the top-right corner of the website. Select the correct organism if requested, or ensure you're submitting to the correct organism database via the drop-down on the top-left of the website.
+
+Just as with an original submission, drag and drop (or select) the files where you have made the appropriate revisions. Press 'Submit'.
+
+You will be directed to the same processing page as you're taken to during initial submission, where you can view the sequences and their changes before releasing them. Once released, these changes will appear in the database after a few minutes, with the version numbers incremented.

docs/src/content/docs/for-users/revoke-sequences.md

@@ -0,0 +1,20 @@
+---
+title: Revoke sequences
+---
+
+Sequences can be revoked if they contain errors that cannot be corrected.
+
+Note that revoking a sequence **does not delete it**. While it will not turn up in default searches, and will be clearly marked as revoked, it will still be publicly visible.
+
+## How to revoke a sequence
+
+Revocation can only be done by members of the group that originally submitted that sequence.
+
+-   Find the sequence you would like to revoke via searching the main database, or by viewing your submitted sequences.
+    (Go to 'Submit' and 'View sequences').
+-   Scroll to the bottom of the sequence page and find the 'Revoke this sequence' button in the bottom-left corner.
+-   Confirm you want to revoke the sequence
+-   You will be taken to the sequence review page - press 'Release' to release the revoked sequence
+-   Confirm you want to release the sequence
+
+The sequence is now revoked.

docs/src/content/docs/for-users/submit-sequences.md

@@ -0,0 +1,34 @@
+---
+title: Submit sequences
+---
+
+You can only upload sequences if you already have an account and [are part of a submitting group](../create-manage-groups/).
+
+Before you begin this process, you should ensure your data is in the correct format. Each sequence should have a unique submissionID that can be used to associate it with its corresponding metadata entry.
+
+Loculus expects:
+
+-   Sequence data in `fasta` format with a unique submissionID per sequence.
+-   Metadata in `tsv` format for each sequence.If you need help formatting metadata, there is a metadata template for each organism on the submission page.
+
+![Metadata template.](../../../assets/MetadataTemplate.png)
+
+## Multi-segmented Pathogens
+
+Loculus expects multi-segmented pathogens to have one unique submissionID per **isolate** (pathogen sample containing all segments). However, `fasta` files should still have a separate entry/record per segment. Therefore, each record id should include the unique submissionID of the isolate and the segment name, for example: `submissionID + '_' + segmentName`. The metadata is uploaded per isolate, i.e. there will be only one row for each `submissionID` and segmented metadata parameters need to be uploaded individually, i.e. under `length_{segmentName}` etc.
+
+## Website
+
+Uploading sequences via the website is a easy way to submit sequences without having to worry about any code.
+
+1. Log into your account, and then click 'Submit' in the top-right corner of the website
+2. Select the organism that you'd like to submit sequences for
+3. Drag-and-drop a `fasta` file with the sequences and a metadata file with the associated metadata into the box on the website, or click the 'Upload a file' link within the boxes to open a file-selection box
+4. Select the Terms of Use that you would like for your data
+5. Select 'Submit sequences' at the bottom of the page
+
+The data will now be processed, and you will have to approve your submission before it is finalized. You can see how to do this [here](../approve-submissions/).
+
+## API
+
+_Instructions coming soon_