From 8aa63e807f3dd4ee86f489dba4c8651e8f54b102 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 17:21:11 +0200 Subject: [PATCH 1/6] update docker image hash --- start | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/start b/start index 8f813fd7a6f..5926c0ea273 100755 --- a/start +++ b/start @@ -17,7 +17,7 @@ import sys from pathlib import Path # Get the latest digest by running `docker pull icr.io/qc-open-source-docs-public/preview:latest`. -IMAGE_DIGEST = "sha256:5336ed8710d3822e6409381e7c4a6d60d7860a2228e22a0f2b2de26c68f54a0b" +IMAGE_DIGEST = "sha256:350f6fbb4d05a7c55bb9edcc9505df437380e5c0a8fbee8d568d7ff7bedd20e5" # Docker on Windows uses `/` rather than `\`, so we need to call `.as_posix()`: # https://medium.com/@kale.miller96/how-to-mount-your-current-working-directory-to-your-docker-container-in-windows-74e47fa104d7 From c7bde8349f8900fb8b087385ae44b3b2537a09c6 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 17:23:17 +0200 Subject: [PATCH 2/6] update package.json dependencies latest commit hash --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 9e5bd796416..e9116ceae99 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "check:spelling": "node node_modules/qiskit-documentation/dist/js/commands/checkSpelling.js --config qiskit-documentation/scripts/config/cspell/cSpell.json" }, "dependencies": { - "qiskit-documentation": "qiskit/documentation#7c4975c83b4812563fff721cb0d081b358a20947" + "qiskit-documentation": "qiskit/documentation#b7584eeb18fe1f32a5bfaa8e532d9601f67c904a" }, "devDependencies": {} } From b7a6ff6755ae73a1f3991091b1117517dfc63b5d Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 17:55:50 +0200 Subject: [PATCH 3/6] update packag-lock.json --- package-lock.json | 50 ++++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/package-lock.json b/package-lock.json index eac29ffe1b9..57dc747e204 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.1.0", "license": "Apache-2.0", "dependencies": { - "qiskit-documentation": "qiskit/documentation#7c4975c83b4812563fff721cb0d081b358a20947" + "qiskit-documentation": "qiskit/documentation#b7584eeb18fe1f32a5bfaa8e532d9601f67c904a" }, "devDependencies": {} }, @@ -188,8 +188,7 @@ "version": "4.0.17", "resolved": "https://registry.npmjs.org/@cspell/dict-css/-/dict-css-4.0.17.tgz", "integrity": "sha512-2EisRLHk6X/PdicybwlajLGKF5aJf4xnX2uuG5lexuYKt05xV/J/OiBADmi8q9obhxf1nesrMQbqAt+6CsHo/w==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@cspell/dict-dart": { "version": "2.3.0", @@ -309,15 +308,13 @@ "version": "4.0.11", "resolved": "https://registry.npmjs.org/@cspell/dict-html/-/dict-html-4.0.11.tgz", "integrity": "sha512-QR3b/PB972SRQ2xICR1Nw/M44IJ6rjypwzA4jn+GH8ydjAX9acFNfc+hLZVyNe0FqsE90Gw3evLCOIF0vy1vQw==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@cspell/dict-html-symbol-entities": { "version": "4.0.3", "resolved": "https://registry.npmjs.org/@cspell/dict-html-symbol-entities/-/dict-html-symbol-entities-4.0.3.tgz", "integrity": "sha512-aABXX7dMLNFdSE8aY844X4+hvfK7977sOWgZXo4MTGAmOzR8524fjbJPswIBK7GaD3+SgFZ2yP2o0CFvXDGF+A==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@cspell/dict-java": { "version": "5.0.11", @@ -488,8 +485,7 @@ "version": "3.2.1", "resolved": "https://registry.npmjs.org/@cspell/dict-typescript/-/dict-typescript-3.2.1.tgz", "integrity": "sha512-jdnKg4rBl75GUBTsUD6nTJl7FGvaIt5wWcWP7TZSC3rV1LfkwvbUiY3PiGpfJlAIdnLYSeFWIpYU9gyVgz206w==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@cspell/dict-vue": { "version": "3.0.4", @@ -779,7 +775,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz", "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -823,8 +818,7 @@ "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", - "license": "Python-2.0" + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" }, "node_modules/array-timsort": { "version": "1.0.3", @@ -2224,10 +2218,19 @@ } }, "node_modules/js-yaml": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz", - "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==", - "license": "MIT", + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.2.0.tgz", + "integrity": "sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/nodeca" + } + ], "dependencies": { "argparse": "^2.0.1" }, @@ -2294,10 +2297,9 @@ } }, "node_modules/lodash-es": { - "version": "4.17.21", - "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", - "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==", - "license": "MIT" + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz", + "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==" }, "node_modules/longest-streak": { "version": "3.1.0", @@ -4233,8 +4235,8 @@ }, "node_modules/qiskit-documentation": { "version": "0.1.0", - "resolved": "git+ssh://git@github.com/qiskit/documentation.git#7c4975c83b4812563fff721cb0d081b358a20947", - "integrity": "sha512-Z/Vtu01Nk9QYDGxR35+ZL8y+42/hR8bve/l04Lnoz/F/RYRnFegG0ixLQJVWx6DLKu4o54MCI0EiAd1tJnHVPg==", + "resolved": "git+ssh://git@github.com/qiskit/documentation.git#b7584eeb18fe1f32a5bfaa8e532d9601f67c904a", + "integrity": "sha512-ghmQbHAp0P1FezFbCXm583/P8HQopbgoInq9SLfJseMAm63HdslPvmZogZFkGgo6+G2+sLAUH8Kq1/I7UqkpXg==", "license": "Apache-2.0", "dependencies": { "@qiskit/mdx-link-extract": "^1.2.0", @@ -4248,8 +4250,8 @@ "hast-util-to-text": "^3.1.0", "is-absolute-url": "^4.0.1", "jest-diff": "^30.3.0", - "js-yaml": "^4.1.1", - "lodash-es": "^4.17.21", + "js-yaml": "^4.2.0", + "lodash-es": "^4.18.1", "mdast": "^3.0.0", "mkdirp": "^3.0.1", "p-map": "^6.0.0", From 2248e7fa7ea1d9d129b3bcafb2d804234277c1fb Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 18:42:22 +0200 Subject: [PATCH 4/6] update tutorial template --- .../template-for-function-name-tutorial.ipynb | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/template-for-function-name-tutorial.ipynb b/docs/tutorials/template-for-function-name-tutorial.ipynb index 7c54bdb1da6..e78e80395fa 100644 --- a/docs/tutorials/template-for-function-name-tutorial.ipynb +++ b/docs/tutorials/template-for-function-name-tutorial.ipynb @@ -12,7 +12,7 @@ "\n", "\n", "# TODO add the title\n", - "> Replace the word 'Title' with the actual tutorial title. Create a brief title. The naming should be related to the *workflow* only and not the tools." + ">Create a brief title. The naming should be related to the *workflow* only and not the tools." ] }, { @@ -26,6 +26,22 @@ "> Replace processor_name with the processor type of the QPU you used (bird name) to run the tutorial." ] }, + { + "cell_type": "markdown", + "id": "21156b6f", + "metadata": {}, + "source": [ + "## Learning outcomes\n", + "\n", + "> Summarize here in bullet points what the reader will learn while doing this tutorial\n", + "\n", + "## Prerequisites\n", + "\n", + "It is important to have familiarity with the following before starting this tutorial.\n", + "\n", + "> List here relevant resources that prepare the user for this tutorial" + ] + }, { "cell_type": "markdown", "id": "8bf80006", @@ -150,11 +166,11 @@ "id": "2cb5785c", "metadata": {}, "source": [ - "## Tutorial survey\n", - "\n", - "Please take a minute to provide feedback on this tutorial. Your insights will help us improve our content offerings and user experience.\n", - "\n", - "[Link to survey](https://your.feedback.ibm.com/jfe/form/SV_3BLFkNVEuh0QBWm)" + "## Next steps\n", + "\n", + "- Link to the documentation for this function (found in `docs/guides/`)\n", + "(List other documentation, tutorials, or papers here that are relevant to this tutorial.)\n", + "" ] } ], From dde52a96ece952df7a13ca6b935b190865ceee65 Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 18:42:32 +0200 Subject: [PATCH 5/6] add API reference --- docs/api/functions/API-REFERENCE-TEMPLATE.mdx | 295 ++++++++++++++++++ docs/api/functions/_toc.json | 33 ++ docs/api/functions/index.mdx | 10 + 3 files changed, 338 insertions(+) create mode 100644 docs/api/functions/API-REFERENCE-TEMPLATE.mdx create mode 100644 docs/api/functions/_toc.json create mode 100644 docs/api/functions/index.mdx diff --git a/docs/api/functions/API-REFERENCE-TEMPLATE.mdx b/docs/api/functions/API-REFERENCE-TEMPLATE.mdx new file mode 100644 index 00000000000..b31422af088 --- /dev/null +++ b/docs/api/functions/API-REFERENCE-TEMPLATE.mdx @@ -0,0 +1,295 @@ +--- +title: "[Full Qiskit function name, including vendor name] API reference" +description: "API reference for [Full Qiskit Function name, including vendor name], including inputs, outputs, and configuration options" +--- + +# [Full Qiskit Function name] API reference + +{/* + In the card component below, leave the title and description fields exactly as they appear here. Edit only the `href`, `analyticsName`, and `linkText` fields to link to the guide for your Qiskit Function. +*/} + + + + + +{/* + LINKS + You can link to related content *within* IBM Quantum Platform using the following markdown syntax (note there is no file extension at the end of links): + - [Guides](/docs/guides/example) + - [Tutorials](/docs/tutorials/example) + - [API references](/docs/api/api-name/example) + - [Learning](learning/courses/course-name/example) + + **Important** - if you copy and paste a link, it might automatically contain a globalization indicator (e.g., `en/`, `de/`). Remove this when you paste a link in your documentation (it will also raise an error in our lint checker). + + You can link to external content using markdown like [this](https://arxiv.org/) +*/} + +{/* + OPTIONAL: ADMONITION SECTIONS + Use these highlight important information. Examples uses + - Limitations or constraints (type="caution") + - Important prerequisites (type="note") + - Tips for getting started (type="tip") + - How options interact with each other + - Defaults and precedence rules + - Links to related guides or documentation +*/} + + + [If applicable, describe important information about this API.] + + +## Inputs + +{/* + INPUTS SECTION + This section documents all parameters the API accepts. + Organize parameters logically: + - Required parameters first + - Optional parameters second + - Complex/nested parameters (like options) can have their own subsection + + For APIs with many inputs, you can add a brief intro sentence explaining + the organization of inputs. +*/} + +See the following list for all input parameters this API accepts. + +{/* + ATTRIBUTE COMPONENT FOR A SIMPLE INPUT + + attributeTypeHint (required): Shows the data type. + - Primitive types: "str", "int", "float", "bool" + - Collections: "list[str]", "dict[str, Any]", "Iterable[SomeType]" + - Union types: "str or None", "int or float" + - Custom types: "QuantumCircuit", "EstimatorPubLike", "SparsePauliOp" + + attributeValue (optional): Shows the default value if one exists. + - If a parameter is required, omit attributeValue + - Examples: "True", "1000", "None", "least busy backend" + + Content: Provide a clear description. Include: + - What the parameter does + - Any constraints or valid values + - "Required: Yes/No" + - An example (actual value or type example) + + Supported markdown: bold, links, code blocks, lists +*/} + +### `required_parameter` + + +Description of what this parameter does and when to use it. Include any constraints or special considerations. +- Required: Yes +- Example: `my_value` + + +### `another_parameter` + + +Description of this parameter. Explain what the list should contain and how it's used. +- Required: No +- Example: `[1, 2, 3]` + + +### `optional_parameter_with_default` + + +Description of this parameter. Mention that it has a default value and what that value is. +- Required: No +- Example: `custom_value` + + +### Options + +{/* + OPTIONS SUBSECTION + Use this when the API accepts a complex options parameter (usually a `dict`). + Include an explanation of how options are structured, then document each option. +*/} + + +Input options for [what this controls]. Options are specified as a nested dictionary. See the [options list](#options-list) below for details and default values. +- Required: No +- Example: `{"option1": true, "option2": "value"}` + + + +#### Options list + +##### `simple_option` + +{/* + SIMPLE OPTIONS: Use Attribute directly within an h5 heading for each option. + Show type, default value, valid choices, and a clear description. +*/} + + +Description of this option. Explain what it controls and the impact of changing it. +- Choices: Integer > 0 + + +##### `flag_option` + + +Whether to enable/disable [what this controls]. +- Choices: True/False + + +##### `choice_option` + + +Description of this option. List the valid choices and what each one does. +- Choices: `option_a` / `option_b` / `option_c` + + +##### `grouped_options` + +{/* + GROUPED/NESTED OPTIONS + When options have sub-options (e.g., mitigation, resilience, etc.), + use `LeftColoredBar` to group them visually and hierarchically. + The color attribute can be "blue" or "purple". +*/} + + + `sub_option_one` + + Description of this sub-option. Explain what it controls. + - Choices: True/False + + + `sub_option_two` + + Description of this sub-option and its choices. + - Choices: `linear` / `exponential` / `polynomial` + + + `nested_group` + {/* + DEEPLY NESTED OPTIONS + For complex hierarchies, nest LeftColoredBar within LeftColoredBar. + Use a different color (e.g., "purple") to visually distinguish nesting levels. + */} + + `deep_nested_option` + + Description of this deeply nested option. + - Choices: Integer > 0 + + + `another_deep_option` + + Description of this deeply nested option with a list default. + - Choices: List of floats, each >= 1 + + + + +## Outputs + +{/* + OUTPUTS SECTION + Document the structure and contents of the API response. + + Two common patterns: + + 1. SINGLE RESPONSE TYPE: + If the API returns a single object/type, start with a brief intro explaining + what that type is, then use LeftColoredBar to document its fields. + + 2. CONDITIONAL RESPONSE: + Some APIs return different structures based on options (e.g., transpile_only=True). + Use subsections and Admonitions to clarify which output goes with which mode. +*/} + +The output of this API is a `[ReturnTypeName]` object containing solution and metadata. The structure may vary depending on execution mode (e.g., if certain options are set). + + +Description of the main output structure. Explain what the response contains at a high level and how to access fields. +- Example: `{"result": 0.5, "error": 0.01, "metadata": {...}}` + + +### Output structure + +{/* + Use LeftColoredBar to organize output fields into a visual hierarchy. + Each field should have an Attribute with type, description, and optionally an example. +*/} + + + `result_field` + + Description of what this field represents and how to interpret its value. + - Example: `0.5` + + + `solution` + + Description of the solution dictionary. Explain what keys it contains. + - Example: `{"bitstring": "11100", "cost": -13.8}` + + + `metadata` + {/* + NESTED OUTPUT FIELDS + For complex outputs with nested structures, use nested LeftColoredBar. + Use a different color to show the hierarchy level. + */} + + `execution_time` + + How long the operation took in seconds. + - Example: `1.234` + + + `timestamp` + + When the operation completed (ISO 8601 format). + - Example: `"2024-01-15T10:30:00Z"` + + + `resource_usage` + + Information about resources consumed during execution. + - Example: `{"qpu_time": 5.2, "total_time": 10.1}` + + + + +### Alternative output structures + +{/* + OPTIONAL: If the API returns different structures based on options, + document each variant with a subsection and Admonition. +*/} + + +When [`transpile_only=True`](#transpile_only), the output contains circuit analysis instead of solution results: + +- `transpilation_info`: Dictionary with `best_seed`, `transpilation_time_seconds`, and `transpiled_circuit` details +- `transpiled_circuit`: Contains `depth`, `gate_count`, `num_qubits`, `width`, and `operations` + + +## Error handling + +{/* + OPTIONAL: Include information about errors, exceptions, or status codes + if your API documents these. This helps users understand what can go wrong. +*/} + + +Describe common error conditions and how to handle them. Examples: +- What happens if an invalid parameter is passed +- When the API might fail or timeout +- Link to [error code reference](/docs/errors) if available + \ No newline at end of file diff --git a/docs/api/functions/_toc.json b/docs/api/functions/_toc.json new file mode 100644 index 00000000000..c951f765e46 --- /dev/null +++ b/docs/api/functions/_toc.json @@ -0,0 +1,33 @@ +{ + "title": "Qiskit Functions", + "children": [ + { + "title": "API index", + "url": "/docs/api/functions" + }, + { + "title": "Circuit functions", + "untranslatable": true, + "children": [ + { + "title": "function-name: a Qiskit Function by partner-name", + "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", + "untranslatable": true + } + ], + "collapsible": false + }, + { + "title": "Application functions", + "untranslatable": true, + "children": [ + { + "title": "function-name: a Qiskit Function by partner-name", + "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", + "untranslatable": true + } + ], + "collapsible": false + } + ] +} \ No newline at end of file diff --git a/docs/api/functions/index.mdx b/docs/api/functions/index.mdx new file mode 100644 index 00000000000..2e537cf2522 --- /dev/null +++ b/docs/api/functions/index.mdx @@ -0,0 +1,10 @@ +--- +title: Qiskit Functions API reference +description: Index of all inputs and outputs of the Qiskit Functions +--- + + + +# Qiskit Functions API reference + +Choose a Qiskit Function from the table of contents to see its API reference documentation. To read more about Qiskit Functions, visit the [Introduction to Qiskit Functions](/docs/guides/functions). From 49dea360a29a93eac25d90c8ee4d2af43252b6bc Mon Sep 17 00:00:00 2001 From: Junye Huang Date: Fri, 26 Jun 2026 18:57:22 +0200 Subject: [PATCH 6/6] fix api toc json indentation --- docs/api/functions/_toc.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/functions/_toc.json b/docs/api/functions/_toc.json index c951f765e46..fc2e62369d1 100644 --- a/docs/api/functions/_toc.json +++ b/docs/api/functions/_toc.json @@ -11,7 +11,7 @@ "children": [ { "title": "function-name: a Qiskit Function by partner-name", - "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", + "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", "untranslatable": true } ], @@ -23,7 +23,7 @@ "children": [ { "title": "function-name: a Qiskit Function by partner-name", - "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", + "url": "/docs/api/functions/API-REFERENCE-TEMPLATE", "untranslatable": true } ],