docs: add user guide (#26)

* chore: update .gitignore for mdbook docs

* docs: add user guide

* chore: add workflow to deploy user guide

* docs: fix extraneous blank line

Author: Athemis

.github/workflows/mdbook.yml

@@ -0,0 +1,55 @@
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install mdBook
+        run: |
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: mdbook build docs/user-guide
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/user-guide/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -26,6 +26,9 @@
 # Debug artifacts
 *.dSYM/
 
+# mdBook build output
+docs/user-guide/book/
+
 # profiling data
 *.profraw
 *.profdata

docs/user-guide/book.toml

@@ -0,0 +1,8 @@
+[book]
+title = "ELNPack User Guide"
+authors = ["ELNPack Team"]
+language = "en"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "ayu"

docs/user-guide/src/SUMMARY.md

@@ -0,0 +1,12 @@
+# Table of Contents
+
+- [Introduction](./introduction.md)
+- [Install & Launch](./installation.md)
+- [Quick Workflow](./quickstart.md)
+- [UI Overview](./overview.md)
+  - [Markdown Editor](./markdown.md)
+  - [Attachments](./attachments.md)
+  - [Keywords](./keywords.md)
+  - [Metadata](./metadata.md)
+  - [Date & Time Picker](./datetime.md)
+  - [Saving ELN Archives](./saving.md)

docs/user-guide/src/attachments.md

@@ -0,0 +1,17 @@
+# Attachments
+
+![File Attachment](images/ui-file-attachments.webp)
+
+1. Click **Add files** to open the file picker. Select all files you want to attach.
+2. A thumbnail will be shown for each file if possible.
+3. Use the **Edit** button to rename files directly from the list.
+4. If a file has been automatically renamed, this will be indicated by a warning icon. Hover the icon to see the original name.
+5. To delete files, click the **Delete** button next to each file.
+6. Beneath the filename, **additional information** such as file size, MIME type and SHA256 hash are displayed.
+
+> [!TIP]
+> Files are hashed twice: first when adding an attachment, and again when saving
+> the ELN archive. If the hashes do not match, an error message is shown.
+>
+> This helps ensure that files are not modified in between and that the file
+> saved in the archive is identical to the one you attached.

docs/user-guide/src/datetime.md

@@ -0,0 +1,11 @@
+# Date & Time Picker
+
+![Date & Time Picker](./images/ui-datetime-picker.webp)
+
+- Pick the calendar date and clock time of the experiment.
+- You can click on the **Now** button to use the current date and time.
+- The chosen value is stored in the archive metadata.
+- During a later ELN import, this exact timestamp is used as creation date.
+
+> [!TIP]
+> Backfill older experiments by setting the original date and time.