Skip to content

Add ReadTheDocs redirect to docs.quantms.org - #616

Merged
ypriverol merged 2 commits into
readthedocsfrom
copilot/add-redirect-for-docs-url
Nov 28, 2025
Merged

Add ReadTheDocs redirect to docs.quantms.org#616
ypriverol merged 2 commits into
readthedocsfrom
copilot/add-redirect-for-docs-url

Conversation

Copilot AI commented Nov 28, 2025 •
edited by qodo-code-review Bot
Loading

Copy link
Copy Markdown
Contributor

User description

PR checklist

  • This comment contains a description of changes (with reason).
  • If you've fixed a bug or added code that should be tested, add tests!
  • If you've added a new tool - have you followed the pipeline conventions in the contribution docs
  • If necessary, also make a PR on the bigbio/quantms branch on the nf-core/test-datasets repository.
  • Make sure your code lints (nf-core pipelines lint).
  • Ensure the test suite passes (nextflow run . -profile test,docker --outdir <OUTDIR>).
  • Check for unexpected warnings in debug mode (nextflow run . -profile debug,test,docker --outdir <OUTDIR>).
  • Usage Documentation in docs/usage.md is updated.
  • Output Documentation in docs/output.md is updated.
  • CHANGELOG.md is updated.
  • README.md is updated (including new tool citations and authors/contributors).

Description

After moving documentation to a dedicated repository, quantms.readthedocs.io no longer exists. This adds a shallow Sphinx site using sphinx-reredirects to automatically redirect visitors to docs.quantms.org/en/latest/.

Changes

  • .readthedocs.yaml - RTD build config (Python 3.11, Ubuntu 22.04)
  • docs/requirements.txt - Sphinx + sphinx-reredirects dependencies
  • docs/source/conf.py - Sphinx config with redirect to new docs URL
  • docs/source/index.rst - Fallback content for no-JS users

Redirect behavior

Generated HTML uses JavaScript redirect with meta refresh fallback, preserving URL hash fragments:

<html><head>
  <noscript><meta http-equiv="refresh" content="0; url=https://docs.quantms.org/en/latest/" /></noscript>
  <script>window.location.replace("https://docs.quantms.org/en/latest/" + window.location.hash);</script>
</head></html>

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • https://api.github.com//advisories
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

After we moved to https://quantms-readthedocs.readthedocs.io/ for a dedicated repository for the documentation, the following URL no longer exists. It would be nice if we could find a way to redirect from https://quantms.readthedocs.io/ -> https://docs.quantms.org/en/latest/.

We could add a shallow website which is basically saying: Go here. (and maybe this can even be done automatically)

https://documatt.com/sphinx-reredirects/usage/

Agree. We can do that, we need to have in any case in docs of quantms that shallow website because quantms.readthedocs.io must be based on the GitHub repo of quantms or one branch around it.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

PR Type

Enhancement, Documentation

Description

  • Set up ReadTheDocs redirect infrastructure from quantms.readthedocs.io

  • Configure Sphinx with sphinx-reredirects for automatic URL forwarding

  • Redirect users to new documentation site at docs.quantms.org/en/latest/

  • Provide fallback content for JavaScript-disabled browsers

Diagram Walkthrough

flowchart LR
  A["quantms.readthedocs.io"] -->|"JavaScript redirect"| B["docs.quantms.org/en/latest/"]
  A -->|"No-JS fallback"| C["Meta refresh redirect"]
  C --> B
Loading

File Walkthrough
Relevant files
Configuration changes
.readthedocs.yaml
ReadTheDocs build configuration                                                   

.readthedocs.yaml

  • Created ReadTheDocs build configuration file
  • Specified Python 3.11 and Ubuntu 22.04 environment
  • Configured Sphinx documentation source path
  • Set up Python dependencies installation from docs/requirements.txt
 +16/-0   
conf.py
Sphinx configuration with redirect setup                                 

docs/source/conf.py

  • Created Sphinx configuration file for redirect site
  • Enabled sphinx_reredirects extension
  • Configured redirect mapping from index to docs.quantms.org/en/latest/
  • Set alabaster as HTML theme
 +22/-0   
Dependencies
requirements.txt
Sphinx and redirect dependencies                                                 

docs/requirements.txt

  • Added Sphinx 7.0.0+ dependency for documentation building
  • Added sphinx-reredirects 0.1.5+ for URL redirect functionality
 +2/-0     
Documentation
index.rst
Fallback documentation index page                                               

