Use the new labels mechanism in docs guide reorganization

scripts/patterns-reorg/entries.py

@@ -450,7 +450,7 @@
     Entry("Manage cost", slug="manage-cost", from_file="run/manage-cost.mdx"),
 )
 
-WORKFLOW_FOLDER_AS_INDEX_CHILDREN = (
+PATTERNS_CHILDREN = (
     Entry(
         "Introduction to Qiskit Patterns",
         slug="intro-to-patterns",
@@ -528,10 +528,7 @@
 
 
 TOP_LEVEL_ENTRIES = (
-    Entry("Get started"),
-    *GET_STARTED_CHILDREN,
-    Entry("Workflow"),
-    *WORKFLOW_FOLDER_AS_INDEX_CHILDREN,
-    Entry("Tools"),
-    *TOOL_ENTRIES,
+    Entry("Get started", label=True, children=GET_STARTED_CHILDREN),
+    Entry("Workflow", label=True, children=PATTERNS_CHILDREN),
+    Entry("Tools", label=True, children=TOOL_ENTRIES),
 )

scripts/patterns-reorg/models.py

@@ -25,6 +25,7 @@ class Entry:
     external_url: str | None = field(default=None, kw_only=True)
     from_file: str | None = field(default=None, kw_only=True)
     page_content: str | None = field(default=None, kw_only=True)
+    label: bool = field(default=False, kw_only=True)
 
     def __post_init__(self) -> None:
         if self.slug and self.external_url:
@@ -44,6 +45,8 @@ def to_json(self, folder_name: str) -> dict:
             result["url"] = self.external_url
         if self.children:
             result["children"] = [child.to_json(folder_name) for child in self.children]
+        if self.label:
+            result["collapsible"] = False
         return result
 
     def ensure_slugs_exist(self, base_dir: Path) -> None:
@@ -99,7 +102,9 @@ def filter_entries(
     return tuple(result)
 
 
-def determine_redirects(entries: tuple[Entry, ...], *, prefix: str = "") -> dict[str, str]:
+def determine_redirects(
+    entries: tuple[Entry, ...], *, prefix: str = ""
+) -> dict[str, str]:
     result = {}
     for entry in entries:
         if entry.slug and entry.from_file:

scripts/patterns-reorg/page_content.py

@@ -14,69 +14,126 @@
 
 
 def map_content(index: str) -> str:
-    return (
-        "# Map problem to circuits\n\n"
-        'The "map problem to circuits" step of a Qiskit pattern describes how a user starts with a classical '
-        "problem and figures out how to map it to a quantum computer. For example, in applications such as "
-        "chemistry and quantum simulation, this step generally involves constructing a quantum circuit "
-        "representing the Hamiltonian you are attempting to solve. During this step, for certain problems, "
-        "it may also be desirable to specify the mapping of the problem onto qubits in the heavy-hex (or "
-        "gross) lattice of IBM Hardware from the outset if the structure of the problem lends itself to "
-        "optimization earlier. It is also worth considering at this point what the outcome of the particular "
-        "algorithm will be in prepartion for the later execute step, e.g. if the desired outcome involves "
-        "inferring correlation functions using Hadamard tests, you might prepare to use `Sampler` whereas "
-        "specifying observables would use the `Estimator` and could provide many error mitigation options. "
-        "The output of this step in a Qiskit pattern is normally a collection of circuits or quantum operators.\n\n"
-        "There are a number of software tools that could be used for this step, you can check out the "
-        f"following resources:\n\n{index}\n"
+    intro = dedent(
+        """\
+---
+title: Map problem to circuits
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
+# Map problem to circuits
+
+The "map problem to circuits" step of a Qiskit pattern describes how a user starts with a classical
+problem and figures out how to map it to a quantum computer.
+
+For example, in applications such as chemistry and quantum simulation, this step generally involves 
+constructing a quantum circuit representing the Hamiltonian you are attempting to solve.
+During this step, for certain problems, it may also be desirable to specify the mapping of
+the problem onto qubits in the heavy-hex (or gross) lattice of IBM Hardware from the
+outset if the structure of the problem lends itself to optimization earlier. 
+
+It is also worth considering at this point what the outcome of the particular algorithm will be
+in prepartion for the later execute step, e.g. if the desired outcome involves
+inferring correlation functions using Hadamard tests, you might prepare to use `Sampler` whereas
+specifying observables would use the `Estimator` and could provide many error mitigation options.
+
+The output of this step in a Qiskit pattern is normally a collection of circuits or quantum operators.
+
+## Guides
+"""
     )
+    return f"{intro}{index}\n"
 
 
 def postprocess_index_content(index: str) -> str:
-    return (
-        "# Post-process results\n\n"
-        'This final "post-process results" step of a Qiskit pattern involves stitching the outputs from '
-        "the prior step back together to obtain the desired result. This can involve a range of classical "
-        "data processing steps such as visualising results, readout error mitigation techniques, marginalizing "
-        "quasi-probability distributions to ascertain results on smaller sets of qubits or post-selection on inherent "
-        "properties of the problem, such as total spin, parity, or particle conservation by removing "
-        "unphysical observables.\n\n"
-        "There are a number of software tools that could be used for this step, you can check out the "
-        f"following resources:\n\n{index}\n"
+    intro = dedent(
+        """\
+---
+title: Post-process results
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
+This final "post-process results" step of a Qiskit pattern involves stitching the outputs from
+the prior step back together to obtain the desired result. This can involve a range of classical
+data processing steps such as visualising results, readout error mitigation techniques, marginalizing
+quasi-probability distributions to ascertain results on smaller sets of qubits or post-selection on inherent
+properties of the problem, such as total spin, parity, or particle conservation by removing
+unphysical observables.
+
+## Guides
+"""
     )
+    return f"{intro}{index}\n"
 
 
 def optimize_content(index: str) -> str:
-    return (
-        "# Optimize for target hardware\n\n"
-        'In the "optimize for target hardware" step of a Qiskit pattern you take the abstract circuits '
-        "(or operators) produced from the map step and perform a series of optimizations on them. This "
-        "may include mapping the route and layout of the circuit to physical qubit hardware, converting "
-        "to basis gates of the hardware, and reducing the number of operations, all designed to optimize"
-        "the likelihood of success in the later execute step. At this point you may also wish to debug "
-        "your circuits with a simulator before executiong on real hardware in the next step.\n\n"
-        "During this step abstract circuits must be transpiled to Instruction Set Architecture (ISA) circuits. "
-        "An ISA circuit is one that only consists of gates understood by the target hardware (basis gates), and "
-        "any multi-qubit gates needed to obey any connectivity constraints (coupling map). Only ISA circuits "
-        "can be run on IBM hardware using IBM Qiskit Runtime.\n\n"
-        "There are a number of software tools that could be used for this step, you can check out the "
-        f"following resources:\n\n{index}\n"
+    intro = dedent(
+        """\
+---
+title: Optimize for target hardware
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
+# Optimize for target hardware
+
+In the "optimize for target hardware" step of a Qiskit pattern, you take the abstract circuits
+(or operators) produced from the map step and perform a series of optimizations on them. This
+may include mapping the route and layout of the circuit to physical qubit hardware, converting
+to basis gates of the hardware, and reducing the number of operations, all designed to optimize
+the likelihood of success in the later execute step. At this point you may also wish to debug
+your circuits with a simulator before executiong on real hardware in the next step.
+
+During this step, abstract circuits must be transpiled to Instruction Set Architecture (ISA) circuits.
+An ISA circuit is one that only consists of gates understood by the target hardware (basis gates), and
+any multi-qubit gates needed to obey any connectivity constraints (coupling map). Only ISA circuits
+can be run on IBM hardware using IBM Qiskit Runtime.
+
+## Guides
+"""
     )
+    return f"{intro}{index}\n"
 
 
 def execute_index_content(index: str) -> str:
-    return (
-        "# Execute on hardware\n\n"
-        'The "execute on hardware" step of a Qiskit pattern involes running you circuits on hardware and produces the outputs of the quantum computation. The ISA circuits produced in the previous step, can be executed using either a Sampler or Estimator Primitive from Qiskit Runtime, initialised locally on your computer or from a cluster or other heterogeneous compute environment. These may be executed in a Batch, which allows parallel transpilation for classical computational efficiency, or a Session, which allows iterative tasks to be implemented efficiently without queuing delays. During this step there is also the option to configure certain error suppression and mitigation techniques provided by Qiskit Runtime.\n\n'
-        "Depending on whether you are using the Sampler or Estimator primitive, the outcome of this step will be different. If using the Sampler the output will be per-shot measurements in the form of bitstrings. If using the Estimator the output will be expectation values of observables corresponding to physical quantities or cost functions.\n\n"
-        "There are a number of software tools that could be used for this step, you can check out the "
-        f"following resources:\n\n{index}\n"
+    intro = dedent(
+        """\
+---
+title: Execute on hardware
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
+# Execute on hardware
+
+The "execute on hardware" step of a Qiskit pattern involes running you circuits on hardware
+and produces the outputs of the quantum computation. The ISA circuits produced in
+the previous step, can be executed using either a Sampler or Estimator Primitive from
+Qiskit Runtime, initialised locally on your computer or from a cluster or other
+heterogeneous compute environment. These may be executed in a Batch, which allows
+parallel transpilation for classical computational efficiency, or a Session,
+which allows iterative tasks to be implemented efficiently without queuing delays.
+
+During this step, there is also the option to configure certain error suppression and
+mitigation techniques provided by Qiskit Runtime.
+
+Depending on whether you are using the Sampler or Estimator primitive, the outcome of this step
+will be different. If using the Sampler, the output will be per-shot measurements
+in the form of bitstrings. If using the Estimator, the output will be
+expectation values of observables corresponding to physical quantities or cost functions.
+
+## Guides
+"""
     )
+    return f"{intro}{index}\n"
 
 
 def patterns_index_content() -> str:
     return dedent(
         """\
+---
+title: Introduction to Qiskit Patterns
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
 # Introduction to Qiskit Patterns
 
 Qiskit Patterns is a general framework for breaking down domain-specific problems and contextualizing required capabilities in stages. This allows for the seamless composability of new capabilities developed by IBM Quantum researchers (and others) and enables a future in which quantum computing tasks are performed by powerful heterogenous (CPU/GPU/QPU) computing infrastructure. Blocks or groups of blocks perform the steps of a pattern, with the Qiskit SDK providing an important foundational layer, supported by other tools or services developed by IBM Quantum or the quantum open-source community. Qiskit Patterns allows domain experts to specify a problem and compose the tooling (blocks) that achieves a Qiskit pattern, then that pattern could be executed locally, through cloud services, or deployed with Quantum Serverless.
@@ -129,6 +186,11 @@ def patterns_index_content() -> str:
 def index_page_content() -> str:
     return dedent(
         """\
+---
+title: Introduction to Qiskit
+description: TODO - 50+ characters long to ignore metadata check for now!
+---
+
 # Introduction to Qiskit
 
 [INSERT BIG PATTERNS AND TOOLS IMAGE]