diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 573e2f0c..9061708d 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,14 +1,21 @@ version: 2 updates: -- package-ecosystem: npm - directory: "/" - schedule: - interval: daily - time: '20:00' - open-pull-requests-limit: 10 -- package-ecosystem: bundler - directory: "/" - schedule: - interval: daily - time: '20:00' - open-pull-requests-limit: 10 + # The bundler ecosystem was dropped with the Hugo site; there is no Gemfile. + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + groups: + # astro and its integrations have to move together. + astro: + patterns: + - "astro" + - "@astrojs/*" + + # Workflow actions are pinned by SHA, so without this they never get updates. + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 1438a53f..4e033dbb 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -11,6 +11,8 @@ jobs: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + with: + fetch-depth: 0 # lastUpdated reads commit dates - name: Setup Node uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db177d4a..182c7f55 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,60 @@ -# How to Contribute +# Contributing -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. +This repository holds the documentation for [UQ XNAT](https://docs.xnat.rcc.uq.edu.au), +operated by the Research Computing Centre at The University of Queensland. -## Contributor License Agreement +Corrections are welcome from anyone who uses the service. If a screenshot is out +of date or a step no longer matches what XNAT does, that is worth reporting even +if you do not fix it yourself. -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. +## Quickest way to fix a page -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. +Every page has an **Edit page** link at the bottom. It opens the file in the +GitHub web editor, where you can make a change and open a pull request without +cloning anything. -## Code reviews +## Working locally -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. +```sh +npm install +npm run dev # http://localhost:4321 +npm run build # production build, run this before opening a PR +``` -## Community Guidelines +Content lives in `src/content/docs/`, one directory per section. Screenshots sit +beside the page that uses them. The sidebar and the URL redirects are both in +`astro.config.mjs`. -This project follows -[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). +## Writing conventions + +- **Australian English** — anonymise, organisation, de-identified. +- **Second person, imperative.** "Select **Upload**", not "we can select Upload". +- **Every page needs `title` and `description` frontmatter.** The description is + the meta description, the social card text and the search result snippet, so + make it a real sentence rather than a repeat of the title. +- **Sentence case for headings**, and at least two `##` headings per page so the + table of contents has something to show. Do not open a page at `###`. +- **Quote the interface exactly.** If XNAT's button says **Begin Upload**, write + that, in bold, with the same capitalisation. +- Prefer `` for ordered procedures, `` for mutually exclusive + paths, and plain prose for explanation. + +## Screenshots + +- **Never include real patient data, or anything that could identify a + participant.** Use a demo project with synthetic data. This is a public + repository and its history cannot be quietly rewritten. +- Colocate images with the page that references them. +- Write alt text describing what to look for, not what the page is. + +## Renaming and moving pages + +A page's URL comes from its filename, so renaming a file changes its URL. The +site carries around 60 redirects for URLs that already exist in the wild +(`astro.config.mjs`). If you move or rename a page, add a redirect from the old +path and check the build still passes. + +## Review + +Pull requests are reviewed by RCC. For anything about the service itself rather +than the documentation, contact `rcc-support@uq.edu.au`. diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 00000000..4c98e094 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,73 @@ +# Docs review queue + +Questions that can't be answered from the codebase, the screenshots or public +XNAT documentation. Grouped by what they block. + +## Blocks launch + +- [ ] **De-identification obligations.** Who is responsible for de-identifying + before upload? What ethics approval is presupposed? What must a user do if + identifiable data reaches the archive, and will RCC purge it? + Currently the only statement of this anywhere is a `:::note` inside step 1 + of `uploading-data/web-upload.mdx`. +- [ ] **Site anonymiser coverage.** `anonymising-data/site-anonymiser.md` says + HIRF and CAI data is anonymised on-site. `getting-started` names HIRF, CAI + **and TRI**. Which is right, and is the DICOM tag table current? This is a + privacy claim, so it needs to be exact. + +## Blocks new pages + +- [ ] **Data residency and lifecycle.** Where do the bytes actually live? Does + deleting in XNAT delete in UQ-RDM? What happens at project end? Backups? +- [x] **Who can create a project.** Answered: UQ users can request their own. + Non-UQ AAF users and non-AAF users cannot; their projects are created by + the facility or they are granted access by a project lead. Non-AAF users + additionally need an AAF VHO account first. Captured in + `using-xnat/projects/your-project.mdx`. +- [ ] **Facility project creation.** Projects for HIRF, CAI and TRI data are + sometimes created automatically and sometimes not. What determines it? + The Facility data tab currently tells users to check their project list + and contact the facility if it is missing, which avoids the question but + does not answer it. +- [ ] **Automated facility uploads.** With CTP retired, what sends imaging data + from HIRF, CAI and TRI scanners to XNAT, and who operates it? How long + does it normally take, does the data land in the project directly or wait + in the prearchive, and how long should a user wait before chasing it — + with the facility or with RCC support? Blocks + `uploading-data/facility-uploads.md`, currently `draft: true`. +- [ ] **Which instance for which user.** `xnat.rcc` vs `opex.xnat` vs + `irc5.xnat`. The homepage flags the latter two as UQ network or VPN only, + and `partials/sign-in-aaf.mdx` already hedges with "if you have been + provided with a project specific XNAT link, use that one instead" — + that hedge exists because the rule was never written down. +- [ ] **Support routing.** When is it `rcc-support@uq.edu.au` vs + `HIRFAdministration@health.qld.gov.au`? Business hours? Escalation path? + The "~24 hours" turnaround appears on two pages with no source. + +## Corrections to existing pages + +- [ ] **XNAT version in production.** Determines whether the quoted UI strings + are right. +- [ ] **"Simply downloaded archive structure"** — quoted on the downloading page. + Is the real checkbox label "Simplify downloaded archive structure"? Left + verbatim rather than silently corrected. +- [ ] **Alias token expiry.** `alias-tokens.md` says 60 days. This is + site-configurable in XNAT — confirm for this instance. +- [ ] **Storage quota.** "1TB storage and 1 million files" — current? Per + project or per user? What does a user see when they hit it? +- [ ] **Feature availability.** The Actions menu in `using-xnat/subjects.png` + shows XSync, Pipelines and Event Service. None are documented. Are they + generally available, restricted, or disabled? +- [ ] **AAF Keycloak login error.** There is an unused screenshot at + `logging-into-xnat/ais-keycloak-login-error.png` showing "Unexpected error + when authenticating with identity provider". What is the fix? Someone hit + this and never wrote it up. +- [ ] **FAQ content.** `user-guides/faq.md` is an honest placeholder. Real + questions from the ticket queue would be better than invented ones. + +## Drafted content awaiting sign-off + +Pages drafted from screenshots and public XNAT docs are marked either +`draft: true` (excluded from production builds) or with a review banner and a +sidebar badge. Nothing drafted should be published without a pass from someone +who runs the service. diff --git a/astro.config.mjs b/astro.config.mjs index 08f4f2e8..9026bab0 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -2,6 +2,8 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; +const SITE = 'https://docs.xnat.rcc.uq.edu.au'; + // Every content page's slug (used to redirect the old Hugo `/docs/...` URLs). const slugs = [ 'user-guides', @@ -17,9 +19,6 @@ const slugs = [ 'user-guides/using-xnat/search', 'user-guides/managing-data', 'user-guides/managing-data/downloading-data', - 'user-guides/managing-data/downloading-data/zip-download', - 'user-guides/managing-data/downloading-data/desktop-client', - 'user-guides/managing-data/downloading-data/download-scan', 'user-guides/managing-data/viewing-images', 'user-guides/managing-data/uploading-data', 'user-guides/managing-data/uploading-data/web-upload', @@ -32,10 +31,6 @@ const slugs = [ 'user-guides/processing-data', 'user-guides/processing-data/command-line-tools', 'user-guides/processing-data/interactive-analysis', - 'facility-guides', - 'facility-guides/ctp', - 'facility-guides/ctp/installation', - 'facility-guides/ctp/proxy-server', ]; // Old Hugo `/docs/` -> new `/`, plus the legacy Hugo aliases. @@ -47,16 +42,16 @@ const redirects = { // every old per-member URL (both the Astro and original Hugo `/docs/` forms) // and the legacy Hugo aliases to the matching tab. '/user-guides/getting-started/uq-members': - '/user-guides/getting-started/?member=uq-members', + '/user-guides/getting-started/?member=aaf-members', '/user-guides/getting-started/other-aaf-members': - '/user-guides/getting-started/?member=other-aaf-members', + '/user-guides/getting-started/?member=aaf-members', '/user-guides/getting-started/non-aaf-members': '/user-guides/getting-started/?member=non-aaf-members', '/user-guides/getting-started/hirf-users': '/user-guides/getting-started/', '/docs/user-guides/getting-started/uq-members': - '/user-guides/getting-started/?member=uq-members', + '/user-guides/getting-started/?member=aaf-members', '/docs/user-guides/getting-started/other-aaf-members': - '/user-guides/getting-started/?member=other-aaf-members', + '/user-guides/getting-started/?member=aaf-members', '/docs/user-guides/getting-started/non-aaf-members': '/user-guides/getting-started/?member=non-aaf-members', '/docs/user-guides/getting-started/hirf-users': '/user-guides/getting-started/', @@ -77,18 +72,48 @@ const redirects = { '/docs/user-guides/using-xnat/sessions/scans': '/user-guides/using-xnat/sessions/#viewing-scans', - // CTP Windows/Linux service pages merged into one OS-tabbed page. - '/facility-guides/ctp/windows-service': '/facility-guides/ctp/run-as-service', - '/facility-guides/ctp/linux-service': '/facility-guides/ctp/run-as-service', - '/docs/facility-guides/ctp/windows-service': '/facility-guides/ctp/run-as-service', - '/docs/facility-guides/ctp/linux-service': '/facility-guides/ctp/run-as-service', + // The three download method pages merged into one tabbed page. The ?method= + // values are the tab labels slugified by TabQueryLink; they must match the + // labels in downloading-data/index.mdx. + '/user-guides/managing-data/downloading-data/zip-download': + '/user-guides/managing-data/downloading-data/?method=zip-download', + '/user-guides/managing-data/downloading-data/desktop-client': + '/user-guides/managing-data/downloading-data/?method=desktop-client', + '/user-guides/managing-data/downloading-data/download-scan': + '/user-guides/managing-data/downloading-data/?method=individual-scans', + '/docs/user-guides/managing-data/downloading-data/zip-download': + '/user-guides/managing-data/downloading-data/?method=zip-download', + '/docs/user-guides/managing-data/downloading-data/desktop-client': + '/user-guides/managing-data/downloading-data/?method=desktop-client', + '/docs/user-guides/managing-data/downloading-data/download-scan': + '/user-guides/managing-data/downloading-data/?method=individual-scans', + + // CTP was retired; its pages are gone. Send the old URLs to the remaining + // upload methods rather than 404. + '/facility-guides': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp/installation': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp/proxy-server': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp/run-as-service': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp/windows-service': '/user-guides/managing-data/uploading-data', + '/facility-guides/ctp/linux-service': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp/installation': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp/proxy-server': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp/run-as-service': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp/windows-service': '/user-guides/managing-data/uploading-data', + '/docs/facility-guides/ctp/linux-service': '/user-guides/managing-data/uploading-data', // Legacy aliases declared in the original Hugo front matter. - '/docs/user-guides/create-xnat-project': '/user-guides/getting-started', + // Project creation now has its own page; these legacy URLs were always about + // creating a project rather than onboarding. + '/docs/user-guides/create-xnat-project': + '/user-guides/using-xnat/projects/your-project', '/docs/user-guides/create-xnat-project/create-q-collection-uq-users': - '/user-guides/getting-started/?member=uq-members', + '/user-guides/using-xnat/projects/your-project', '/docs/user-guides/create-xnat-project/create-q-collection-non-uq-users': - '/user-guides/getting-started/?member=other-aaf-members', + '/user-guides/using-xnat/projects/your-project', '/docs/user-guides/browsing-xnat': '/user-guides/using-xnat', '/docs/user-guides/login-to-xnat': '/user-guides/logging-into-xnat', '/docs/user-guides/login-to-xnat/aaf-login': '/user-guides/logging-into-xnat/', @@ -96,105 +121,147 @@ const redirects = { // https://astro.build/config export default defineConfig({ - site: 'https://docs.xnat.rcc.uq.edu.au', + site: SITE, redirects, integrations: [ starlight({ title: 'UQ XNAT', description: 'Storing, managing and analysing de-identified imaging data for UQ projects and collaborators', - customCss: ['./src/styles/custom.css'], + customCss: [ + './src/styles/tokens.css', + './src/styles/base.css', + './src/styles/components.css', + ], tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }, + editLink: { baseUrl: 'https://github.com/UQ-RCC/xnat/edit/main/' }, + // Reads git commit times, so CI needs full history (fetch-depth: 0). + lastUpdated: true, + favicon: '/favicon.svg', + head: [ + // Starlight sets twitter:card=summary_large_image but emits no + // og:image. Scrapers will not resolve a relative image URL. + { tag: 'meta', attrs: { property: 'og:image', content: `${SITE}/og-default.png` } }, + { tag: 'meta', attrs: { property: 'og:image:width', content: '1200' } }, + { tag: 'meta', attrs: { property: 'og:image:height', content: '630' } }, + { + tag: 'meta', + attrs: { + property: 'og:image:alt', + content: 'UQ XNAT - imaging data documentation', + }, + }, + { tag: 'meta', attrs: { name: 'twitter:image', content: `${SITE}/og-default.png` } }, + { + tag: 'link', + attrs: { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' }, + }, + { tag: 'meta', attrs: { name: 'theme-color', content: '#51247A' } }, + ], components: { // Replace the header's social-icons slot with our top-nav links. SocialIcons: './src/components/NavLinks.astro', // Cycling theme toggle (auto → light → dark) instead of the dropdown. ThemeSelect: './src/components/ThemeSelect.astro', }, + // Single axis: every group is a task, ordered the way a new user meets + // them. Labels are free to change; slugs are not, since the legacy + // redirects point at them. sidebar: [ { - label: 'User Guides', + label: 'Getting started', items: [ - // FAQ hidden from the sidebar until it has real content. - // The page still exists at /user-guides/faq (kept for old redirects). - // Getting Started is now a single tabbed page (member type via tabs). - { label: 'Getting Started', slug: 'user-guides/getting-started' }, - // Logging into XNAT is now a single page (AAF + RCC Authenticate tabs). - { label: 'Logging into XNAT', slug: 'user-guides/logging-into-xnat' }, + // Tabbed by member type; covers requesting a project and an account. + { label: 'Signing up', slug: 'user-guides/getting-started' }, + { label: 'Logging in', slug: 'user-guides/logging-into-xnat' }, { - label: 'Using XNAT', - items: [ - { label: 'Overview', slug: 'user-guides/using-xnat' }, - { - label: 'Projects', - items: [ - { label: 'Overview', slug: 'user-guides/using-xnat/projects' }, - { label: 'Granting Access', slug: 'user-guides/using-xnat/projects/granting-access' }, - { label: 'Request Storage', slug: 'user-guides/using-xnat/projects/request-storage' }, - ], - }, - { label: 'Subjects', slug: 'user-guides/using-xnat/subjects' }, - { label: 'Sessions', slug: 'user-guides/using-xnat/sessions' }, - { label: 'Search', slug: 'user-guides/using-xnat/search' }, - ], + label: 'Your project', + slug: 'user-guides/using-xnat/projects/your-project', + }, + ], + }, + { + label: 'Uploading and downloading', + items: [ + { + label: 'Overview', + slug: 'user-guides/managing-data/uploading-data', + }, + { + label: 'Upload from the browser', + slug: 'user-guides/managing-data/uploading-data/web-upload', + }, + { + label: 'Fixing stuck uploads', + slug: 'user-guides/managing-data/uploading-data/prearchive', + }, + { + label: 'Custom upload forms', + slug: 'user-guides/managing-data/uploading-data/resource-uploader', + }, + { label: 'Downloading data', slug: 'user-guides/managing-data/downloading-data' }, + { + label: 'Syncing between XNATs', + slug: 'user-guides/managing-data/syncing-data', }, + ], + }, + { + label: 'Browsing and organising', + items: [ + { label: 'Overview', slug: 'user-guides/using-xnat' }, { - label: 'Managing Data', + label: 'Projects', items: [ + { label: 'Overview', slug: 'user-guides/using-xnat/projects' }, { - label: 'Downloading Data', - items: [ - { label: 'Overview', slug: 'user-guides/managing-data/downloading-data' }, - { label: 'Zip Download', slug: 'user-guides/managing-data/downloading-data/zip-download' }, - { label: 'Desktop client', slug: 'user-guides/managing-data/downloading-data/desktop-client' }, - { label: 'Download Scan', slug: 'user-guides/managing-data/downloading-data/download-scan' }, - ], - }, - { label: 'Viewing Images', slug: 'user-guides/managing-data/viewing-images' }, - { - label: 'Uploading Data', - items: [ - { label: 'Overview', slug: 'user-guides/managing-data/uploading-data' }, - { label: 'Web Upload', slug: 'user-guides/managing-data/uploading-data/web-upload' }, - { label: 'Resource uploader', slug: 'user-guides/managing-data/uploading-data/resource-uploader' }, - { label: 'Prearchive', slug: 'user-guides/managing-data/uploading-data/prearchive' }, - ], + label: 'Granting access', + slug: 'user-guides/using-xnat/projects/granting-access', }, - { label: 'Syncing Data', slug: 'user-guides/managing-data/syncing-data' }, { - label: 'Anonymising Data', - items: [ - { label: 'Overview', slug: 'user-guides/managing-data/anonymising-data' }, - { label: 'Project anonymiser', slug: 'user-guides/managing-data/anonymising-data/project-anonymiser' }, - { label: 'Site anonymiser', slug: 'user-guides/managing-data/anonymising-data/site-anonymiser' }, - ], + label: 'Requesting more storage', + slug: 'user-guides/using-xnat/projects/request-storage', }, ], }, + { label: 'Subjects', slug: 'user-guides/using-xnat/subjects' }, + { label: 'Sessions and scans', slug: 'user-guides/using-xnat/sessions' }, + { label: 'Viewing images', slug: 'user-guides/managing-data/viewing-images' }, + { label: 'Search', slug: 'user-guides/using-xnat/search' }, + ], + }, + { + label: 'Anonymising data', + items: [ + { label: 'Overview', slug: 'user-guides/managing-data/anonymising-data' }, { - label: 'Processing Data', - items: [ - { label: 'Alias tokens', slug: 'user-guides/processing-data/alias-tokens' }, - { label: 'Command line tools', slug: 'user-guides/processing-data/command-line-tools' }, - { label: 'Interactive Analysis', slug: 'user-guides/processing-data/interactive-analysis' }, - ], + label: 'On-site anonymisation', + slug: 'user-guides/managing-data/anonymising-data/site-anonymiser', + }, + { + label: 'Project anonymiser', + slug: 'user-guides/managing-data/anonymising-data/project-anonymiser', }, ], }, { - label: 'Facility Guides', + // Plugins layered on top of XNAT, rather than core platform features. + label: 'Analysis and pipelines', items: [ { - label: 'Clinical Trials Processor (CTP)', - items: [ - { label: 'Overview', slug: 'facility-guides/ctp' }, - { label: 'Installation', slug: 'facility-guides/ctp/installation' }, - { label: 'Run CTP as a service', slug: 'facility-guides/ctp/run-as-service' }, - { label: 'Proxy Server Settings', slug: 'facility-guides/ctp/proxy-server' }, - ], + label: 'Jupyter environment', + slug: 'user-guides/processing-data/interactive-analysis', }, ], }, + { + label: 'Command line access', + items: [ + { label: 'Overview', slug: 'user-guides/processing-data' }, + { label: 'Alias tokens', slug: 'user-guides/processing-data/alias-tokens' }, + { label: 'Command line tools', slug: 'user-guides/processing-data/command-line-tools' }, + ], + }, ], }), ], diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 56265331..00000000 --- a/netlify.toml +++ /dev/null @@ -1,6 +0,0 @@ -[build] -command = "npm run build" -publish = "dist" - -[build.environment] -NODE_VERSION = "22" diff --git a/public/apple-touch-icon.png b/public/apple-touch-icon.png new file mode 100644 index 00000000..bb505508 Binary files /dev/null and b/public/apple-touch-icon.png differ diff --git a/public/favicon.svg b/public/favicon.svg new file mode 100644 index 00000000..ba8b7077 --- /dev/null +++ b/public/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/public/icon-192.png b/public/icon-192.png new file mode 100644 index 00000000..5fe9e197 Binary files /dev/null and b/public/icon-192.png differ diff --git a/public/icon-512.png b/public/icon-512.png new file mode 100644 index 00000000..c8562b32 Binary files /dev/null and b/public/icon-512.png differ diff --git a/public/og-default.png b/public/og-default.png new file mode 100644 index 00000000..c4936027 Binary files /dev/null and b/public/og-default.png differ diff --git a/scripts/branding/icon-square.svg b/scripts/branding/icon-square.svg new file mode 100644 index 00000000..4a266a99 --- /dev/null +++ b/scripts/branding/icon-square.svg @@ -0,0 +1,7 @@ + + + + + + diff --git a/scripts/branding/og-card.svg b/scripts/branding/og-card.svg new file mode 100644 index 00000000..19c41e5d --- /dev/null +++ b/scripts/branding/og-card.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + UQ XNAT + + Imaging data documentation + + + + Research Computing Centre · The University of Queensland + National Imaging Facility · Australian Imaging Service + diff --git a/scripts/generate-icons.mjs b/scripts/generate-icons.mjs new file mode 100644 index 00000000..c2613048 --- /dev/null +++ b/scripts/generate-icons.mjs @@ -0,0 +1,36 @@ +/** + * Rasterises scripts/branding/*.svg into the PNGs served from public/. + * Run manually and commit the output; not part of `npm run build`. + * + * node scripts/generate-icons.mjs + * + * The social card text needs DejaVu Sans (fonts-dejavu-core). + * public/favicon.svg is hand-maintained, not generated here. + */ +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; +import sharp from 'sharp'; + +const root = join(dirname(fileURLToPath(import.meta.url)), '..'); +const branding = join(root, 'scripts', 'branding'); +const out = join(root, 'public'); + +const targets = [ + { src: 'icon-square.svg', file: 'apple-touch-icon.png', size: 180 }, + { src: 'icon-square.svg', file: 'icon-192.png', size: 192 }, + { src: 'icon-square.svg', file: 'icon-512.png', size: 512 }, +]; + +for (const { src, file, size } of targets) { + await sharp(join(branding, src), { density: 384 }) + .resize(size, size) + .png({ compressionLevel: 9 }) + .toFile(join(out, file)); + console.log(`${file} ${size}x${size}`); +} + +await sharp(join(branding, 'og-card.svg'), { density: 96 }) + .resize(1200, 630) + .png({ compressionLevel: 9 }) + .toFile(join(out, 'og-default.png')); +console.log('og-default.png 1200x630'); diff --git a/src/components/ChoiceCards.astro b/src/components/ChoiceCards.astro new file mode 100644 index 00000000..8c848f50 --- /dev/null +++ b/src/components/ChoiceCards.astro @@ -0,0 +1,143 @@ +--- +/** + * Explainer cards that sit above a Starlight block and let the reader + * self-select a path. Each card maps to a tab by its slugified label; clicking + * a card selects that tab. Cards stay in sync however the tab was chosen + * (card, tab bar, or a ?param= deep link via TabQueryLink). + * + * + * ... + */ +interface Option { + /** Must match the exactly. */ + tab: string; + /** Supporting line under the title. */ + who: string; +} + +interface Props { + options: Option[]; + label: string; +} + +const { options, label } = Astro.props; + +const slugify = (s: string) => + s + .trim() + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/(^-|-$)/g, ''); +--- + + + { + options.map((o) => ( + + )) + } + + + + + diff --git a/src/components/EmailAafRequestForm.astro b/src/components/EmailAafRequestForm.astro deleted file mode 100644 index 13676a49..00000000 --- a/src/components/EmailAafRequestForm.astro +++ /dev/null @@ -1,144 +0,0 @@ ---- -// Interactive helper that builds an "AAF account request" email from project, -// organisation and acquisition-site fields, with copy-to-clipboard buttons. -// Ported from the Hugo `email-aaf-request-form` shortcode; styled standalone. -const uid = Math.random().toString(36).slice(2, 9); ---- - -
-
- - -
-
- - -
-
- - -
- - -
- - - - diff --git a/src/components/EmailJupyterRequestForm.astro b/src/components/EmailJupyterRequestForm.astro deleted file mode 100644 index 98d97bad..00000000 --- a/src/components/EmailJupyterRequestForm.astro +++ /dev/null @@ -1,130 +0,0 @@ ---- -// Interactive helper that builds a "request Jupyter environment access" email for -// XNAT project data, with copy-to-clipboard buttons. Ported from the Hugo -// `email-request-form` shortcode; styled standalone (no Bootstrap). -const uid = Math.random().toString(36).slice(2, 9); ---- - -
-
- - -
- - -
- - - - diff --git a/src/components/EmailRequestForm.astro b/src/components/EmailRequestForm.astro deleted file mode 100644 index 67ef3025..00000000 --- a/src/components/EmailRequestForm.astro +++ /dev/null @@ -1,130 +0,0 @@ ---- -// Interactive helper that builds a "request new XNAT project" email from an -// RDM collection name, with copy-to-clipboard buttons. Ported from the Hugo -// `email-request-form` shortcode; styled standalone (no Bootstrap). -const uid = Math.random().toString(36).slice(2, 9); ---- - -
-
- - -
- - -
- - - - diff --git a/src/components/MemberChooser.astro b/src/components/MemberChooser.astro deleted file mode 100644 index 3fefd860..00000000 --- a/src/components/MemberChooser.astro +++ /dev/null @@ -1,117 +0,0 @@ ---- -// Explainer cards that sit above the visible Starlight on Getting -// Started. Each card maps to a tab by its slugified label; clicking a card -// selects that tab (the tab bar stays visible as a second, explicit switcher). -// Cards stay highlighted in sync with the active tab, however it was chosen -// (card click, tab-bar click, or ?member= deep link via TabQueryLink). -const options = [ - { tab: 'UQ members', who: 'UQ staff and students' }, - { - tab: 'Other AAF members', - who: 'QUT, Griffith, CQU, JCU, USQ, USC, Bond, CSIRO, QCIF and other AAF members', - }, - { tab: 'Non-AAF members', who: 'TRI, QIMR, QLD Health, QLD Xray, Pacific Radiology' }, -]; - -const slugify = (s) => - s.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, ''); ---- - -
- { - options.map((o) => ( - - )) - } -
- - - - diff --git a/src/components/RequestEmailForm.astro b/src/components/RequestEmailForm.astro new file mode 100644 index 00000000..9a035d47 --- /dev/null +++ b/src/components/RequestEmailForm.astro @@ -0,0 +1,235 @@ +--- +/** + * Builds a support-request email from a set of fields and copies the parts to + * the clipboard. Nothing is submitted anywhere and no mailto: link is used; + * the user pastes into their own mail client. + * + * `subject` and `body` take {fieldId} placeholders matching a field's id. + * + * + */ +interface Field { + id: string; + label: string; + placeholder?: string; + /** Output stays hidden until every required field is filled. Default true. */ + required?: boolean; +} + +interface Props { + fields: Field[]; + subject: string; + body: string; + to?: string; + intro?: string; +} + +const { fields, subject, body, to = 'rcc-support@uq.edu.au', intro } = Astro.props; + +// Namespaces input ids so several instances can share a page. +const uid = Math.random().toString(36).slice(2, 9); +const config = JSON.stringify({ to, subject, body }); +--- + + + {intro &&

