Skip to content

docs: fill the gaps in the researcher pages - #155

Merged
uniqueg merged 4 commits into
mainfrom
docs/89-researcher-gaps
Nov 17, 2026
Merged

uniqueg merged 4 commits into
mainfrom
docs/89-researcher-gaps

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Fills the gaps that #89 lists in the researcher pages, with the maintainers' answers of 2026-11-17:

  1. TES access: "Before you start" now asks researchers to join the LS Login group ECP_CLN:EOC-Compute (application form coming: generic-issues#49; until then, the service email). New section "Which TES services you can use": tasks go through the deployment's proTES (https://protes.rahtiapp.fi/) with an LS Login token from Krini; direct access only to TES services of Nodes that require tokens, found in the Cloud Registry.
  2. Demonstrators: the Snakemake demonstrator page (already updated for current proTES with fix: run the demo with current proTES demo-tes-hybrid-cloud#5) now points to the deployment's proTES; the pointer to the retired CWL demonstrator is dropped, and the CLI page no longer names cwl-WES. (The CWL demo line in "GA4GH Standards" goes in the PR for docs: fill the gaps in the partner pages #82, which edits that file.)
  3. SPE: the page "Sensitive Data in a Secure Processing Environment" and its nav and table entries are removed, as it names no service of the deployment, no address and no access process. Its content is recorded in a comment on docs: fill the gaps in the researcher pages #89, for its authors to re-add with an address and an access process if they want it back.
  4. Crypt4GH: the page says the middleware is being ported to the FOCA plugin tes.data.crypt4gh (foca-plugins#65/docs: rewrite the researchers section #66 merged; 0.1.0 prepared, not published) and keeps using proTES 0.3.0 until then. The "Under construction" note is folded into that note.

Removing researchers/spe-with-weskit.md drops its URL; the site has no redirect plugin.

Closes #89
Closes #61

This PR closes the parent #61 too, as #81, #82 and #89 are its last open children: merge it after #153 and #154.

Verification

  • python scripts/check_names.py: passes
  • mkdocs build --strict: passes, no warnings
  • pytest: 25 passed, 100% coverage (unchanged)
  • CI: all checks green (CI passed, Read the Docs build, CodeQL, Sourcery).

Declined review findings

Review

Light lane: docs only. I reviewed the diff myself.

🤖 Generated with Claude Code

Summary by Sourcery

Update researcher documentation to match the deployment’s available services, access requirements, and current demonstrators.

New Features:

  • Document how researchers obtain deployment compute access and use its proTES gateway or eligible Node TES services.
  • Add current guidance for running the Crypt4GH tutorial while its proTES plugin is unreleased.

Bug Fixes:

  • Remove references to the retired CWL demonstrator and the unavailable SPE with WESkit page.

Enhancements:

  • Update researcher tutorials and navigation to reflect the deployment's available TES services and current demonstrator guidance.
  • Clarify federated workflow prerequisites and deployment proTES usage.
  • Improve sensitive-data guidance by directing users to available Crypt4GH analysis resources.

Documentation:

  • Expand researcher documentation with LS Login group requirements, TES access and token-safety guidance, updated federated workflow instructions, and Crypt4GH status and setup notes.

Chores:

  • Remove the obsolete SPE with WESkit researcher page and its navigation entry.

Say how researchers use TES (proTES with an LS Login token from
Krini, as members of ECP_CLN:EOC-Compute), point the Snakemake
demonstrator at the deployment's proTES and drop the CWL demo
pointer, remove the SPE page, which names no service of the
deployment, and say that the Crypt4GH middleware is being ported.

Closes #89

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 17, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Configuration

Remove the obsolete SPE page from the site navigation.

  • mkdocs.yml L122 (removed lines)

Documentation

Document the deployment’s TES access path, group membership requirement, and token-safety guidance for researchers.

  • docs/researchers/index.md L17-18, L25-53

Update the Snakemake demonstrator and CLI guidance, and remove the retired CWL demonstrator pointer.

  • docs/researchers/cli.md L23
  • docs/researchers/federated-workflows.md L11-14, L47-53, L73 (removed lines)

Explain that Crypt4GH currently requires an unreleased proTES branch, record the tested versions, and document how to deploy that branch.

  • docs/researchers/crypt4gh-with-protes.md L11-52, L173-177, L186-210 (+1 small edits)

Remove the unsupported SPE researcher page and stop directing sensitive-data readers to it.

  • docs/partners-and-developers/sensitive-data.md L78-79
  • docs/researchers/spe-with-weskit.md (deleted)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@uniqueg
uniqueg marked this pull request as ready for review November 17, 2026 04:38

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 4 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/researchers/index.md" line_range="41-44" />
<code_context>
+token from [Krini](krini.md#copy-your-access-token): proTES accepts tokens
+that LS Login issued to Krini.
+
+You can also send tasks directly to the TES services of the Nodes that
+require LS Login tokens. Find them, and their addresses, in the Cloud
+Registry (see [Using the
+APIs](../partners-and-developers/apis.md#1-find-the-services)).
+
+[gi-49]: <https://github.com/elixir-cloud-aai/generic-issues/issues/49>
</code_context>
<issue_to_address>
**Service tokens reach untrusted endpoints**

When a researcher follows the new instructions and chooses an untrusted or unverified TES endpoint, the guidance sends an LS Login bearer token or other service credentials to the selected TES endpoint without telling researchers to check whether they trust it. An untrusted endpoint operator can capture and replay those credentials, acting as the researcher until the token expires.

Warn researchers to verify and trust each TES endpoint before sending it bearer tokens or other credentials, and link to the Cloud Registry guidance on checking service labels.

Also at `docs/researchers/federated-workflows.md:52-53`.
</issue_to_address>

### Comment 2
<location path="docs/researchers/index.md" line_range="34-35" />
<code_context>
+## Which TES services you can use
+
+Send your tasks to the TES gateway of the deployment,
+[proTES](../operators/services/protes.md), at
+<https://protes.rahtiapp.fi/> (TES API at
+`https://protes.rahtiapp.fi/ga4gh/tes/v1`), with an LS Login access token.
+proTES forwards each task to one of the TES services of the Nodes. Get the
</code_context>
<issue_to_address>
**Readers get conflicting endpoint guidance**

When readers consult the linked proTES or API documentation alongside the researcher guidance, the researcher page publishes the deployment gateway address and TES endpoint, while the operator page says the address is not documented and the API guide says TES endpoints are not documented. Readers cannot tell which endpoint guidance is current.

Update the linked operator and API documentation to document the published gateway address and TES endpoint.

Also at `docs/researchers/federated-workflows.md:48`, `docs/researchers/index.md:36-37`.
</issue_to_address>

### Comment 3
<location path="docs/researchers/index.md" line_range="26-27" />
<code_context>
-   APIs](../partners-and-developers/apis.md#1-find-the-services) shows how
-   to list them in the Cloud Registry.
+2. Become a member of the LS Login group `ECP_CLN:EOC-Compute`, which
+   gives access to the compute services of the deployment. An application
+   form is coming ([generic-issues#49][gi-49]); until then, write to
+   [cloud-service@elixir-europe.org][elixir-on-cloud-email].
 3. Choose a page above and follow its steps.
</code_context>
<issue_to_address>
**Admin members face unnecessary access steps**

When a researcher belongs to `ECP_CLN:ADMIN` but not `ECP_CLN:EOC-Compute`, the access instructions tell the researcher to join `ECP_CLN:EOC-Compute` and contact the service email, despite the TES guidance saying `ECP_CLN:ADMIN` members may run tasks. They are sent through an unnecessary access process.

State that `ECP_CLN:ADMIN` members may use the services without joining `ECP_CLN:EOC-Compute` or contacting the service email.
</issue_to_address>

### Comment 4
<location path="docs/researchers/index.md" line_range="19" />
<code_context>
-| [Crypt4GH with proTES](crypt4gh-with-protes.md) | Process Crypt4GH-encrypted files in a secure container. Needs proTES 0.3.0 or earlier. | Docker and three virtual machines. |
</code_context>
<issue_to_address>
**SPE guide recommendation leads nowhere**

The sensitive-data guide still directs readers to the Researchers index to try an SPE, but the removed entry leaves no SPE walkthrough or deployment service there; readers cannot follow the promised path to try one.

Revise the sensitive-data guide to clarify that the deployment currently offers no SPE to try, or point to a still-available SPE walkthrough.
</issue_to_address>

Sourcery assessment

Approval pending. 4 findings to address first.

Blocking findings: docs/researchers/index.md:44, docs/researchers/index.md:35, docs/researchers/index.md:27, docs/researchers/index.md:19


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/researchers/index.md Resolved
Comment thread docs/researchers/index.md Resolved
Comment thread docs/researchers/index.md Resolved
Comment thread docs/researchers/index.md Resolved
Warn researchers to send their token only to verified services that
they trust, and stop pointing the sensitive-data page to an SPE in
the researcher section, which no longer has one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 578f558

#61 docs: relaunch the hub at docs.elixir-on.cloud · 0 of 1 met

# Requirement Status Notes
1 Provide redirects from old URLs. 🟡 Partly met Removing the SPE page drops its old URL, and this change adds no redirect; the description notes that the site has no redirect plugin.

#89 docs: fill the gaps in the researcher pages · 3 of 4 met

# Requirement Status Notes
1 Document which deployment TES services researchers can use, their addresses, and how to get access. ✅ Met The page gives the deployment proTES address and token source, explains group access, and directs researchers to the Cloud Registry for direct TES service addresses.
2 Establish whether the Snakemake and CWL demonstrators are updated for current products. 🟡 Partly met The page says the Snakemake demonstrator's CI runs against proTES 0.6.0, but dropping the CWL pointer does not say whether that demonstrator works with current products.
3 Resolve the SPE service, address, interface, and access questions. ✅ Met The unsupported researcher SPE page and its navigation and table entries are removed.
4 Document the Crypt4GH middleware port, installation, and tested versions. ✅ Met The page describes the unreleased proTES branch used, gives deployment steps and records the versions available, noting where versions were not recorded.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New gaps against the linked issues

Comment thread mkdocs.yml Resolved

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New gaps against the linked issues

No released proTES runs the middleware: 0.4.0 and later drop
middlewares, and 0.3.0 refuses the released middleware, which doesn't
derive from AbstractMiddleware. Document the unreleased proTES branch
adjust_middleware that the tutorial's authors used, how to deploy it,
and the versions they used, as far as they were recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New gaps against the linked issues

Comment thread mkdocs.yml Resolved
Comment thread docs/researchers/federated-workflows.md Resolved
@uniqueg
uniqueg merged commit af8ea05 into main Nov 17, 2026
13 checks passed
@uniqueg
uniqueg deleted the docs/89-researcher-gaps branch November 17, 2026 06:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: fill the gaps in the researcher pages docs: relaunch the hub at docs.elixir-on.cloud

1 participant