{
-`)
+`),
).toMatchInlineSnapshot(`
"
@@ -66,7 +66,7 @@ describe('sphinxHtmlToMarkdown', () => {
`);
});
- test('remove permalink', async () => {
+ test("remove permalink", async () => {
expect(
await toMd(` {
>
-`)
+`),
).toMatchInlineSnapshot(`""`);
});
- test('extract images', async () => {
+ test("extract images", async () => {
expect(
await sphinxHtmlToMarkdown({
html: `
@@ -113,9 +113,9 @@ describe('sphinxHtmlToMarkdown', () => {
`,
- url: 'http://qiskit.org/docs/quantum-circuit.html',
- imageDestination: '/images/qiskit',
- })
+ url: "http://qiskit.org/docs/quantum-circuit.html",
+ imageDestination: "/images/qiskit",
+ }),
).toMatchInlineSnapshot(`
{
"images": [
@@ -135,7 +135,7 @@ describe('sphinxHtmlToMarkdown', () => {
`);
});
- test('handle tabs', async () => {
+ test("handle tabs", async () => {
expect(
await toMd(` {
@@ -415,7 +415,7 @@ describe('sphinxHtmlToMarkdown', () => {
- `)
+ `),
).toMatchInlineSnapshot(`
"| | |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
@@ -434,7 +434,7 @@ describe('sphinxHtmlToMarkdown', () => {
`);
});
- test('handle <', async () => {
+ test("handle <", async () => {
expect(
await toMd(`
@@ -448,7 +448,7 @@ describe('sphinxHtmlToMarkdown', () => {
- `)
+ `),
).toMatchInlineSnapshot(`
"For the full list of backend attributes, see the IBMBackend class documentation \\<[https://qiskit.org/documentation/apidoc/providers\\_models.html](https://qiskit.org/documentation/apidoc/providers_models.html)>
@@ -459,7 +459,7 @@ describe('sphinxHtmlToMarkdown', () => {
`);
});
- test('handle {', async () => {
+ test("handle {", async () => {
expect(
await toMd(`
@@ -467,14 +467,14 @@ describe('sphinxHtmlToMarkdown', () => {
Can be either (1) a dictionary mapping XX angle values to fidelity at that angle; or
(2) a single float f, interpreted as {pi: f, pi/2: f/2, pi/3: f/3}.
- `)
+ `),
).toMatchInlineSnapshot(`
"**basis\\_fidelity** (*dict | float*) – available strengths and fidelity of each. Can be either (1) a dictionary mapping XX angle values to fidelity at that angle; or (2) a single float f, interpreted as \\{pi: f, pi/2: f/2, pi/3: f/3}.
"
`);
});
- test('translate codeblocks to code fences with lang python', async () => {
+ test("translate codeblocks to code fences with lang python", async () => {
expect(
await toMd(`
@@ -484,7 +484,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angle
filters=lambda x: ("rz" in x.basis_gates )
- `)
+ `),
).toMatchInlineSnapshot(`
"\`\`\`python
QiskitRuntimeService.backends(
@@ -496,7 +496,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angle
`);
});
- test('convert source links', async () => {
+ test("convert source links", async () => {
expect(
(
await sphinxHtmlToMarkdown({
@@ -504,17 +504,17 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angle
IBMBackend.control_channel(qubits)[source]¶
`,
- url: 'https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html',
+ url: "https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html",
baseSourceUrl: `https://github.com/Qiskit/qiskit-ibm-runtime/tree/0.9.2/`,
})
- ).markdown
+ ).markdown,
).toMatchInlineSnapshot(`
"IBMBackend.control\\_channel(*qubits*)[\\[source\\]](https://github.com/Qiskit/qiskit-ibm-runtime/tree/0.9.2/qiskit_ibm_runtime/ibm_backend.py)
"
`);
});
- test('convert class signature headings', async () => {
+ test("convert class signature headings", async () => {
expect(
await toMdWithMeta(`Estimator¶
@@ -572,7 +572,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angleEstimator.circuits¶
@@ -622,7 +622,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angleQuantum circuits that represents quantum states.
Estimator.run¶
@@ -651,7 +651,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angle Estimator.run(circuits, observables, parameter_values=None, **kwargs)[source]¶Submit a request to the estimator primitive program.
EnvironmentOptions.callback¶
@@ -680,7 +680,7 @@ Can be either (1) a dictionary mapping XX angle values to fidelity at that angle EnvironmentOptions.callback: Optional[Callable] = None¶Methods
basis¶
@@ -842,7 +842,7 @@ By default this is sys.stdout.Basis (qiskit_ibm_provider.transpiler.passes.basis)¶
Passes to layout circuits to IBM backend’s instruction sets.
@@ -990,7 +990,7 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"# DAGCircuit
@@ -1032,7 +1032,7 @@ bits.
`);
});
- test('transform dl, dd, dt elements', async () => {
+ test("transform dl, dd, dt elements", async () => {
expect(
await toMd(`-
@@ -1049,7 +1049,7 @@ bits.
Qiskit Runtime (qiskit_ibm_runtime)¶
Modules related to Qiskit Runtime IBM Client.
@@ -1098,7 +1098,7 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"| | |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
@@ -1107,7 +1107,7 @@ bits.
`);
});
- test('transform block math', async () => {
+ test("transform block math", async () => {
expect(
await toMd(`
@@ -1128,7 +1128,7 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"$$
\\begin{split}CCX q_0, q_1, q_2 =
@@ -1152,7 +1152,7 @@ bits.
`);
});
- test('transform admonitions', async () => {
+ test("transform admonitions", async () => {
expect(
await toMd(`
\\[x = \\sum_{i=0}^{n-1} 2^i q_i,\\]
@@ -1171,7 +1171,7 @@ bits.
The global phase gate (\\(e^{i\\theta}\\)).
@@ -1230,7 +1230,7 @@ bits.
Bar has a type and a defualt value
- `)
+ `),
).toMatchInlineSnapshot(`
"
@@ -1281,7 +1281,7 @@ bits.
`);
});
- test('parse deprecations warnings', async () => {
+ test("parse deprecations warnings", async () => {
expect(
await toMd(`
@@ -1289,7 +1289,7 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"Deprecated since version 0.23.0: The method qiskit.circuit.quantumregister.QuantumRegister.qasm() is deprecated as of qiskit-terra 0.23.0. It will be removed no earlier than 3 months after the release date. Correct exporting to OpenQASM 2 is the responsibility of a larger exporter; it cannot safely be done on an object-by-object basis without context. No replacement will be provided, because the premise is wrong.
@@ -1318,7 +1318,7 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"
@@ -1339,7 +1339,7 @@ bits.
`);
});
- test('merge contiguous emphasis', async () => {
+ test("merge contiguous emphasis", async () => {
expect(
await toMd(`
@@ -1347,14 +1347,14 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"* **gate** (*Union\\[*[*Gate*](qiskit.circuit.Gate#qiskit.circuit.Gate "qiskit.circuit.Gate")*, str]*) – Gate information.
"
`);
});
- test('remove spaces from emphashis boundaries', async () => {
+ test("remove spaces from emphashis boundaries", async () => {
expect(
await toMd(`
gate (Union[Gate, str]) – Gate information.
@@ -1362,14 +1362,14 @@ bits.
- `)
+ `),
).toMatchInlineSnapshot(`
"* **gate** ( *Union\\[*[*Gate*](qiskit.circuit.Gate#qiskit.circuit.Gate "qiskit.circuit.Gate")*, str]* ) – Gate information.
"
`);
});
- test('remove gate ( Union[Gate, str] ) – Gate information.
', async () => { + test("remove
", async () => { expect( await toMd(`
@@ -1387,7 +1387,7 @@ compilation flow follows the structure given below:
- `)
+ `),
).toMatchInlineSnapshot(`
"Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and/or to optimize the circuit for execution on present day noisy quantum systems.
@@ -1404,7 +1404,7 @@ compilation flow follows the structure given below:
async function toMd(html: string) {
return (
await sphinxHtmlToMarkdown({
- url: 'https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html',
+ url: "https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html",
html,
})
).markdown;
@@ -1412,7 +1412,7 @@ async function toMd(html: string) {
async function toMdWithMeta(html: string) {
return await sphinxHtmlToMarkdown({
- url: 'https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html',
+ url: "https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.Sampler.html",
html,
});
}
diff --git a/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts b/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
index 30f7d28707..670bcdba0a 100644
--- a/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
+++ b/scripts/lib/sphinx/sphinxHtmlToMarkdown.ts
@@ -10,24 +10,28 @@
// copyright notice, and modified files need to carry a notice indicating
// that they have been altered from the originals.
-import { load } from 'cheerio';
-import { unified } from 'unified';
-import rehypeParse from 'rehype-parse';
-import rehypeRemark from 'rehype-remark';
-import remarkStringify from 'remark-stringify';
-import remarkGfm from 'remark-gfm';
-import { last, first, without, initial, tail } from 'lodash';
-import { defaultHandlers, Handle, toMdast, all } from 'hast-util-to-mdast';
-import { toText } from 'hast-util-to-text';
-import remarkMath from 'remark-math';
-import remarkMdx from 'remark-mdx';
-import { SphinxToMdResult } from './SphinxToMdResult';
-import { PythonObjectMeta } from './PythonObjectMeta';
-import { getLastPartFromFullIdentifier, removePrefix, removeSuffix } from '../stringUtils';
-import { remarkStringifyOptions } from './unifiedParser';
-import { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
-import { visit } from 'unist-util-visit';
-import { Root } from 'mdast';
+import { load } from "cheerio";
+import { unified } from "unified";
+import rehypeParse from "rehype-parse";
+import rehypeRemark from "rehype-remark";
+import remarkStringify from "remark-stringify";
+import remarkGfm from "remark-gfm";
+import { last, first, without, initial, tail } from "lodash";
+import { defaultHandlers, Handle, toMdast, all } from "hast-util-to-mdast";
+import { toText } from "hast-util-to-text";
+import remarkMath from "remark-math";
+import remarkMdx from "remark-mdx";
+import { SphinxToMdResult } from "./SphinxToMdResult";
+import { PythonObjectMeta } from "./PythonObjectMeta";
+import {
+ getLastPartFromFullIdentifier,
+ removePrefix,
+ removeSuffix,
+} from "../stringUtils";
+import { remarkStringifyOptions } from "./unifiedParser";
+import { MdxJsxFlowElement } from "mdast-util-mdx-jsx";
+import { visit } from "unist-util-visit";
+import { Root } from "mdast";
export async function sphinxHtmlToMarkdown(options: {
html: string;
@@ -38,7 +42,12 @@ export async function sphinxHtmlToMarkdown(options: {
baseSourceUrl?: string;
}): PromiseQiskit has four pre-built transpilation pipelines available here:
${$quote.html()}
`); }); - $main.find('.sd-card-body blockquote').each((_, quote) => { + $main.find(".sd-card-body blockquote").each((_, quote) => { const $quote = $page(quote); $quote.replaceWith($quote.children()); }); // add language class to code blocks - $main.find('pre').each((_, pre) => { + $main.find("pre").each((_, pre) => { const $pre = $page(pre); - $pre.replaceWith(`${$pre.html()}${$pre.html()}${$el.html()}
`); }); // delete colons - $main.find('.colon').remove(); + $main.find(".colon").remove(); // translate type headings to titles function findByText(selector: string, text: string) { - return $main.find(selector).filter((i, el) => $page(el).text().trim() === text); + return $main + .find(selector) + .filter((i, el) => $page(el).text().trim() === text); } $main - .find('dl.field-list.simple') + .find("dl.field-list.simple") .toArray() .map((dl) => { const $dl = $page(dl); $dl - .find('dt') + .find("dt") .toArray() .forEach((dt) => { const $dt = $page(dt); @@ -140,7 +153,7 @@ export async function sphinxHtmlToMarkdown(options: { }); $dl - .find('dd') + .find("dd") .toArray() .forEach((dd) => { const $dd = $page(dd); @@ -155,7 +168,7 @@ export async function sphinxHtmlToMarkdown(options: { // members can be recursive, so we need to pick elements one by one const dl = $main .find( - 'dl.py.class, dl.py.property, dl.py.method, dl.py.attribute, dl.py.function, dl.py.exception' + "dl.py.class, dl.py.property, dl.py.method, dl.py.attribute, dl.py.function, dl.py.exception", ) .get(0); @@ -170,65 +183,67 @@ export async function sphinxHtmlToMarkdown(options: { .toArray() .map((child) => { const $child = $page(child); - $child.find('.viewcode-link').closest('a').remove(); - const id = $dl.find('dt.sig-object').attr('id'); + $child.find(".viewcode-link").closest("a").remove(); + const id = $dl.find("dt.sig-object").attr("id"); - if (child.name === 'dt' && $dl.hasClass('class')) { + if (child.name === "dt" && $dl.hasClass("class")) { if (!meta.python_api_type) { - meta.python_api_type = 'class'; + meta.python_api_type = "class"; meta.python_api_name = id; } - findByText('em.property', 'class').remove(); + findByText("em.property", "class").remove(); return `${$child.html()}
${signature}
${getLastPartFromFullIdentifier(id)}
`).insertBefore($dl); + $page( + `${getLastPartFromFullIdentifier(id)}
`, + ).insertBefore($dl); } } - findByText('em.property', 'method').remove(); + findByText("em.property", "method").remove(); return `${$child.html()}
${signature}
${name}
`]; + const output = [ + `${name}
`, + ]; if (type) { output.push(`${type}
${value}
${$child.html()}
${$child.html()}
${$child.html()}
`;
})
- .join('\n');
+ .join("\n");
$dl.replaceWith(`${replacement}
`);
}
// preserve math block whitespace
$main
- .find('div.math')
+ .find("div.math")
.toArray()
.map((el) => {
const $el = $page(el);
@@ -286,31 +303,31 @@ export async function sphinxHtmlToMarkdown(options: {
});
// extract module meta
- const modulePrefix = 'module-';
+ const modulePrefix = "module-";
const moduleIdWithPrefix = $main
.find(`.target, section`)
.toArray()
- .map((el) => $page(el).attr('id'))
+ .map((el) => $page(el).attr("id"))
.find((id) => id?.startsWith(modulePrefix));
if (moduleIdWithPrefix) {
const moduleId = moduleIdWithPrefix.slice(modulePrefix.length);
- meta.python_api_type = 'module';
+ meta.python_api_type = "module";
meta.python_api_name = moduleId;
}
// Update headings of modules
- if (meta.python_api_type === 'module') {
+ if (meta.python_api_type === "module") {
$main
- .find('h1,h2')
+ .find("h1,h2")
.toArray()
.forEach((el) => {
const $el = $page(el);
- const $a = $page($el.find('a'));
+ const $a = $page($el.find("a"));
const signature = $a.text();
$a.remove();
let title = $el.text();
- title = title.replace('()', '');
+ title = title.replace("()", "");
let replacement = `<${el.tagName}>${title}`;
if (signature.trim().length > 0) {
replacement += `${signature}