Add tests showing that sphinx.ext.linkcode can be handled (#849)

Part of #517. Turns out
that we already do the right thing! That's because both
`sphinx.ext.viewcode` and `sphinx.ext.linkcode` use the same HTML
structure.

This PR adds tests and better comments to make that clear.

The key insight is that we don't need to change the URLs at all, unlike
using `sphinx.ext.viewcode`. We assume the source repositories are
giving us valid URLs.

scripts/lib/api/processHtml.test.ts

@@ -235,6 +235,7 @@ test("replaceSourceLinksWithGitHub()", () => {
   // Assumes that removeHtmlExtensionsInRelativeLinks() has already removed .html from the URL.
   const doc = Doc.load(
     `<a href="../_modules/my_quantum_project/my_file#IBMBackend"></a>
+    <a class="reference external" href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101"></a>
     <a href="#my_quantum_project.IBMBackend"></a>`,
   );
   replaceViewcodeLinksWithGitHub(
@@ -245,6 +246,7 @@ test("replaceSourceLinksWithGitHub()", () => {
   );
   doc.expectHtml(
     `<a href="https://github.com/Qiskit/my-project/tree/stable/0.9/my_quantum_project/my_file.py"></a>
+    <a class="reference external" href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101"></a>
     <a href="#my_quantum_project.IBMBackend"></a>`,
   );
 });
@@ -322,7 +324,7 @@ describe("prepareGitHubLink()", () => {
     doc.expectHtml(html);
   });
 
-  test("link", () => {
+  test("link from sphinx.ext.viewcode", () => {
     const doc = Doc.load(
       `<span class="pre">None</span><span class="sig-paren">)</span><a class="reference internal" href="https://ibm.com/my_link"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#qiskit_ibm_runtime.IBMBackend" title="Link to this definition">#</a>`,
     );
@@ -334,6 +336,19 @@ describe("prepareGitHubLink()", () => {
       `<span class="pre">None</span><span class="sig-paren">)</span><a class="headerlink" href="#qiskit_ibm_runtime.IBMBackend" title="Link to this definition">#</a>`,
     );
   });
+
+  test("link from sphinx.ext.linkcode", () => {
+    const doc = Doc.load(
+      `<span class="pre">None</span><span class="sig-paren">)</span><a class="reference external" href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#qiskit_ibm_runtime.IBMBackend" title="Link to this definition">#</a>`,
+    );
+    const result = prepareGitHubLink(doc.$, doc.$main);
+    expect(result).toEqual(
+      `<a href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101" title="view source code">GitHub</a>`,
+    );
+    doc.expectHtml(
+      `<span class="pre">None</span><span class="sig-paren">)</span><a class="headerlink" href="#qiskit_ibm_runtime.IBMBackend" title="Link to this definition">#</a>`,
+    );
+  });
 });
 
 describe("processMembersAndSetMeta()", () => {

scripts/lib/api/processHtml.ts

@@ -162,12 +162,14 @@ export function addLanguageClassToCodeBlocks(
 }
 
 /**
- * Redirect URLS from sphinx.ext.viewcode to instead go to GitHub.
+ * Redirect URLS from `sphinx.ext.viewcode` to instead go to GitHub.
  *
  * These URLs will only go to the overall source code file, not the specific lines
  * of code. This function only changes the URLs; the DOM still needs to be modified
  * to remove the original `[source]` anchor element from Sphinx with our own `GitHub`
  * anchor element in the correct location.
+ *
+ * This does not impact links from `sphinx.ext.linkcode`.
  */
 export function replaceViewcodeLinksWithGitHub(
   $: CheerioAPI,
@@ -388,6 +390,9 @@ export function processMembersAndSetMeta(
  *
  * This returns the HTML string, rather than directly inserting into the HTML, because the insertion
  * logic is most easily handled by the calling code.
+ *
+ * This function works the same regardless of whether the Sphinx build used `sphinx.ext.viewcode`
+ * or `sphinx.ext.linkcode` because they have the same HTML structure.
  */
 export function prepareGitHubLink($: CheerioAPI, $child: Cheerio<any>): string {
   const originalLink = $child.find(".viewcode-link").closest("a");