{intro}

} + + { + fields.map((field) => ( +
+ + +
+ )) + } + + + +

+
+ + + + diff --git a/src/content/docs/facility-guides/ctp/close-launcher.png b/src/content/docs/facility-guides/ctp/close-launcher.png deleted file mode 100644 index 3d9e6011..00000000 Binary files a/src/content/docs/facility-guides/ctp/close-launcher.png and /dev/null differ diff --git a/src/content/docs/facility-guides/ctp/index.mdx b/src/content/docs/facility-guides/ctp/index.mdx deleted file mode 100644 index 4ec0536c..00000000 --- a/src/content/docs/facility-guides/ctp/index.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Clinical Trials Processor (CTP) -description: Install, run and configure CTP for sending data to XNAT ---- - -import { CardGrid, LinkCard } from '@astrojs/starlight/components'; - -CTP (Clinical Trials Processor) receives DICOM from a clinical site, anonymises it, and routes it into an XNAT project. - - - - - - diff --git a/src/content/docs/facility-guides/ctp/installation.mdx b/src/content/docs/facility-guides/ctp/installation.mdx deleted file mode 100644 index 967f88c8..00000000 --- a/src/content/docs/facility-guides/ctp/installation.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Installation -description: Installing CTP on Windows 10 ---- - -import { Steps } from '@astrojs/starlight/components'; - -### Installing CTP on Windows 10 - - - -1. Create a new user for CTP on UQ XNAT (not an AAF/OpenID user) with required project access, without admin access - -2. Download the following files - - - [CTP-installer.jar](https://github.com/johnperry/CTP/raw/master/products/CTP-installer.jar) - - [ctp_clinical_site_to_xnat_config.xml](https://github.com/Australian-Imaging-Service/configuration/raw/0c784a9bdd817ee5e0534034a5a108b4a1c6f4aa/CTP/ctp_clinical_site_to_xnat_config.xml) - - [dcmtk-3.6.6-win64-dynamic.zip](https://dicom.offis.de/download/dcmtk/dcmtk366/bin/dcmtk-3.6.6-win64-dynamic.zip) - - [dicom_viewer_Mrbrain.zip](http://www.rubomedical.com/dicom_files/dicom_viewer_Mrbrain.zip) - - Optional if you need more DICOM samples: [sample1.zip](https://download.nrg.wustl.edu/pub/data/sample1.zip) - -3. Install CTP using: - - ``` - cd INSTALL_FOLDER (replace with your actual folder) - java -jar CTP-installer.jar - ``` - -4. Replace CTP/config.xml with ctp_clinical_site_to_xnat_config.xml - -5. Edit CTP/config.xml - - - Change "xxxx.xxxx" in two "url" tags to "xnat.rcc.uq.edu.au" - - Change "xxxx" username and password tags to match new user from step 1 - - If CTP internet access is via a proxy server, add the proxy server element to the Server config - - ```xml - ... - - - - ... - ``` - - Once this element is added proxy server settings can be updated in the CTP Launcher GUI - -6. Add CTP the anonymiser script - - - Copy CTP/scripts/DicomServiceAnonymizer.script to CTP/scripts/dicom-anonymizer-sender.script - - Add the PROJECTID parameter to the list of parameters at the start of the file - - `

