Fix 404s from PR #4617: add stub pages for relocated/reauthored notebooks

[rogerawong]

Background

PR #4617 (“trim jupyter notebooks”, commit 65f501c27, Jun 4, 2026) removed 17 application notebooks from the CUDA-Q docs, but stopped short of adding redirects or stubs to indicate where some of this content has been relocated. The old paths now return 404.

Proposed fix

Let’s at least add stub pages for the nine notebooks we know were relocated/re-authored. Branch docs-notebook-404-stubs on rogerawong/cuda-quantum (one commit ahead of upstream/main, commit 83a2779d6) adds:

• Nine :orphan: RST stub pages at the nine old paths. Each stub states what happened in 0.15.0 and links directly to the destination notebook.
• Nine “moved to” HTML divs in applications.rst, placed at the positions where the original notebook-entry divs appeared before PR trim jupyter notebooks #4617.

This adds stub pages at the old URLs to provide guidance to AI agents hitting them. Stubs for relocated notebooks say the content is now hosted in the NVIDIA CUDA-Q Academic repository. Those for re-authored notebooks say a teaching module on the same topic is available there, since the destination notebooks are structured differently from the originals.

Evidence

9 of the 17 removed notebooks have counterparts in NVIDIA/cuda-q-academic: five were relocated near-verbatim (quantum_teleportation, bernstein_vazirani, quantum_fourier_transform, deutsch_algorithm, grovers) and four were re-authored as teaching modules (adapt_vqe, qm_mm_pe, hybrid_quantum_neural_networks, unitary_compilation_diffusion_models). All nine old paths now return a 404; applications/python/grovers is one example. The problem is compounded for AI assistants trained before mid-2026 that cite these paths from memory.

git show --stat 65f501c27 confirms 17 .ipynb files deleted from docs/sphinx/applications/python/ in that commit. Each counterpart in NVIDIA/cuda-q-academic was confirmed by reading the file at the destination path.

Old docs path	Destination in cuda-q-academic	Disposition
applications/python/quantum_teleportation	qis-examples/quantum_teleportation.ipynb	relocated
applications/python/bernstein_vazirani	qis-examples/bernstein_vazirani.ipynb	relocated
applications/python/quantum_fourier_transform	qis-examples/quantum_fourier_transform.ipynb	relocated
applications/python/deutsch_algorithm	qis-examples/deutsch_algorithm.ipynb	relocated
applications/python/grovers	qis-examples/grovers.ipynb	relocated
applications/python/adapt_vqe	chemistry-simulations/adapt_vqe.ipynb	re-authored as teaching module
applications/python/qm_mm_pe	chemistry-simulations/qmmm.ipynb	re-authored as teaching module
applications/python/hybrid_quantum_neural_networks	quantum-machine-learning-and-data-analysis/01_an_introduction_to_hybrid_quantum_neural_networks.ipynb	re-authored as teaching module
applications/python/unitary_compilation_diffusion_models	ai-for-quantum/01_compiling_unitaries_diffusion.ipynb	re-authored as teaching module

Scope

The eight remaining removed notebooks (qaoa, adapt_qaoa, digitized_counterdiabatic_qaoa, cost_minimization, divisive_clustering_coresets, edge_detection, quantum_pagerank, vqe_advanced) have no counterpart in cuda-q-academic and there should be a discussion as to where those old URLs should point or redirect to.

[AnitaGeorge404]

Hi @rogerawong, I’d be interested in contributing to this issue if the team is open to an external PR.

I can work on the notebook stubs/redirect handling and add tests to make sure the affected old documentation paths no longer result in unhelpful 404s. I can also help address the remaining eight notebooks where a destination still needs to be determined.

I've gone through the scope described here, including the nine relocated/reauthored notebooks and their corresponding destinations in cuda-q-academic. I can implement the RST stub pages and the corresponding applications.rst entries, then build the documentation locally to verify that the old paths provide the correct migration guidance and that all destination links resolve correctly.

If the existing docs-notebook-404-stubs branch is intended to be the final implementation, I’d also be happy to build on it and take care of the remaining work and validation.

Please let me know if you’d be happy for me to take this up.