docs/source/index.rst

  • Created fallback RST content for no-JavaScript users
  • Added note explaining documentation has moved
  • Provided clickable link to new documentation location
  • Included message about automatic redirection
 +10/-0   

@coderabbitai

coderabbitai Bot commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Comment @coderabbitai help to get the list of available commands and usage tips.

@ypriverol
Add ReadTheDocs redirect to new documentation site at docs.quantms.org
5597d72 
Co-authored-by: ypriverol <52113+ypriverol@users.noreply.github.com>
Copilot AI changed the title [WIP] Add redirect from old documentation URL to new site Add ReadTheDocs redirect to docs.quantms.org Nov 28, 2025
Copilot AI requested a review from ypriverol November 28, 2025 07:14
@ypriverol
ypriverol marked this pull request as ready for review November 28, 2025 07:15
@ypriverol
ypriverol requested review from enryH and removed request for ypriverol November 28, 2025 07:15
@qodo-code-review

qodo-code-review Bot commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪
🎫 No ticket provided
  • Create ticket/issue
Codebase Duplication Compliance
⚪
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
Generic: Meaningful Naming and Self-Documenting Code

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Secure Logging Practices

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Security-First Input Validation and Data Handling

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

⚪
Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
Not Applicable: The added code configures Sphinx/ReadTheDocs redirects and does not implement application
logic where audit trails would apply; no critical actions are introduced to instrument.

Referred Code 
# Configuration file for the Sphinx documentation builder.
#
# This file redirects users from quantms.readthedocs.io to docs.quantms.org

# -- Project information -----------------------------------------------------
project = "quantms"
copyright = "2024, bigbio"
author = "bigbio"

# -- General configuration ---------------------------------------------------
extensions = [
    "sphinx_reredirects",
]

# -- Options for HTML output -------------------------------------------------
html_theme = "alabaster"