my xnat project id

` - - Change the PatientComments element 0010,4000 to set XNAT project routing info - - `@always()@append(){Project:@param(@PROJECTID) Subject:@contents([0010,0010]) Session:@contents([0008,0050])}` - - Review/set other parameters at the start of the file - - PROFILENAME, eg. AIS-Clinical-Site-210604 - - DATEINC, eg. 0 - - PROJECTNAME, SITEID, SITENAME, TRIALNAME, TRIALSPONSOR as required - - Optional: review script to check anonymisation settings are appropriate - -7. Start CTP GUI - - ``` - java -jar Launcher.jar - ``` - -8. Click the CTP "Start" button - -9. Click the "CTP Home Page" button to open the Web UI - - - If the browser can't connect, check CTP is not already running, or try changing the Server port - -10. Login - - - Top RHS banner should show "Welcome admin" - -11. Optional: click "User Manager" to change default usernames/passwords - -12. Optional: click "DICOM Anonymizer" to view/edit anonymiser script - -13. Unzip DCMTK and MrBrain dicom sample - -14. Try sending an dicom to CTP using dcmtk - - ``` - cd dcmtk-3.6.5-win64-dynamic/bin - dcmsend localhost 25055 ../../dicom_viewer_Mrbrain/MRBRAIN.DCM - ``` - -15. Login to the XNAT server with an admin account to view Prearchive - - - Use "Upload" → "Go to prearchive" - - DICOM should appear in "Receiving" status, with project id assigned from step 6 - - Optional: non-admin users need to search by subject/etc - - Use Refresh to check when "Ready" or it disappears from list (as it has been routed to the project) - - Debugging: use dcm2xml from DCMTK to check anonymised dicom file under CTP/roots/FileAfterAnonymization25055 - -16. Logout and login with the new XNAT user from step 1 - -17. Navigate to the project set in step 6 - - - You should see the dicom listed as subject "1737775597" - -18. Use subject "1737775597" → "MR Session" → "View Images" to view the uploaded image - -19. Try a dicom send from the scanner using PC address and port 25055 (check windows firewall settings?) - -20. Enable CTP as a service. Instructions [here](/facility-guides/ctp/run-as-service) - -
- -### Further information -If you need a different commit of CTP-installer -``` -git clone https://github.com/johnperry/CTP -cd CTP/products -git checkout CTP-Installer.jar -``` -If you need other AIS CTP config files -``` -git clone https://github.com/Australian-Imaging-Service/configuration.git -cd configuration/CTP -``` -CTP documentation links: - -[MIRC CTP Wiki](http://mircwiki.rsna.org/index.php?title=MIRC_CTP) - -[CTP DICOM Anonymizer](http://mircwiki.rsna.org/index.php?title=The_CTP_DICOM_Anonymizer) diff --git a/src/content/docs/facility-guides/ctp/proxy-config.png b/src/content/docs/facility-guides/ctp/proxy-config.png deleted file mode 100644 index 2ac64dca..00000000 Binary files a/src/content/docs/facility-guides/ctp/proxy-config.png and /dev/null differ diff --git a/src/content/docs/facility-guides/ctp/proxy-server.mdx b/src/content/docs/facility-guides/ctp/proxy-server.mdx deleted file mode 100644 index f87158ea..00000000 --- a/src/content/docs/facility-guides/ctp/proxy-server.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Proxy Server Settings -description: Updating CTP proxy server settings on Windows ---- - -import { Steps } from '@astrojs/starlight/components'; - -If CTP uses a proxy server for internet access, you can update the CTP proxy server settings on Windows as follows - - - -1. Stop the CTP Windows service - - - If you already have a Services short-cut on the Windows desktop, double-click the short-cut to start Windows Services - - If not, click the Windows start button, start typing "services" and the Services App icon should appear - - Click the Services App icon to start Windows Services - - Locate the CTP service in the list of services, right-click and select **Stop** from the context menu - -2. Start the CTP Launcher - - - If you already have a CTP Launcher short-cut on the Windows desktop, double-click the short-cut to start the CTP Launcher - - If not, locate the CTP service in the list of services again, right-click and select **Properties** from the context menu - 1. Use the **Path to executable** entry to find the installation folder for CTP. It will be in the form `\windows\CTP.exe` - 2. Open a Windows Command prompt window (Start button, type "cmd", click the Command Prompt App icon) - 3. In the Command Prompt window, enter the following commands - - ``` - cd - java -jar Launcher.jar - ``` - -3. Navigate to the CTP Launcher Configuration tab - -4. Use the navigation panel on the left to select **Configuration** -> **Server** -> **ProxyServer** - - ![CTP Launcher proxy configuration](./proxy-config.png) - -5. Update the proxy server settings in the right panel as required. You can set an IP address or host name in the proxyIPAddress field - -6. Select **File** -> **Save** from the main menu bar to save your changes - -7. Close the CTP Launcher using the Window close button at the top right - - :::caution - If the following prompt appears, select **No**. - - ![Close launcher prompt](./close-launcher.png) - - If the CTP is stopped, restart it from the Windows services menu (See below) - ::: - -8. Close the Command Prompt window - -9. Re-Start the CTP Windows service using Windows Services - - Locate the CTP service in the list of services, right-click and select **Start** from the context menu - - ![Start CTP Windows service](./windows-service.png) - - - -#### Troubleshooting -* If the CTP Windows service Stop is disabled, try restarting Windows Services as administrator by right-clicking the icon and selecting **Run as administrator** - -#### Further information - -* [CTP Server Settings](https://mircwiki.rsna.org/index.php?title=MIRC_CTP#Server) diff --git a/src/content/docs/facility-guides/ctp/run-as-service.mdx b/src/content/docs/facility-guides/ctp/run-as-service.mdx deleted file mode 100644 index 04223073..00000000 --- a/src/content/docs/facility-guides/ctp/run-as-service.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Run CTP as a service -description: Enabling CTP as a service on Windows or Linux ---- - -import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; - -Run CTP automatically in the background by installing it as a service. Choose your operating system. - - - - -The CTP install.bat script uses Apache procrun. Use the following steps to enable CTP as a Windows service, including an update to use a JRE other than system default (leave out step 2 if using the system default JRE) - - - -1. Install CTP - - ``` - java -jar CTP-installer.jar - ``` - -2. To use JRE other than system default, edit `/windows/install.bat`. Find the `--Jvm=auto`, add a `--JavaHome` entry and set both as follows - - ``` - --JavaHome=" " ^ - --Jvm="\bin\server\jvm.dll" ^ - ``` - - - `^` is needed to wrap/continue command line in batch file - - The jvm.dll location under `` is the same for JRE 1.7 and 1.8 installs. Confirm this is the case for other JREs/JDKs - -3. Run install.bat as Administrator to create the CTP windows service - - ``` - cd /windows - install - ``` - -4. Open Windows Services as Administrator and start the CTP service - -5. Open CTP administration page in Web browser - -6. Confirm the correct JRE is reported in Admin → System Properties and/or Admin → Log Viewer → ctp.log - - - -#### Troubleshooting -* Installation paths are set in install.bat during CTP install so it won't work if you move the CTP folder somewhere else after install -* If removing the service (with uninstall.bat) leaves the service stuck in delete pending state, reboot the system to complete - -#### Further information - -* [Running CTP as a Windows service](https://mircwiki.rsna.org/index.php?title=Running_CTP_as_a_Windows_Service) -* [Apache procrun](https://commons.apache.org/proper/commons-daemon/procrun.html) - - - - - - -1. Open `./linux/ctpService-ubuntu.sh` and update the following parameters: - - ``` - USER=ubuntu - CTP_HOME=/opt/ctp/CTP - JAVA_BIN=/usr/lib/jvm/java-17-openjdk-amd64/bin - JAVA=$JAVA_BIN/java - CTP_PID=$CTP_HOME/ctp.pid - ``` - -2. Install the ctpService into init.d: - - ``` - sudo ln -s ./linux/ctpService-ubuntu.sh /etc/init.d/ctpService - sudo update-rc.d ctpService defaults 98 02 - ``` - -3. Start and stop CTP using the following commands: - - ``` - sudo service ctpService start - sudo service ctpService stop - ``` - - - - - diff --git a/src/content/docs/facility-guides/ctp/windows-service.png b/src/content/docs/facility-guides/ctp/windows-service.png deleted file mode 100644 index 6a5f2269..00000000 Binary files a/src/content/docs/facility-guides/ctp/windows-service.png and /dev/null differ diff --git a/src/content/docs/facility-guides/index.mdx b/src/content/docs/facility-guides/index.mdx deleted file mode 100644 index 8cdda631..00000000 --- a/src/content/docs/facility-guides/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Facility Guides -description: For Clinical and Imaging facilities ---- - -import { CardGrid, LinkCard } from '@astrojs/starlight/components'; - -Guides for facilities setting up infrastructure to send imaging data to the UQ XNAT. - - - - diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 19e0dd5c..ff7e108a 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,5 +1,5 @@ --- -title: UQ XNAT +title: UQ Imaging Data description: Storing, managing and analysing de-identified imaging data for UQ projects and collaborators template: splash hero: @@ -8,8 +8,8 @@ hero: image: html: 'XNAT' actions: - - text: Documentation - link: /user-guides/getting-started + - text: Browse the guides + link: /user-guides icon: open-book variant: primary - text: Go to XNAT diff --git a/src/content/docs/user-guides/getting-started/index.mdx b/src/content/docs/user-guides/getting-started/index.mdx index 263e148f..82ec3ef7 100644 --- a/src/content/docs/user-guides/getting-started/index.mdx +++ b/src/content/docs/user-guides/getting-started/index.mdx @@ -1,126 +1,117 @@ --- -title: Getting Started -description: Sign up and get started with UQ XNAT — choose your organisation type +title: Signing up +description: Sign up for UQ XNAT with your AAF credentials, or request an AAF Virtual Home account if your organisation is not an AAF member tableOfContents: false --- -import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; -import EmailRequestForm from '@components/EmailRequestForm.astro'; -import EmailAafRequestForm from '@components/EmailAafRequestForm.astro'; +import { Tabs, TabItem, Steps, LinkCard } from '@astrojs/starlight/components'; +import ChoiceCards from '@components/ChoiceCards.astro'; +import RequestEmailForm from '@components/RequestEmailForm.astro'; import SignInAaf from '@partials/sign-in-aaf.mdx'; -import AccessingProject from '@partials/accessing-project.mdx'; import TabQueryLink from '@components/TabQueryLink.astro'; -import MemberChooser from '@components/MemberChooser.astro'; -Choose the option that matches your organisation — your selection is remembered as you move through the docs. - - +Logging in to XNAT uses the Australian Access Federation (AAF). How you start +depends on whether your organisation is an AAF member. + + - - -For UQ staff and students. - -## Signing into XNAT - - - -## Creating an XNAT project - -For UQ users, XNAT uses UQ-RDM HPC collections for storage allocation. For any general questions about UQ-RDM, please refer to the [library guides](https://guides.library.uq.edu.au/for-researchers/uq-research-data-manager). - -:::caution[Note] -Only one member of the project team needs to request for the project -::: - - - -1. Before creating an XNAT project, you'll require a UQ-RDM **HPC Collection** - - - **HPC collections** end with **-Q** and a 4-digit numerical identifier (e.g. PROJ001-**Q0189**) - - **Non-HPC collections** end with **-A** (e.g. PROJ001-**A0189**) or **-I** (PROJ001-**I0189**) - - Open [https://rdm.uq.edu.au/create-record](https://rdm.uq.edu.au/create-record), sign in and fill in the record as per your project details - - ![UQ-RDM create record](./uqrdm-create-record.png) - - :::caution[Important] - For **(6) Data Storage Options**, select the second option (_The project data needs to be mounted on UQ HPC facilities._). Any other option will be incompatible with XNAT, requiring a new RDM request. - ::: - - **REQUEST DATA STORAGE** when complete. You should have an RDM collection name ready (e.g. **PROJ001-Q0189**) - -2. Open a ticket with RCC support. Fill in your RDM collection name below and click to send a pre-filled email. - - - -3. The support ticket will inform you when the project is set up. XNAT project setup typically takes around ~24 hours from ticket submission. - - - - - - + -For users from Australian universities and AAF member organisations (QUT, Griffith, CQU, JCU, USQ, USC, CSIRO and others). Full list of AAF members found [here](https://aaf.edu.au/subscribers). +If your organisation is part of the AAF, you already have everything you need to +log in. The [full list of AAF members](https://aaf.edu.au/subscribers) is on the +AAF site. -## Signing into XNAT +## Logging into XNAT -## Accessing your XNAT project +## Your XNAT project - + -For users from non-AAF organisations (QLD Health, TRI, QIMR, QLD Xray). QCIF/QRIScloud can provide an AAF Virtual Home (VHO) account for login. +If your organisation is not an AAF member, QCIF and QRIScloud can provide an AAF +Virtual Home (VHO) account so you can log in. Request that first. ## Request an AAF VHO account -1. Open a ticket with RCC support to request an AAF account. Fill in your details below and click to send a pre-filled email. +1. Open a ticket with RCC support. Fill in your details below, then copy the + generated email into your mail client. - + -2. AAF's VHO service will return an email regarding the account registration process. +2. AAF's VHO service will email you about the account registration process. -## Signing into XNAT +## Logging into XNAT -1. Open [https://xnat.rcc.uq.edu.au](https://xnat.rcc.uq.edu.au) and log in with the AAF Single sign-on button. +1. Open [https://xnat.rcc.uq.edu.au](https://xnat.rcc.uq.edu.au) and log in with + the AAF Single sign-on button. ![XNAT AAF login page](../logging-into-xnat/xnat-aaf-login-page.png) -2. Select the **AAF Virtual Home** option and login with your AAF VHO credentials. +2. Select the **AAF Virtual Home** option and log in with your VHO credentials. ![AAF Virtual Home login](../logging-into-xnat/aaf-virtual-home-login.png) ![AAF VHO sign-in](../logging-into-xnat/aaf-vho-signin.png) -3. After the AAF sign-in, you should be redirected back to XNAT. There will be **no projects listed** the first time. +3. After the AAF sign-in you are redirected back to XNAT. There will be **no + projects listed** the first time. ![Signed in to XNAT](./xnat-signed-in.png) -## Accessing your XNAT project +## Your XNAT project - + :::note -Data acquired at HIRF, CAI or TRI can be sent to the UQ XNAT repository. If you have multiple valid affiliations, we'd recommend using UQ or AAF where possible. Questions: contact rcc-support@uq.edu.au or HIRFAdministration@health.qld.gov.au +Data acquired at HIRF, CAI or TRI can be sent to the UQ XNAT repository. If you +have multiple valid affiliations, we recommend using UQ or AAF where possible. ::: diff --git a/src/content/docs/user-guides/index.md b/src/content/docs/user-guides/index.md deleted file mode 100644 index 43414195..00000000 --- a/src/content/docs/user-guides/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: User Guides -description: For Researchers and Collaborators ---- diff --git a/src/content/docs/user-guides/index.mdx b/src/content/docs/user-guides/index.mdx new file mode 100644 index 00000000..c4d28215 --- /dev/null +++ b/src/content/docs/user-guides/index.mdx @@ -0,0 +1,41 @@ +--- +title: Guides +description: Find the guide for what you are trying to do in UQ XNAT, from getting access through to running analysis +--- + +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +Find what you are trying to do below, or use the sidebar to browse everything. + +## Getting set up + + + + + + + +## Getting data in and out + + + + + + + + +## Working with your data + + + + + + + + +## Scripting and analysis + + + + + diff --git a/src/content/docs/user-guides/logging-into-xnat/index.mdx b/src/content/docs/user-guides/logging-into-xnat/index.mdx index 3adb8db6..4fe509ff 100644 --- a/src/content/docs/user-guides/logging-into-xnat/index.mdx +++ b/src/content/docs/user-guides/logging-into-xnat/index.mdx @@ -1,31 +1,25 @@ --- -title: Logging into XNAT -description: Logging into XNAT with AAF or RCC Authenticate +title: Logging in +description: Log in to UQ XNAT with your organisation's AAF credentials --- -import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; -import TabQueryLink from '@components/TabQueryLink.astro'; +import { Steps } from '@astrojs/starlight/components'; - - -There are two ways to log into XNAT. AAF is the recommended option for most users. - - - +If your organisation is part of the Australian Access Federation (AAF), you can +use your existing institutional credentials to log in. :::note -AAF is the recommended way to sign up and login to XNAT. - -If your organisation is not in the AAF list during the sign-up process, please contact the respective XNAT support for further options +If your organisation is not in the AAF list during sign-up, contact RCC support +for other options. ::: -If your organisation is part of the Australian Access Federation (AAF), you can use your AAF credentials to sign up. Follow the steps below to sign-up/login using AAF. +## Logging in with AAF 1. Open [https://xnat.rcc.uq.edu.au](https://xnat.rcc.uq.edu.au) -2. Log in with the AAF Single sign-on button (shown below) +2. Log in with the AAF Single sign-on button. ![XNAT AAF login page](./xnat-aaf-login-page.png) @@ -33,22 +27,12 @@ If your organisation is part of the Australian Access Federation (AAF), you can -:::caution[First time users] -First time users will only see publically accessible projects when they login +:::note[First time users] +You will not see any projects the first time you log in — your account has only +just been created. See [Your project](/user-guides/using-xnat/projects/your-project) +for how to get access to one. ::: -For more details on the Australian Access Federation, see https://aaf.edu.au - - - - -To use this login, you would have received an email from a UQ XNAT administrator with the login information. - -:::caution[Note] -If you have not received an email, either use **AAF** (see the other tab) or contact the respective XNAT support. - -RCC Authenticate credentials are **NOT** your UQ or institutional username and password -::: +## Further reading - - +- [Australian Access Federation](https://aaf.edu.au) diff --git a/src/content/docs/user-guides/managing-data/anonymising-data/index.mdx b/src/content/docs/user-guides/managing-data/anonymising-data/index.mdx index 079b65ee..45dfa43c 100644 --- a/src/content/docs/user-guides/managing-data/anonymising-data/index.mdx +++ b/src/content/docs/user-guides/managing-data/anonymising-data/index.mdx @@ -1,5 +1,5 @@ --- -title: Anonymising Data +title: Anonymising data description: Site-level and project-level anonymisation of DICOM data --- diff --git a/src/content/docs/user-guides/managing-data/anonymising-data/project-anonymiser.md b/src/content/docs/user-guides/managing-data/anonymising-data/project-anonymiser.md index f677a09a..795c1571 100644 --- a/src/content/docs/user-guides/managing-data/anonymising-data/project-anonymiser.md +++ b/src/content/docs/user-guides/managing-data/anonymising-data/project-anonymiser.md @@ -1,6 +1,6 @@ --- title: Project anonymiser -description: Project anonymiser +description: Use a DicomEdit script to rename, retag or further anonymise sessions as they are archived into your project --- The Project level anonymiser uses a scripting syntax called DicomEdit to modify, reassign or blank DICOM tags. @@ -21,7 +21,7 @@ The example in this screenshot basically replicates the behaviour in the HIRF on You can use DICOMedit to enforce a particular naming and tagging scheme across your entire project this way. -## Anonymising existing sesssions +## Anonymising existing sessions :::note[Note] If you’re planning to use the project level anonymiser, best solution would be to have your project’s renaming, retagging or anonymisation scheme established before starting data acquisition. diff --git a/src/content/docs/user-guides/managing-data/anonymising-data/site-anonymiser.md b/src/content/docs/user-guides/managing-data/anonymising-data/site-anonymiser.md index 387934ee..8c2043b0 100644 --- a/src/content/docs/user-guides/managing-data/anonymising-data/site-anonymiser.md +++ b/src/content/docs/user-guides/managing-data/anonymising-data/site-anonymiser.md @@ -1,6 +1,6 @@ --- -title: Site anonymiser -description: Site anonymiser +title: On-site anonymisation +description: Which DICOM tags are modified and blanked when HIRF and CAI data is anonymised on-site before it reaches XNAT --- HIRF and CAI data are anonymised on-site by default with the following protocols diff --git a/src/content/docs/user-guides/managing-data/downloading-data/desktop-client.md b/src/content/docs/user-guides/managing-data/downloading-data/desktop-client.md deleted file mode 100644 index fc067191..00000000 --- a/src/content/docs/user-guides/managing-data/downloading-data/desktop-client.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Desktop client -description: Downloading data using the XNAT Desktop client ---- - -The XNAT Desktop client is maintained by the XNAT development team. For information see the link below. - -XNAT Desktop client -: https://www.xnat.org/download/desktop-client/ - -## Install client - -Download and install the client for you operating system - -![Install desktop client](./desktop-client/desktop-client-1.png) - -## Download images - -The Project, Subject and Sessions page has the option to **Download Images** from the right hand side menu - -![Download Images menu](./desktop-client/desktop-client-2.png) - -Select **Option 1: Download via Desktop Client** - -:::caution[Note] -Untick **Simply downloaded archive structure** to keep scan names in scan folders -::: - -![Download via Desktop Client](./desktop-client/desktop-client-3.png) - -Click **Download Via App** - -![Download Via App](./desktop-client/desktop-client-4.png) - -Select a local destination folder - -![Select destination folder](./desktop-client/desktop-client-5.png) - -Download should start, and progress can be monitored diff --git a/src/content/docs/user-guides/managing-data/downloading-data/download-scan.md b/src/content/docs/user-guides/managing-data/downloading-data/download-scan.md deleted file mode 100644 index 8ba75c51..00000000 --- a/src/content/docs/user-guides/managing-data/downloading-data/download-scan.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Download Scan -description: Downloading induvidual Scans using the XNAT UI ---- - -Induvidual scans can be downloaded from the Sessions page - -![Download scan from session](./download-scan/downloading-data-scan-1.png) - -Multiple scans can be selected and downloaded using **Bulk Actions** - -![Bulk download scans](./download-scan/downloading-data-scan-2.png) diff --git a/src/content/docs/user-guides/managing-data/downloading-data/index.mdx b/src/content/docs/user-guides/managing-data/downloading-data/index.mdx index d37f69c3..4a99ad2d 100644 --- a/src/content/docs/user-guides/managing-data/downloading-data/index.mdx +++ b/src/content/docs/user-guides/managing-data/downloading-data/index.mdx @@ -1,16 +1,120 @@ --- title: Downloading Data -description: Downloading data from XNAT Projects +description: Download a whole project, a single session or individual scans from XNAT, as a zip or via the Desktop client --- -import { CardGrid, LinkCard } from '@astrojs/starlight/components'; +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; +import TabQueryLink from '@components/TabQueryLink.astro'; -There are a few ways to download data from XNAT, depending on how much you need and the tools you prefer. +There are three ways to get data out of XNAT. Which one you want depends on how +much you are taking and what you plan to do with it. - - - - - +| If you want | Use | Notes | +| --- | --- | --- | +| A whole project, subject or session | **Zip download** | Everything in one archive, straight from the browser | +| Large downloads, or a resumable transfer | **Desktop client** | A separate application you install once | +| One scan, or a few scans from a session | **Individual scans** | Fastest when you only need part of a session | -For further information refer to the [XNAT official guide on downloading data](https://wiki.xnat.org/documentation/how-to-use-xnat/how-to-download-image-data-from-xnat-projects). +{/* Tab labels are load-bearing: TabQueryLink slugifies the label to build the + ?method= value, and the legacy redirects in astro.config.mjs point at those + exact slugs. Renaming a label breaks those URLs silently. */} + + + + +The Project, Subject and Sessions pages each have a **Download Images** option +in the right hand side menu. + + + +1. Open **Download Images** from the right hand menu. + + ![Download Images menu](./zip-download/downloading-data-1.png) + +2. Choose what to include from the download options. + + ![Download options](./zip-download/downloading-data-2.png) + +3. Select **Option 2: ZIP download**. + + ![Download dialog](./zip-download/downloading-data-3.png) + + :::caution + Untick **Simply downloaded archive structure** to keep scan names in scan folders. + ::: + +4. Filter the sessions and scans using the first two columns, then select **Submit**. + + ![ZIP download options](./zip-download/downloading-data-zip.png) + + + + + + +The XNAT Desktop client is a separate application maintained by the XNAT +development team. Install it once, then trigger downloads from the browser and +hand them to the client. + +:::note +The client signs in to XNAT with an +[alias token](/user-guides/processing-data/alias-tokens), not your AAF login. +::: + + + +1. Download and install [the XNAT Desktop client](https://www.xnat.org/download/desktop-client/) + for your operating system. + + ![Install desktop client](./desktop-client/desktop-client-1.png) + +2. In XNAT, open **Download Images** from the right hand menu of a Project, + Subject or Session. + + ![Download Images menu](./desktop-client/desktop-client-2.png) + +3. Select **Option 1: Download via Desktop Client**. + + :::caution + Untick **Simply downloaded archive structure** to keep scan names in scan folders. + ::: + + ![Download via Desktop Client](./desktop-client/desktop-client-3.png) + +4. Click **Download Via App**. + + ![Download Via App](./desktop-client/desktop-client-4.png) + +5. Select a local destination folder. The download starts, and you can monitor + its progress in the client. + + ![Select destination folder](./desktop-client/desktop-client-5.png) + + + + + + +When you only need part of a session, download the scans directly from the +Sessions page rather than taking the whole session. + + + +1. Open the session and download the scan from the Sessions page. + + ![Download scan from session](./download-scan/downloading-data-scan-1.png) + +2. To take several at once, select the scans you want and use **Bulk Actions**. + + ![Bulk download scans](./download-scan/downloading-data-scan-2.png) + + + + + + + + +## Further reading + +- [XNAT official guide on downloading image data](https://wiki.xnat.org/documentation/how-to-use-xnat/how-to-download-image-data-from-xnat-projects) diff --git a/src/content/docs/user-guides/managing-data/downloading-data/zip-download.md b/src/content/docs/user-guides/managing-data/downloading-data/zip-download.md deleted file mode 100644 index 36494537..00000000 --- a/src/content/docs/user-guides/managing-data/downloading-data/zip-download.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Zip Download -description: Downloading data as Zip using the XNAT UI ---- - -The Project, Subject and Sessions page has the option to **Download Images** from the right hand side menu - -![Download Images menu](./zip-download/downloading-data-1.png) -![Download options](./zip-download/downloading-data-2.png) -![Download dialog](./zip-download/downloading-data-3.png) - -Select **Option 2: ZIP download** - -:::caution[Note] -Untick **Simply downloaded archive structure** to keep scan names in scan folders -::: - -![ZIP download options](./zip-download/downloading-data-zip.png) - -Filter out the Session and scans from the first two columns and select **Submit** diff --git a/src/content/docs/user-guides/managing-data/index.mdx b/src/content/docs/user-guides/managing-data/index.mdx index f46b2e74..6fc21c18 100644 --- a/src/content/docs/user-guides/managing-data/index.mdx +++ b/src/content/docs/user-guides/managing-data/index.mdx @@ -1,6 +1,6 @@ --- title: Managing Data -description: Managing Data +description: Upload, download, view, sync and anonymise imaging data once your XNAT project exists --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; diff --git a/src/content/docs/user-guides/managing-data/syncing-data/index.md b/src/content/docs/user-guides/managing-data/syncing-data/index.md index 43302675..e99c3b65 100644 --- a/src/content/docs/user-guides/managing-data/syncing-data/index.md +++ b/src/content/docs/user-guides/managing-data/syncing-data/index.md @@ -1,5 +1,5 @@ --- -title: Syncing Data +title: Syncing between XNATs description: Request syncing of datasets to other XNATs in Australia --- diff --git a/src/content/docs/user-guides/managing-data/uploading-data/facility-uploads.md b/src/content/docs/user-guides/managing-data/uploading-data/facility-uploads.md new file mode 100644 index 00000000..94452ff0 --- /dev/null +++ b/src/content/docs/user-guides/managing-data/uploading-data/facility-uploads.md @@ -0,0 +1,38 @@ +--- +title: Automated facility uploads +description: How imaging data acquired at HIRF, CAI or TRI reaches your XNAT project without you uploading it +draft: true +--- + +:::caution[Draft — not yet reviewed] +This page is a skeleton. The details marked below need confirming by someone who +runs the service before it is published. +::: + +If your data is acquired at HIRF, CAI or TRI, you do not need to upload it. The +facility sends it to XNAT for you. + +## What happens + + + +1. Your session is acquired at the facility. +2. The data is de-identified on-site before it leaves the facility. See + [On-site anonymisation](/user-guides/managing-data/anonymising-data/site-anonymiser) + for the DICOM tags this changes. +3. The data is sent to UQ XNAT and archived into your project. + + + +## If your data has not arrived + +- Check the prearchive — data waiting there has arrived but not been archived. + See [Fixing stuck uploads](/user-guides/managing-data/uploading-data/prearchive). +- Check you have access to the project. Data can be in XNAT before you are added + to the project. See [Your project](/user-guides/using-xnat/projects/your-project). +- If neither applies, contact the facility that acquired the data. + + diff --git a/src/content/docs/user-guides/managing-data/uploading-data/index.mdx b/src/content/docs/user-guides/managing-data/uploading-data/index.mdx index a4d2c9d9..0d39a314 100644 --- a/src/content/docs/user-guides/managing-data/uploading-data/index.mdx +++ b/src/content/docs/user-guides/managing-data/uploading-data/index.mdx @@ -1,14 +1,39 @@ --- -title: Uploading Data -description: Upload data to XNAT Projects +title: Uploading and downloading data +description: Compare the ways of getting imaging data into and out of XNAT, and pick the one that suits your data and tools --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; +There are several ways to move data in and out of XNAT. Which one suits you +depends on how much data you have and whether you are working in the browser or +from a script. + +## Getting data in + + + + + + + +## Getting data out + - - - + + -Data can also be uploaded via the XNAT data client or CTP. For further information refer to the [image session upload methods in XNAT](https://wiki.xnat.org/documentation/how-to-use-xnat/image-session-upload-methods-in-xnat). +## From the command line + +Scripted uploads and downloads use the same tools in both directions, and need +an alias token rather than your AAF login. + + + + + + +## Further reading + +- [Image session upload methods in XNAT](https://wiki.xnat.org/documentation/how-to-use-xnat/image-session-upload-methods-in-xnat) diff --git a/src/content/docs/user-guides/managing-data/uploading-data/prearchive.md b/src/content/docs/user-guides/managing-data/uploading-data/prearchive.md index eb603265..b6f86bbe 100644 --- a/src/content/docs/user-guides/managing-data/uploading-data/prearchive.md +++ b/src/content/docs/user-guides/managing-data/uploading-data/prearchive.md @@ -1,29 +1,45 @@ --- -title: Prearchive -description: XNAT Prearchive +title: Fixing stuck uploads +description: What to do when uploaded data does not appear in your project, and how to archive or merge a session waiting in the prearchive --- -If a dataset has not arrived into your XNAT project, the prearchive would be the place to check +If data you uploaded has not appeared in your XNAT project, it is probably +waiting in the **prearchive** — a holding area that uploads pass through before +they are archived into a project. -This usually happens when: -- a DICOM dataset matching an existing session gets resent -- a part of a session gets uploaded separately +Data usually stops there when: -## Accessing the prearchive +- a DICOM dataset matching an existing session is sent again +- part of a session is uploaded separately -Go to **Upload** on the top menu, and **Go to prearchive** +## Finding your data + +Go to **Upload** on the top menu, then **Go to prearchive**. ![Go to prearchive](./prearchive/prearchive-1.png) -The following is an example of a session that is in conflict. -We can select the session and choose **Details**. +Select the session and choose **Details** to review it. Below is an example of a +session in conflict. ![Prearchive session details](./prearchive/prearchive-2.png) -Here we can download the session, or individual scans. -And review the datasets +From here you can download the session or individual scans to check the contents +before deciding what to do with it. -- Choose **Archive** if you want the dataset merged into the existing one on the archive, -- choose **Modify and Archive** if any details need to be changed before archiving, or if you don’t want this dataset to merge with the existing one +## Archiving the data ![Archive options](./prearchive/prearchive-3.png) + +This choice matters, and it cannot be undone easily: + +- **Archive** merges the data into the existing session in your project. Use this + when the upload is the missing part of a session that is already there. +- **Modify and Archive** lets you change the details first. Use this when the + data should become a separate session, or when the session or subject labels + are wrong. + +:::caution +If you are not sure whether the data belongs to the existing session, download +it and check before archiving. Merging the wrong data into a session is harder +to unpick than archiving it separately. +::: diff --git a/src/content/docs/user-guides/managing-data/uploading-data/resource-uploader.md b/src/content/docs/user-guides/managing-data/uploading-data/resource-uploader.md index cbd0e1d3..914fc941 100644 --- a/src/content/docs/user-guides/managing-data/uploading-data/resource-uploader.md +++ b/src/content/docs/user-guides/managing-data/uploading-data/resource-uploader.md @@ -1,6 +1,6 @@ --- -title: Resource uploader -description: Resource uploader +title: Custom upload forms +description: Create a reusable web upload form for repeated uploads of non-DICOM data, such as analysis outputs or behavioural files --- This is to create a web upload form for repeated uploads of any data type. diff --git a/src/content/docs/user-guides/managing-data/uploading-data/web-upload.mdx b/src/content/docs/user-guides/managing-data/uploading-data/web-upload.mdx index ff1d0e15..7adc45a9 100644 --- a/src/content/docs/user-guides/managing-data/uploading-data/web-upload.mdx +++ b/src/content/docs/user-guides/managing-data/uploading-data/web-upload.mdx @@ -1,5 +1,5 @@ --- -title: Web Upload +title: Upload from the browser description: Upload using XNAT compressed uploader --- @@ -47,4 +47,4 @@ This is for uploading **de-identified DICOM** files using the uploader directly
-For further information refer to the [XNAT official guide on using the compressed image uploader](https://wiki.xnat.org/documentation/how-to-use-xnat/image-session-upload-methods-in-xnat/using-the-compressed-image-uploader). +For further information refer to the [XNAT official guide on using the compressed image uploader](https://wiki.xnat.org/documentation/how-to-use-xnat/using-the-compressed-image-uploader). diff --git a/src/content/docs/user-guides/processing-data/alias-tokens.md b/src/content/docs/user-guides/processing-data/alias-tokens.md index 5d40361c..e62ef566 100644 --- a/src/content/docs/user-guides/processing-data/alias-tokens.md +++ b/src/content/docs/user-guides/processing-data/alias-tokens.md @@ -1,6 +1,6 @@ --- title: Alias tokens -description: Alias tokens +description: Generate a time-limited username and password so desktop clients, command line tools and XSync can connect to XNAT without your AAF login --- AAF is used for logging into the XNAT website itself. diff --git a/src/content/docs/user-guides/processing-data/command-line-tools/index.mdx b/src/content/docs/user-guides/processing-data/command-line-tools/index.mdx index 746a2d94..96c1476d 100644 --- a/src/content/docs/user-guides/processing-data/command-line-tools/index.mdx +++ b/src/content/docs/user-guides/processing-data/command-line-tools/index.mdx @@ -1,6 +1,6 @@ --- title: Command line tools -description: Command line tools +description: Connect to XNAT from the terminal or a Python script with xnatutils, xnatpy or pyxnat --- import { Tabs, TabItem } from '@astrojs/starlight/components'; diff --git a/src/content/docs/user-guides/processing-data/index.mdx b/src/content/docs/user-guides/processing-data/index.mdx index f58a0e5b..6ceb0b79 100644 --- a/src/content/docs/user-guides/processing-data/index.mdx +++ b/src/content/docs/user-guides/processing-data/index.mdx @@ -1,11 +1,11 @@ --- -title: Processing Data -description: Processing Data +title: Command line access +description: Connect to XNAT from a terminal or script using an alias token with xnatutils, xnatpy or pyxnat --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + - diff --git a/src/content/docs/user-guides/processing-data/interactive-analysis/index.mdx b/src/content/docs/user-guides/processing-data/interactive-analysis/index.mdx index 53818d7e..625fef0a 100644 --- a/src/content/docs/user-guides/processing-data/interactive-analysis/index.mdx +++ b/src/content/docs/user-guides/processing-data/interactive-analysis/index.mdx @@ -1,10 +1,10 @@ --- -title: Interactive Analysis -description: Interactive Analysis +title: Jupyter environment +description: Request access to a Jupyter environment and run notebooks directly against your XNAT project data --- import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; -import EmailJupyterRequestForm from '@components/EmailJupyterRequestForm.astro'; +import RequestEmailForm from '@components/RequestEmailForm.astro'; You can access a Jupyter environment directly from XNAT. This allows you to run analysis on your data using familiar tools like Jupyter notebooks. RCC support can set up access to the Jupyter environment. @@ -12,9 +12,13 @@ You can access a Jupyter environment directly from XNAT. This allows you to run -1. Open a ticket with RCC support. Fill in your XNAT project name/s that should be accessible from the Jupyter environment below and click to send a pre-filled email. +1. Open a ticket with RCC support. Fill in the XNAT projects that should be accessible from the Jupyter environment, then copy the generated email into your mail client. - + 2. The support ticket will inform you when your access is set up. Jupyter access setup typically takes around ~24 hours from ticket submission. diff --git a/src/content/docs/user-guides/using-xnat/index.mdx b/src/content/docs/user-guides/using-xnat/index.mdx index dcfd5206..4427e44a 100644 --- a/src/content/docs/user-guides/using-xnat/index.mdx +++ b/src/content/docs/user-guides/using-xnat/index.mdx @@ -1,6 +1,6 @@ --- -title: Using XNAT -description: Using XNAT +title: Browsing and organising +description: Browse and organise your imaging data in XNAT, across projects, subjects, sessions and search --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; @@ -12,4 +12,4 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -For further information refer to the [XNAT official guides on browsing data](https://wiki.xnat.org/documentation/how-to-use-xnat/using-the-standard-search/browsing-data-types). +For further information refer to the [XNAT official guides on browsing data](https://wiki.xnat.org/documentation/how-to-use-xnat/browsing-data-types). diff --git a/src/content/docs/user-guides/using-xnat/projects/granting-access.md b/src/content/docs/user-guides/using-xnat/projects/granting-access.md index 8355d5c2..e02ca7a8 100644 --- a/src/content/docs/user-guides/using-xnat/projects/granting-access.md +++ b/src/content/docs/user-guides/using-xnat/projects/granting-access.md @@ -1,9 +1,9 @@ --- title: Granting Access -description: Granting project access to other users +description: Add users to an XNAT project and choose whether they are an Owner, Member or Collaborator --- -Switch to the Access tab. Use **Add User** or **Add Users from List** to select the user to add +Switch to the Access tab. Use **Add User** or **Add Users from List** to select the user to add. ![Add user to project](./granting-access/user-access.png) diff --git a/src/content/docs/user-guides/using-xnat/projects/index.md b/src/content/docs/user-guides/using-xnat/projects/index.md index 4639582b..edb33a31 100644 --- a/src/content/docs/user-guides/using-xnat/projects/index.md +++ b/src/content/docs/user-guides/using-xnat/projects/index.md @@ -9,3 +9,9 @@ When you login into the home page, the list of projects that you have access to - User access is controlled at the project level ![Project list](./project-list.png) + +## Working with projects + +- [Your XNAT project](/user-guides/using-xnat/projects/your-project) — request a new project, or get access to an existing one +- [Granting access](/user-guides/using-xnat/projects/granting-access) — add users as Owners, Members or Collaborators +- [Requesting more storage](/user-guides/using-xnat/projects/request-storage) — raise the 1TB and 1 million file limits diff --git a/src/content/docs/user-guides/using-xnat/projects/request-storage.mdx b/src/content/docs/user-guides/using-xnat/projects/request-storage.mdx index f41e25b7..7082a028 100644 --- a/src/content/docs/user-guides/using-xnat/projects/request-storage.mdx +++ b/src/content/docs/user-guides/using-xnat/projects/request-storage.mdx @@ -1,5 +1,5 @@ --- -title: Request Storage +title: Requesting more storage description: Request increase in storage and file count limits --- diff --git a/src/content/docs/user-guides/using-xnat/projects/your-project.mdx b/src/content/docs/user-guides/using-xnat/projects/your-project.mdx new file mode 100644 index 00000000..81896144 --- /dev/null +++ b/src/content/docs/user-guides/using-xnat/projects/your-project.mdx @@ -0,0 +1,107 @@ +--- +title: Your project +description: Request a new XNAT project, join a colleague's project, or get access to data acquired at a facility +--- + +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; +import ChoiceCards from '@components/ChoiceCards.astro'; +import RequestEmailForm from '@components/RequestEmailForm.astro'; +import TabQueryLink from '@components/TabQueryLink.astro'; + +Every dataset in XNAT lives in a project, and access is controlled per project. +When you first log in you will have no projects listed. + + + + + + + +Only UQ staff and students can request a new project, because each XNAT project +is allocated against a UQ-RDM HPC collection. If you are not at UQ, ask a UQ +collaborator to request it. + +:::note +If your data is acquired at HIRF, CAI or TRI, check with the facility first — +they may create the project for you as part of your imaging booking. +::: + + + +1. Create a UQ-RDM **HPC Collection**. + + Open [https://rdm.uq.edu.au/create-record](https://rdm.uq.edu.au/create-record), + log in, and fill in the record with your project details. + + ![UQ-RDM create record](./your-project/uqrdm-create-record.png) + + :::caution[Important] + For **(6) Data Storage Options**, select the second option (_The project data + needs to be mounted on UQ HPC facilities._). Any other option is incompatible + with XNAT and will require a new RDM request. + ::: + + Select **REQUEST DATA STORAGE**. You will end up with a collection name such + as **PROJ001-Q0189** — HPC collections end in **-Q**, not **-A** or **-I**. + +2. Send the request to RCC support. + + + +3. Wait for confirmation. Project setup typically takes around 24 hours. + + + + + + + +Access is granted per project by an Owner, so someone has to add you. + + + +1. Ask the person who owns the project to add you. + + - **A study run by a colleague** — ask the study lead. + - **Data acquired at HIRF, CAI or TRI** — ask the facility, if they set the + project up. + +2. They follow [Granting access](/user-guides/using-xnat/projects/granting-access) + and choose your role — Owner, Member or Collaborator. + +3. Log in to XNAT. The project appears in your project list. + + + +:::caution +Contact RCC support if you have been told access was granted but the project is +still missing after five working days. +::: + +:::note +If you are from a non-AAF organisation, request an AAF account first — see +[Signing up](/user-guides/getting-started/?member=non-aaf-members). +::: + + + + + + + +## Further reading + +- [Granting access to your project](/user-guides/using-xnat/projects/granting-access) +- [Requesting more storage](/user-guides/using-xnat/projects/request-storage) diff --git a/src/content/docs/user-guides/getting-started/uqrdm-create-record.png b/src/content/docs/user-guides/using-xnat/projects/your-project/uqrdm-create-record.png similarity index 100% rename from src/content/docs/user-guides/getting-started/uqrdm-create-record.png rename to src/content/docs/user-guides/using-xnat/projects/your-project/uqrdm-create-record.png diff --git a/src/content/docs/user-guides/using-xnat/sessions/index.md b/src/content/docs/user-guides/using-xnat/sessions/index.md index a0be0454..00daf388 100644 --- a/src/content/docs/user-guides/using-xnat/sessions/index.md +++ b/src/content/docs/user-guides/using-xnat/sessions/index.md @@ -1,5 +1,5 @@ --- -title: Sessions +title: Sessions and scans description: Managing Scan Sessions --- diff --git a/src/partials/accessing-project.mdx b/src/partials/accessing-project.mdx deleted file mode 100644 index bd08a601..00000000 --- a/src/partials/accessing-project.mdx +++ /dev/null @@ -1,7 +0,0 @@ -#### If you are acquiring data at HIRF, CAI or TRI -- The respective facility will organise the project creation. -- You will receive a follow up email when access has been granted -- Contact rcc-support@uq.edu.au if you have not received access within 5 working days - -#### If you are collaborating on an existing XNAT project -- Contact the project lead to grant you access to the XNAT project diff --git a/src/partials/sign-in-aaf.mdx b/src/partials/sign-in-aaf.mdx index d6869f68..3e8ea319 100644 --- a/src/partials/sign-in-aaf.mdx +++ b/src/partials/sign-in-aaf.mdx @@ -16,7 +16,7 @@ import { Steps } from '@astrojs/starlight/components'; 3. After the AAF sign-in, you should be redirected back to XNAT. - There will be **no projects listed** when signing in for the first-time, as your user account would have just been created. + There will be **no projects listed** the first time, as your user account has only just been created. ![Signed in to XNAT](../content/docs/user-guides/getting-started/xnat-signed-in.png) diff --git a/src/styles/base.css b/src/styles/base.css new file mode 100644 index 00000000..66552a33 --- /dev/null +++ b/src/styles/base.css @@ -0,0 +1,53 @@ +/* Site-wide base behaviour: links, focus, motion, images. + Loaded after tokens.css and before components.css. */ + +/* Starlight distinguishes prose links by colour alone, at ~1.05:1 against body + text (WCAG 1.4.1). Scoped to markdown content: cards, hero actions and nav + links are distinguishable by shape and position. */ +.sl-markdown-content a:not(:where(.not-content *)) { + text-decoration: underline; + text-underline-offset: 0.2em; + text-decoration-thickness: from-font; +} + +.sl-markdown-content a:not(:where(.not-content *)):hover { + text-decoration-thickness: 2px; +} + +/* Headings that link to themselves shouldn't be underlined. */ +.sl-markdown-content :where(h1, h2, h3, h4, h5, h6) a { + text-decoration: none; +} + +/* The restyled search button and borderless theme toggle have no visible user + agent focus indicator. */ +:where(a, button, input, select, textarea, summary, [tabindex]):focus-visible { + outline: var(--xnat-focus-ring); + outline-offset: var(--xnat-focus-offset); + border-radius: var(--xnat-radius-sm); +} + +/* ChoiceCards and the request forms animate borders and backgrounds on hover + with no guard of their own. */ +@media (prefers-reduced-motion: reduce) { + *, + *::before, + *::after { + animation-duration: 0.01ms !important; + animation-iteration-count: 1 !important; + transition-duration: 0.01ms !important; + scroll-behavior: auto !important; + } +} + +/* Frame screenshots consistently: light border and soft shadow (no rounding - + it looks off on screenshots whose own edges are square). */ +.sl-markdown-content img:not([data-no-border]) { + border: 1px solid var(--xnat-surface-border); + box-shadow: 0 1px 5px rgba(0, 0, 0, 0.12); +} + +::selection { + background: var(--sl-color-accent); + color: var(--sl-color-text-invert); +} diff --git a/src/styles/custom.css b/src/styles/components.css similarity index 65% rename from src/styles/custom.css rename to src/styles/components.css index 7eb3a493..51bd6b4a 100644 --- a/src/styles/custom.css +++ b/src/styles/components.css @@ -1,34 +1,13 @@ -/* UQ XNAT theme — UQ purple (#51247a) accent. - Overrides Starlight's default accent palette in both colour modes. */ - -:root { - /* Dark mode accents (lighter purples for contrast on dark backgrounds) */ - --sl-color-accent-low: #2a1340; - --sl-color-accent: #8b5fb5; - --sl-color-accent-high: #d6c2e8; -} - -:root[data-theme='light'] { - /* Light mode accents derived from UQ purple #51247a */ - --sl-color-accent-low: #e7ddf1; - --sl-color-accent: #51247a; - --sl-color-accent-high: #341553; -} - -/* Frame screenshots consistently: light border and soft shadow (no rounding — - it looks off on screenshots whose own edges are square). */ -.sl-markdown-content img:not([data-no-border]) { - border: 1px solid var(--sl-color-gray-5); - box-shadow: 0 1px 5px rgba(0, 0, 0, 0.12); -} +/* Overrides for specific Starlight components and page furniture. + Loaded last, after tokens.css and base.css. */ /* ---- Homepage links below the feature cards ---- */ .home-links { text-align: center; - margin-top: 3rem; + margin-top: var(--xnat-space-7); } .home-links p { - margin: 0.3rem 0; + margin: var(--xnat-space-1) 0; } .home-links__heading { font-weight: 600; @@ -41,14 +20,14 @@ margin: 0 0.6rem; } .home-links__ais { - margin-top: 1.25rem !important; + margin-top: var(--xnat-space-5) !important; font-size: var(--sl-text-sm); } -/* Sidebar: keep only the top-level headers (User Guides, Facility Guides) - bold/large. Normalise every nested expandable group label so it matches the - plain single-page links beside it. (`.top-level ul .large` excludes the two - top headers, whose label sits in the summary, not inside a nested list.) */ +/* Sidebar: keep only the top-level headers bold/large. Normalise every nested + expandable group label so it matches the plain single-page links beside it. + (`.top-level ul .large` excludes the top headers, whose label sits in the + summary, not inside a nested list.) */ .top-level ul .large { font-size: var(--sl-text-base); font-weight: 400; @@ -84,16 +63,16 @@ height: auto; box-sizing: border-box; background: #fff; - padding: 1rem 1.25rem; - border-radius: 0.75rem; - border: 1px solid var(--sl-color-gray-5); + padding: var(--xnat-space-4) var(--xnat-space-5); + border-radius: var(--xnat-radius-lg); + border: 1px solid var(--xnat-surface-border); box-shadow: 0 2px 14px rgba(0, 0, 0, 0.18); } /* ---- Navbar (adapted from the Neurodesk Starlight site) ---- */ /* Pagefind search trigger: Starlight styles it like a wide fake text input. - Restyle as a compact button — magnifier + "Search" + ⌘K hint — so the + Restyle as a compact button - magnifier + "Search" + ⌘K hint - so the affordance matches the modal it actually opens. */ site-search button[data-open-modal] { gap: 0.375rem; @@ -104,7 +83,7 @@ site-search button[data-open-modal] { site-search button[data-open-modal] { width: auto; max-width: none; - padding-inline: 0.5rem; + padding-inline: var(--xnat-space-2); background-color: transparent; border-color: transparent; border-radius: 0.375rem; @@ -122,14 +101,14 @@ site-search button[data-open-modal] { } site-search button[data-open-modal] kbd { - padding: 0 0.25rem; + padding: 0 var(--xnat-space-1); font-size: var(--sl-text-xs); background-color: var(--sl-color-gray-5); } /* Right-align search beside the nav links / theme toggle, with a divider. */ .header { - grid-template-columns: auto 1fr auto auto !important; + grid-template-columns: auto 1fr auto auto; } .header > div:has(site-search) { @@ -146,7 +125,12 @@ site-search button[data-open-modal] { content: ''; align-self: center; height: 1.25rem; - border-inline-start: 1px solid var(--sl-color-gray-5); + border-inline-start: 1px solid var(--xnat-surface-border); } } +/* Hero and link buttons. Starlight makes these full pills (999rem); square them + off to match the cards and framed screenshots. */ +.sl-link-button:is(.primary, .secondary, .minimal) { + border-radius: var(--xnat-radius-md); +} diff --git a/src/styles/tokens.css b/src/styles/tokens.css new file mode 100644 index 00000000..7a6078b6 --- /dev/null +++ b/src/styles/tokens.css @@ -0,0 +1,68 @@ +/* Design tokens. Loaded before base.css and components.css. + + Brand ramp: hue 271 lightness ladder, step 700 = UQ purple #51247A. + + customCss is injected unlayered and so beats Starlight's @layer + starlight.base regardless of specificity. Any --sl-* var set for dark mode + must also be set for light, or the dark value applies in both. */ + +:root { + --xnat-purple-50: #f5effb; + --xnat-purple-100: #e8dbf5; + --xnat-purple-200: #d2bae8; + --xnat-purple-300: #b48ed7; + --xnat-purple-400: #965ec9; + --xnat-purple-500: #7a37b9; + --xnat-purple-600: #632d95; + --xnat-purple-700: #51247a; + --xnat-purple-800: #3e1b5f; + --xnat-purple-900: #2c1244; + --xnat-purple-950: #1d0b2d; + + --xnat-radius-sm: 0.25rem; + --xnat-radius-md: 0.5rem; + --xnat-radius-lg: 0.75rem; + + --xnat-space-1: 0.25rem; + --xnat-space-2: 0.5rem; + --xnat-space-3: 0.75rem; + --xnat-space-4: 1rem; + --xnat-space-5: 1.5rem; + --xnat-space-6: 2rem; + --xnat-space-7: 3rem; + + --xnat-focus-ring: 2px solid var(--sl-color-accent); + --xnat-focus-offset: 2px; + --xnat-transition: 150ms ease; + + /* 45rem squeezes this site's screenshots. */ + --sl-content-width: 47rem; + --sl-line-height: 1.7; +} + +/* Dark mode. accent-high carries prose links (10.1:1 on page background); + accent is used for focus rings and component button text (6.6:1); + accent-low is text-invert, drawn on accent (6.1:1). */ +:root { + --sl-color-accent-low: var(--xnat-purple-900); + --sl-color-accent: var(--xnat-purple-300); + --sl-color-accent-high: var(--xnat-purple-200); + + /* Starlight defines gray-7 in light mode only; components reaching for it + fell back to the page background and rendered without a surface. */ + --xnat-surface: var(--sl-color-gray-6); + --xnat-surface-raised: var(--sl-color-gray-5); + --xnat-surface-border: var(--sl-color-gray-5); +} + +/* Light mode. accent carries prose links (11.2:1 on page background) and is + also bg-accent, with white on it at 11.2:1. */ +:root[data-theme='light'] { + --sl-color-accent-low: var(--xnat-purple-100); + --sl-color-accent: var(--xnat-purple-700); + --sl-color-accent-high: var(--xnat-purple-800); + + --xnat-surface: var(--sl-color-gray-7); + --xnat-surface-raised: #fff; + --xnat-surface-border: var(--sl-color-gray-5); +}