enforce 50 <= description length <= 160 (#890)

Fixes #327
Qiskit · Feb 26, 2024 · d49c97d · d49c97d
1 parent 7e97535
commit d49c97d
Show file tree

Hide file tree

Showing 26 changed files with 34 additions and 29 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -54,7 +54,11 @@ const readMetadata = async (filePath: string): Promise<Record<string, any>> => {
 };
 
 const isValidMetadata = (metadata: Record<string, any>): 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<void> => {
   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.