# -- sphinx-reredirects configuration ----------------------------------------
# Redirect the root page to the new documentation site
redirects = {
    "index": "https://docs.quantms.org/en/latest/",


 ... (clipped 1 lines)

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Robust Error Handling and Edge Case Management

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status:
No error handling: The configuration solely sets up a redirect without explicit error handling for
build/runtime failures, which may be acceptable for Sphinx config but cannot be verified
from the diff alone.

Referred Code 
extensions = [
    "sphinx_reredirects",
]

# -- Options for HTML output -------------------------------------------------
html_theme = "alabaster"

# -- sphinx-reredirects configuration ----------------------------------------
# Redirect the root page to the new documentation site
redirects = {
    "index": "https://docs.quantms.org/en/latest/",
}

Learn more about managing compliance generic rules or creating your own custom rules
Compliance status legend 🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

@qodo-code-review

qodo-code-review Bot commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
High-level
Use ReadTheDocs' built-in redirect feature

Instead of adding a new Sphinx site and dependencies to create a redirect, use
the built-in redirect feature in the ReadTheDocs admin dashboard. This avoids
adding unnecessary code and maintenance overhead.

Examples:

docs/source/conf.py [1-22] 
# Configuration file for the Sphinx documentation builder.
#
# This file redirects users from quantms.readthedocs.io to docs.quantms.org

# -- Project information -----------------------------------------------------
project = "quantms"
copyright = "2024, bigbio"
author = "bigbio"

# -- General configuration ---------------------------------------------------

 ... (clipped 12 lines)
.readthedocs.yaml [1-16] 
# Read the Docs configuration file for quantms
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"


 ... (clipped 6 lines)

Solution Walkthrough:

Before:

# .readthedocs.yaml
version: 2
build:
  os: ubuntu-22.04
  ...
sphinx:
  configuration: docs/source/conf.py
python:
  install:
    - requirements: docs/requirements.txt

# docs/source/conf.py
extensions = ["sphinx_reredirects"]
redirects = {
    "index": "https://docs.quantms.org/en/latest/",
}

After:

# All new files are removed from the repository.
# (.readthedocs.yaml, docs/requirements.txt, docs/source/conf.py, docs/source/index.rst)

# In ReadTheDocs Admin Dashboard for the project:
# 1. Go to "Redirects".
# 2. Add a "Page Redirect".
# 3. Type: "Exact Redirect".
# 4. From URL: "/".
# 5. To URL: "https://docs.quantms.org/en/latest/".
# 6. Save.
Suggestion importance[1-10]: 9

__

Why: The suggestion correctly identifies that the PR's code-based redirect can be replaced by a simpler, no-code configuration on the ReadTheDocs platform, eliminating unnecessary files and maintenance.

High
Possible issue
Implement a wildcard redirect for all pages

Implement a wildcard redirect to forward all pages from the old documentation
site to the new one, not just the index page. This will prevent users from
encountering 404 errors on bookmarked sub-pages.

docs/source/conf.py [20-22]

 redirects = {
-    "index": "https://docs.quantms.org/en/latest/",
+    "*": "https://docs.quantms.org/en/latest/$source.html",
 }
  • Apply / Chat
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies that the current redirect only handles the index page and proposes a wildcard redirect to handle all pages, which significantly improves the user experience by preventing 404 errors.

Medium
  • More

@ypriverol

ypriverol commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

@copilot should we have a different branch for this called: readthedocs, instead of doing this against dev?

Copilot AI commented Nov 28, 2025

Copy link
Copy Markdown
Contributor Author

@copilot should we have a different branch for this called: readthedocs, instead of doing this against dev?

Yes, having a dedicated readthedocs branch makes sense. This would keep the redirect documentation separate from the main pipeline code in dev. ReadTheDocs can be configured to build from the readthedocs branch specifically.

Would you like me to help create a new PR targeting a readthedocs branch, or would you prefer to handle the branch creation on your end?

Copilot AI requested a review from ypriverol November 28, 2025 07:25
@ypriverol

ypriverol commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

Do it yourself @copilot

Copilot AI commented Nov 28, 2025

Copy link
Copy Markdown
Contributor Author

Do it yourself @copilot

I'm unable to create new branches or new PRs directly - I can only work within the current branch and push changes using report_progress.

To move these changes to a readthedocs branch, you'll need to:

  1. Create a readthedocs branch from dev
  2. Cherry-pick commits 5597d72 (the main changes) to that branch
  3. Close this PR

Alternatively, you can retarget this PR to a readthedocs branch if you create it first. Would you like to handle that, or should we proceed with merging to dev?

@ypriverol

ypriverol commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

I already created the branch @copilot just retarget the PR.

Copilot AI commented Nov 28, 2025

Copy link
Copy Markdown
Contributor Author

I already created the branch @copilot just retarget the PR.

I'm unable to retarget PRs - that requires modifying PR settings which I don't have access to. You can retarget this PR yourself by:

  1. Go to the PR page
  2. Click "Edit" next to the base branch
  3. Change from dev to readthedocs

The commits will automatically apply to the new base branch.

@ypriverol ypriverol linked an issue Nov 28, 2025 that may be closed by this pull request
https://quantms.readthedocs.io/ not available #610
Closed
@ypriverol
ypriverol changed the base branch from dev to readthedocs November 28, 2025 07:36
@ypriverol

ypriverol commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

@copilot should we remove all the code and only leave the docs folder?

Copilot AI commented Nov 28, 2025

Copy link
Copy Markdown
Contributor Author

@copilot should we remove all the code and only leave the docs folder?

Yes, for a dedicated readthedocs branch, keeping only the necessary files makes sense. The minimal set needed would be:

  • .readthedocs.yaml - RTD build configuration
  • docs/requirements.txt - Python dependencies
  • docs/source/conf.py - Sphinx configuration with redirect
  • docs/source/index.rst - Fallback content

However, I'm unable to delete all repository files in this PR - that would require you to reset the readthedocs branch to an empty state and then cherry-pick just my documentation commits. Would you like to handle that on your end?

@ypriverol
ypriverol merged commit 0fadaf3 into readthedocs Nov 28, 2025
43 of 64 checks passed
@github-actions

github-actions Bot commented Nov 28, 2025

Copy link
Copy Markdown

nf-core pipelines lint overall result: Passed ✅ ⚠️

Posted for pipeline commit 5597d72

+| ✅ 111 tests passed       |+
#| ❔  19 tests were ignored |#
!| ❗   1 tests had warnings |!
Details

❗ Test warnings:

  • pipeline_todos - TODO string in nextflow.config: Specify any additional parameters here

❔ Tests ignored:

✅ Tests passed:

Run details

  • nf-core/tools version 3.5.1
  • Run at 2025-11-28 07:16:29

@enryH

enryH commented Nov 28, 2025

Copy link
Copy Markdown
Collaborator

amazing to see agents in use!

@ypriverol
ypriverol deleted the copilot/add-redirect-for-docs-url branch November 29, 2025 07:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@enryH enryH Awaiting requested review from enryH
@ypriverol ypriverol Awaiting requested review from ypriverol

Assignees

@ypriverol ypriverol

Copilot code review Copilot

Labels

Review effort 1/5

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

https://quantms.readthedocs.io/ not available

3 participants

@ypriverol @enryH