Add script to update all non-API links to guides/ (Qiskit#1498)

Closes Qiskit#1460

This PR adds a script to update all the non-API links to point to
`guides/` taking into account that all the files will now be in the same
folder, and there's no need to preserve the relative paths

scripts/patterns-reorg/main.py

@@ -23,6 +23,9 @@
 from entries import TOP_LEVEL_ENTRIES
 from deleted_entries import DELETED_PAGES
 
+OLD_FOLDERS = ["start", "run", "verify", "transpile", "build"]
+REDIRECTS = determine_redirects((*TOP_LEVEL_ENTRIES, *DELETED_PAGES))
+
 
 def create_parser() -> ArgumentParser:
     parser = ArgumentParser()
@@ -54,13 +57,12 @@ def write_guides_dir() -> None:
 
 def write_redirects_file() -> None:
     fp = Path("scripts/patterns-reorg/redirects.json")
-    redirects = determine_redirects((*TOP_LEVEL_ENTRIES, *DELETED_PAGES))
-    text = json.dumps(redirects, indent=2) + "\n"
+    text = json.dumps(REDIRECTS, indent=2) + "\n"
     fp.write_text(text)
 
 
 def delete_existing_guides() -> None:
-    for d in ["start", "run", "verify", "transpile", "build"]:
+    for d in OLD_FOLDERS:
         shutil.rmtree(Path("docs", d))
 
 

scripts/patterns-reorg/models.py

@@ -115,12 +115,15 @@ def filter_entries(
         result.append(new_entry)
     return tuple(result)
 
-def _add_redirect_to_dict(redirects: dict[str, str], old_url: str, redirect_to: str)-> None:
+
+def _add_redirect_to_dict(
+    redirects: dict[str, str], old_url: str, redirect_to: str
+) -> None:
     redirects[old_url] = redirect_to
     # We need to add two links for each index entry because we can
     # have two links possible. For example, `/run/index` and `/run`
     # point to the same page.
-    old_folder, old_file_name = old_url.split('/')
+    old_folder, old_file_name = old_url.split("/")
     if old_file_name == "index":
         redirects[f"{old_folder}"] = redirect_to
 
@@ -132,16 +135,16 @@ def determine_redirects(
     for entry in entries:
         if isinstance(entry, Entry):
             result.update(determine_redirects(entry.children))
-    
+
             if entry.slug is None or not entry.from_file:
                 continue
-            
+
             old_url = str(PurePath(entry.from_file).with_suffix(""))
             redirect_to = f"{prefix}{entry.slug.removeprefix('/')}"
             _add_redirect_to_dict(result, old_url, redirect_to)
 
-        elif isinstance(entry, DeletedPage):    
+        elif isinstance(entry, DeletedPage):
             redirect_to = f"{prefix}{entry.redirect_to.removeprefix('/')}"
             _add_redirect_to_dict(result, entry.old_slug, redirect_to)
-    
+
     return result

scripts/patterns-reorg/update_internal_links.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3.11
+
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2024.
+#
+# This code is licensed under the Apache License, Version 2.0. You may obtain a
+# copy of this license in the LICENSE file in the root directory of this source
+# tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this copyright
+# notice, and modified files need to carry a notice indicating that they have
+# been altered from the originals.
+
+from __future__ import annotations
+
+import re
+import glob
+from pathlib import Path
+from main import OLD_FOLDERS, REDIRECTS
+
+
+def update_link(markdown: str, folder: str, link: str) -> str:
+    anchor_index = link.find("#")
+
+    if link.startswith("http") or anchor_index == 0:
+        return markdown
+
+    if anchor_index == -1:
+        link_without_anchor = link
+        anchor = ""
+    else:
+        link_without_anchor = link[:anchor_index]
+        anchor = link[anchor_index:]
+
+    link_split = link_without_anchor.split("/")
+    if link.startswith("/") or link.startswith("../"):
+        search_key = f"{link_split[-2]}/{link_split[-1]}"
+    else:
+        search_key = f"{folder}/{link_split[-1]}"
+
+    if search_key not in REDIRECTS:
+        return markdown
+
+    new_link = REDIRECTS[search_key]
+    if new_link == "":
+        new_link = "/guides"
+
+    redirect_to = f"{new_link}{anchor}"
+    # If the link doesn't change we return without changing anything
+    if link == redirect_to:
+        return markdown
+
+    return markdown.replace(link, f"./{redirect_to}")
+
+
+def main() -> None:
+    inline_link_re = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+    for folder in OLD_FOLDERS:
+        for file_path in glob.glob(f"docs/{folder}/*"):
+            file = Path(file_path)
+            markdown = file.read_text()
+            markdown = re.sub(
+                inline_link_re,
+                lambda m: update_link(m[0], folder, m[2]),
+                markdown,
+            )
+            file.write_text(markdown)
+
+
+if __name__ == "__main__":
+    main()