From ec42361ea5b37ef287fbd816ac93bd436e2e19f5 Mon Sep 17 00:00:00 2001 From: "Kevin J. Sung" Date: Mon, 26 Feb 2024 17:36:55 -0500 Subject: [PATCH] enforce 50 <= description length <= 160 (#890) Fixes #327 --- docs/api/migration-guides/qiskit-1.0-features.mdx | 2 +- docs/api/migration-guides/qiskit-1.0.mdx | 2 +- .../migration-guides/qiskit-algorithms-module.mdx | 2 +- docs/api/migration-guides/qiskit-opflow-module.mdx | 2 +- docs/build/circuit-construction.ipynb | 2 +- docs/build/interoperate-qiskit-qasm2.mdx | 2 +- docs/build/interoperate-qiskit-qasm3.mdx | 2 +- docs/build/qasm-feature-table.mdx | 2 +- docs/run/configure-error-mitigation.mdx | 2 +- docs/run/configure-runtime-compilation.mdx | 2 +- docs/run/primitives-examples.mdx | 2 +- docs/run/primitives-get-started.mdx | 2 +- docs/run/quantum-serverless.mdx | 2 +- docs/run/run-jobs-batch.mdx | 2 +- docs/run/run-jobs-in-session.mdx | 2 +- docs/run/sessions.mdx | 2 +- docs/start/configure-qiskit-local.mdx | 2 +- docs/start/index.mdx | 2 +- .../defaults-and-configuration-options.mdx | 2 +- docs/transpile/index.mdx | 2 +- docs/transpile/set-optimization.mdx | 2 +- docs/transpile/transpiler-stages.ipynb | 2 +- docs/verify/index.mdx | 2 +- docs/verify/simulate-with-qiskit-primitives.mdx | 2 +- docs/verify/stabilizer-circuit-simulation.ipynb | 2 +- scripts/commands/checkMetadata.ts | 13 +++++++++---- 26 files changed, 34 insertions(+), 29 deletions(-) diff --git a/docs/api/migration-guides/qiskit-1.0-features.mdx b/docs/api/migration-guides/qiskit-1.0-features.mdx index f2407869776..f8d106ed571 100644 --- a/docs/api/migration-guides/qiskit-1.0-features.mdx +++ b/docs/api/migration-guides/qiskit-1.0-features.mdx @@ -1,6 +1,6 @@ --- title: Qiskit 1.0 feature migration guide -description: Adapt to feature changes with Qiskit 1.0 +description: Description of feature changes introduced in Qiskit 1.0 and how to update your code to work with them. --- # Qiskit 1.0 feature changes diff --git a/docs/api/migration-guides/qiskit-1.0.mdx b/docs/api/migration-guides/qiskit-1.0.mdx index 8b6c518d542..7c3212ab46b 100644 --- a/docs/api/migration-guides/qiskit-1.0.mdx +++ b/docs/api/migration-guides/qiskit-1.0.mdx @@ -1,6 +1,6 @@ --- title: Qiskit 1.0 migration guide -description: Update your project to use Qiskit 1.0 +description: How to update your project so that it works with Qiskit 1.0. --- # Qiskit 1.0 migration guide diff --git a/docs/api/migration-guides/qiskit-algorithms-module.mdx b/docs/api/migration-guides/qiskit-algorithms-module.mdx index 744723d80ac..96f820028b9 100644 --- a/docs/api/migration-guides/qiskit-algorithms-module.mdx +++ b/docs/api/migration-guides/qiskit-algorithms-module.mdx @@ -1,6 +1,6 @@ --- title: qiskit.algorithms migration guide -description: Use the new interface for `qiskit.algorithms` +description: How to update your code to use the new interface for `qiskit.algorithms`. --- # Algorithms migration guide diff --git a/docs/api/migration-guides/qiskit-opflow-module.mdx b/docs/api/migration-guides/qiskit-opflow-module.mdx index 2f41fdd3023..94df99c3ef6 100644 --- a/docs/api/migration-guides/qiskit-opflow-module.mdx +++ b/docs/api/migration-guides/qiskit-opflow-module.mdx @@ -1,6 +1,6 @@ --- title: qiskit.opflow migration guide -description: Stop using the deprecated `qiskit.opflow` module +description: How to update your code to stop using the deprecated `qiskit.opflow` module. --- # Opflow migration guide diff --git a/docs/build/circuit-construction.ipynb b/docs/build/circuit-construction.ipynb index cf0185e8ce7..972a6a3b0d2 100644 --- a/docs/build/circuit-construction.ipynb +++ b/docs/build/circuit-construction.ipynb @@ -458,7 +458,7 @@ } ], "metadata": { - "description": "How to create and manipulate circuits in Qiskit", + "description": "How to construct and visualize quantum circuits in Qiskit.", "kernelspec": { "display_name": "Python 3", "language": "python", diff --git a/docs/build/interoperate-qiskit-qasm2.mdx b/docs/build/interoperate-qiskit-qasm2.mdx index 275f0335b32..e8500887387 100644 --- a/docs/build/interoperate-qiskit-qasm2.mdx +++ b/docs/build/interoperate-qiskit-qasm2.mdx @@ -1,6 +1,6 @@ --- title: OpenQASM 2 and Qiskit -description: Convert code between OpenQASM 2 and Qiskit +description: How to convert code between OpenQASM 2 and Qiskit. --- diff --git a/docs/build/interoperate-qiskit-qasm3.mdx b/docs/build/interoperate-qiskit-qasm3.mdx index 77937756c39..bce2327346a 100644 --- a/docs/build/interoperate-qiskit-qasm3.mdx +++ b/docs/build/interoperate-qiskit-qasm3.mdx @@ -1,6 +1,6 @@ --- title: OpenQASM 3 and Qiskit -description: Convert code between OpenQASM 3 and Qiskit +description: How to convert code between OpenQASM 3 and Qiskit. --- diff --git a/docs/build/qasm-feature-table.mdx b/docs/build/qasm-feature-table.mdx index 873c849cbc7..98836713f1d 100644 --- a/docs/build/qasm-feature-table.mdx +++ b/docs/build/qasm-feature-table.mdx @@ -1,6 +1,6 @@ --- title: OpenQASM 3 feature table -description: A list of the OpenQASM 3 language features +description: A table of the language features included in OpenQASM 3. --- diff --git a/docs/run/configure-error-mitigation.mdx b/docs/run/configure-error-mitigation.mdx index 3c4df8e119b..5515a52ec0f 100644 --- a/docs/run/configure-error-mitigation.mdx +++ b/docs/run/configure-error-mitigation.mdx @@ -1,6 +1,6 @@ --- title: Configure error mitigation -description: Configure error mitigation with Qiskit Runtime +description: How to configure error mitigation with Qiskit Runtime. --- # Configure error mitigation for Qiskit Runtime diff --git a/docs/run/configure-runtime-compilation.mdx b/docs/run/configure-runtime-compilation.mdx index c673d0ff7a9..bca59f8a4b0 100644 --- a/docs/run/configure-runtime-compilation.mdx +++ b/docs/run/configure-runtime-compilation.mdx @@ -1,6 +1,6 @@ --- title: Configure runtime compilation -description: How to use runtime compilation techniques +description: How to configure runtime compilation in Qiskit Runtime. --- diff --git a/docs/run/primitives-examples.mdx b/docs/run/primitives-examples.mdx index a9500fe2cca..79810c66164 100644 --- a/docs/run/primitives-examples.mdx +++ b/docs/run/primitives-examples.mdx @@ -1,6 +1,6 @@ --- title: Primitives examples -description: Practical examples of primitive usage +description: Practical examples of using primitives in Qiskit Runtime. --- diff --git a/docs/run/primitives-get-started.mdx b/docs/run/primitives-get-started.mdx index 2c03da0b364..c290deca1da 100644 --- a/docs/run/primitives-get-started.mdx +++ b/docs/run/primitives-get-started.mdx @@ -1,6 +1,6 @@ --- title: Get started with primitives -description: Use Qiskit Runtime Estimator and Sampler +description: How to use the Estimator and Sampler primitives in Qiskit Runtime. --- diff --git a/docs/run/quantum-serverless.mdx b/docs/run/quantum-serverless.mdx index f46d1ab1aca..9deca28df5f 100644 --- a/docs/run/quantum-serverless.mdx +++ b/docs/run/quantum-serverless.mdx @@ -1,6 +1,6 @@ --- title: Run workloads remotely with Quantum Serverless -description: Run workloads remotely with Quantum Serverless +description: How to run quantum computing workloads remotely using Quantum Serverless. --- # Run workloads remotely with Quantum Serverless diff --git a/docs/run/run-jobs-batch.mdx b/docs/run/run-jobs-batch.mdx index e07347f00d0..bdb1923ef3f 100644 --- a/docs/run/run-jobs-batch.mdx +++ b/docs/run/run-jobs-batch.mdx @@ -1,6 +1,6 @@ --- title: Run jobs in a batch -description: How to run jobs in batch mode. +description: How to run quantum computing jobs in batch mode using Qiskit Runtime. --- diff --git a/docs/run/run-jobs-in-session.mdx b/docs/run/run-jobs-in-session.mdx index 1f6786a7de3..2068e34b586 100644 --- a/docs/run/run-jobs-in-session.mdx +++ b/docs/run/run-jobs-in-session.mdx @@ -1,6 +1,6 @@ --- title: Run jobs in a session -description: Run a job in a session +description: How to run a quantum computing job in a Qiskit Runtime session. --- diff --git a/docs/run/sessions.mdx b/docs/run/sessions.mdx index 3bb538355cd..a30f8eb7505 100644 --- a/docs/run/sessions.mdx +++ b/docs/run/sessions.mdx @@ -1,6 +1,6 @@ --- title: Sessions -description: An overview of sessions and when to use them. +description: An overview of Qiskit Runtime sessions and when to use them. --- diff --git a/docs/start/configure-qiskit-local.mdx b/docs/start/configure-qiskit-local.mdx index 1bcb68ca52c..55234d70c93 100644 --- a/docs/start/configure-qiskit-local.mdx +++ b/docs/start/configure-qiskit-local.mdx @@ -1,6 +1,6 @@ --- title: Configure Qiskit locally -description: Configure Qiskit on your local machine +description: How to customize the configuration of a local Qiskit installation. --- # Configure Qiskit locally diff --git a/docs/start/index.mdx b/docs/start/index.mdx index ee53e211d33..685760751ca 100644 --- a/docs/start/index.mdx +++ b/docs/start/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: Introduction to IBM Quantum documentation +description: Introduction to the documentation for IBM Quantum, Qiskit, and Qiskit Runtime. in_page_toc_max_heading_level: 2 diff --git a/docs/transpile/defaults-and-configuration-options.mdx b/docs/transpile/defaults-and-configuration-options.mdx index 7ad1051b17e..6a09bdc853a 100644 --- a/docs/transpile/defaults-and-configuration-options.mdx +++ b/docs/transpile/defaults-and-configuration-options.mdx @@ -1,6 +1,6 @@ --- title: Transpilation defaults and configuration options -description: Default settings and configuration options +description: The default settings and configuration options for quantum circuit transpilation in Qiskit. --- # Transpilation default settings and configuration options diff --git a/docs/transpile/index.mdx b/docs/transpile/index.mdx index 19fc502137b..9903f93ebd7 100644 --- a/docs/transpile/index.mdx +++ b/docs/transpile/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: Introduction to the transpiler +description: Introduction to transpiling quantum circuits in Qiskit. --- diff --git a/docs/transpile/set-optimization.mdx b/docs/transpile/set-optimization.mdx index 8af693aa461..a2ffe090233 100644 --- a/docs/transpile/set-optimization.mdx +++ b/docs/transpile/set-optimization.mdx @@ -1,6 +1,6 @@ --- title: Set transpiler optimization level -description: Learn how to set the optimization level +description: How to set the optimization level for transpiling quantum circuits in Qiskit. --- # Set the optimization level diff --git a/docs/transpile/transpiler-stages.ipynb b/docs/transpile/transpiler-stages.ipynb index c62c0e32aff..bd5b16ac4c9 100644 --- a/docs/transpile/transpiler-stages.ipynb +++ b/docs/transpile/transpiler-stages.ipynb @@ -468,7 +468,7 @@ ], "metadata": { "celltoolbar": "Raw Cell Format", - "description": "Overview of transpiler stages and the PassManager", + "description": "The default stages of the quantum circuit transpilation pipeline in Qiskit.", "kernelspec": { "display_name": "Python 3", "language": "python", diff --git a/docs/verify/index.mdx b/docs/verify/index.mdx index eb511c53a81..06b72ea57b1 100644 --- a/docs/verify/index.mdx +++ b/docs/verify/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: Introduction to the Verify phase +description: Introduction to verifying quantum circuits in Qiskit. --- # Introduction diff --git a/docs/verify/simulate-with-qiskit-primitives.mdx b/docs/verify/simulate-with-qiskit-primitives.mdx index f1ccc27e302..7b2e9b9780c 100644 --- a/docs/verify/simulate-with-qiskit-primitives.mdx +++ b/docs/verify/simulate-with-qiskit-primitives.mdx @@ -1,6 +1,6 @@ --- title: Exact simulation with Qiskit primitives -description: Simulate with Qiskit reference primitives. How to compute an expectation value with the Estimator primitive, and how to compute circuit output probabilities with the Sampler primitive +description: How to perform exact simulation of quantum circuits using primitives in Qiskit. --- # Exact simulation with Qiskit primitives diff --git a/docs/verify/stabilizer-circuit-simulation.ipynb b/docs/verify/stabilizer-circuit-simulation.ipynb index 48568d7a5c8..9f9c42f7942 100644 --- a/docs/verify/stabilizer-circuit-simulation.ipynb +++ b/docs/verify/stabilizer-circuit-simulation.ipynb @@ -201,7 +201,7 @@ } ], "metadata": { - "description": "Efficient simulation of stabilizer circuits with Qiskit Aer primitives", + "description": "How to efficiently simulate stabilizer circuits using Qiskit Aer primitives.", "kernelspec": { "display_name": "Python 3", "language": "python", diff --git a/scripts/commands/checkMetadata.ts b/scripts/commands/checkMetadata.ts index a5463c6af0f..0bdc47a8421 100644 --- a/scripts/commands/checkMetadata.ts +++ b/scripts/commands/checkMetadata.ts @@ -54,7 +54,11 @@ const readMetadata = async (filePath: string): Promise> => { }; const isValidMetadata = (metadata: Record): boolean => - metadata.title && metadata.description; + metadata.title && + metadata.description && + metadata.title != metadata.description && + metadata.description.length <= 160 && + metadata.description.length >= 50; const main = async (): Promise => { const args = readArgs(); @@ -106,7 +110,7 @@ function handleErrors(mdErrors: string[], notebookErrors: string[]): void { --- The title should be the page title: it's used for browser tabs and the top line of search results. The description should describe the page - in <160 characters, ideally using some keywords. The description is what + in at least 50 but no more than 160 characters, ideally using some keywords. The description is what shows up as the text in search results. See https://github.com/Qiskit/documentation/issues/131 for some tips. Please fix these files:\n\n${mdErrors.join("\n")} @@ -116,7 +120,8 @@ function handleErrors(mdErrors: string[], notebookErrors: string[]): void { console.error(` Invalid Jupyter notebook metadata. Every .ipynb file needs to set 'title' and 'description' in the file metadata. You need to - manually add this metadata. + manually add this metadata. Furthermore, the length of the description + must be at least 50 but no more than 160 characters. For example, if using VSCode, open up the file with the "Open With..." option and then "Text Editor". @@ -130,7 +135,7 @@ function handleErrors(mdErrors: string[], notebookErrors: string[]): void { Finally, add new keys in the "metadata" section for "title" and "description". The title should be the page title: it's used for browser tabs and the top line of search results. The description should describe the page - in <160 characters, ideally using some keywords. The description is what + in at least 50 but no more than 160 characters, ideally using some keywords. The description is what shows up as the text in search results. See https://github.com/Qiskit/documentation/issues/131 for some tips.