-
Notifications
You must be signed in to change notification settings - Fork 87
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API pipeline needs to add "front matter" (title / metadata) to several pages #66
Comments
Closes #9. Once this lands, we will update the closed source repository to start consuming this repository and remove the API pipeline from there. Note that these API docs are not identical to the closed source versions! This uses qiskit-ibm-provider 0.7 rather than 0.6.3, and qiskit-ibm-runtime 0.12.2 rather than 0.11.3. We skip spellcheck issues and the metadata check for certain files (#66) to facilitate landing this. They were already issues in closed source.
Perhaps we can use the filename as a fallback? |
Closes #558. Before: <img width="248" alt="Screenshot 2023-12-29 at 1 38 50 PM" src="https://github.com/Qiskit/documentation/assets/14852634/299bd13b-e681-4105-93b6-9525312c547a"> After: <img width="251" alt="Screenshot 2023-12-29 at 1 39 08 PM" src="https://github.com/Qiskit/documentation/assets/14852634/21c900af-b44c-4c69-9ac5-133bbc251b00"> This new left sidebar layout aligns with Qiskit. The consistency is useful, but also I think this new layout is more functional anyways. It reduces the amount of nesting. It also allows us to collapse the left sidebar by default, which we do in the rest of the docs. ## Changes index page Before, the index page was the description for the code components belonging to the top-level modules `qiskit_ibm_provider` and `qiskit_ibm_runtime`, rather than enumerating what all the modules are: Before: <img width="625" alt="Screenshot 2023-12-29 at 1 40 19 PM" src="https://github.com/Qiskit/documentation/assets/14852634/c2e08d6f-365e-4775-8719-c6aad01cc77a"> After: <img width="658" alt="Screenshot 2023-12-29 at 1 41 30 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4a58cdd7-48f3-4e28-a0e4-cb716f095e4e"> Note that this index page is not accessible from the left sidebar; it's not clear what we would call it. But you can access it from the top nav-bar: <img width="234" alt="Screenshot 2023-12-29 at 1 42 13 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4c9ebdd7-9bf2-45ed-8c3b-b998d319d5ec"> ## Metadata The new index pages have never had metadata. That's because we don't have any technique to determine from Sphinx programatically its metadata because the Sphinx generated HTML page is missing it: https://github.com/Qiskit/documentation/blob/92b3fa45c10aa917c3fbc7ada861b2db55203902/scripts/lib/sphinx/PythonObjectMeta.ts#L13-L24 This is an instance of #66. I think we need a generic solution to that problem, such as Axel's suggestion to use filenames as a fallback. But, it's important that the metadata is high quality for these two index pages since they are so high-profile. So, I propose hardcoding the metadata for them. Because there are only two files, I think this approach is acceptable; obviously it wouldn't scale if we were hardcoding dozens of files.
Closes #793. This unblocks us starting to check API docs in #66. It also speeds up the workflow for non-API docs, which is valuable because non-API and API docs have such different workflows. I only added an `--apis` argument rather than e.g. `--current-apis` vs `--historical-apis` because this check is fast enough to not need the nuance. --------- Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
#821 fixes a legit bug in historical API docs. The other files so far seem to be because they are not using the I'm thinking we could extract the title from the We should go through this file list to confirm that this is the correct diagnosis and fix: Failing files after #821docs/api/qiskit/transpiler_builtin_plugins.md docs/api/qiskit/0.19/aer.md docs/api/qiskit/0.19/ibmq_jupyter.md docs/api/qiskit/0.19/ibmq_visualization.md docs/api/qiskit/0.19/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.19/qiskit.optimization.INFINITY.md docs/api/qiskit/0.19/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.24/aer.md docs/api/qiskit/0.24/aqua.md docs/api/qiskit/0.24/ibmq-provider.md docs/api/qiskit/0.24/ibmq_jupyter.md docs/api/qiskit/0.24/ibmq_visualization.md docs/api/qiskit/0.24/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.24/qiskit.optimization.INFINITY.md docs/api/qiskit/0.24/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.25/aer.md docs/api/qiskit/0.25/aqua.md docs/api/qiskit/0.25/ibmq-provider.md docs/api/qiskit/0.25/ibmq_jupyter.md docs/api/qiskit/0.25/ibmq_visualization.md docs/api/qiskit/0.25/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.25/qiskit.optimization.INFINITY.md docs/api/qiskit/0.25/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.25/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.26/aer.md docs/api/qiskit/0.26/aqua.md docs/api/qiskit/0.26/ibmq-provider.md docs/api/qiskit/0.26/ibmq_jupyter.md docs/api/qiskit/0.26/ibmq_visualization.md docs/api/qiskit/0.26/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.26/qiskit.optimization.INFINITY.md docs/api/qiskit/0.26/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.26/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.27/aer.md docs/api/qiskit/0.27/aqua.md docs/api/qiskit/0.27/ibmq-provider.md docs/api/qiskit/0.27/ibmq_jupyter.md docs/api/qiskit/0.27/ibmq_visualization.md docs/api/qiskit/0.27/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.27/qiskit.optimization.INFINITY.md docs/api/qiskit/0.27/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.27/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.30/aer.md docs/api/qiskit/0.30/aqua.md docs/api/qiskit/0.30/ibmq-provider.md docs/api/qiskit/0.30/ibmq_jupyter.md docs/api/qiskit/0.30/ibmq_visualization.md docs/api/qiskit/0.30/parallel.md docs/api/qiskit/0.30/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.30/qiskit.optimization.INFINITY.md docs/api/qiskit/0.30/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.30/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.29/aer.md docs/api/qiskit/0.29/aqua.md docs/api/qiskit/0.29/ibmq-provider.md docs/api/qiskit/0.29/ibmq_jupyter.md docs/api/qiskit/0.29/ibmq_visualization.md docs/api/qiskit/0.29/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.29/qiskit.optimization.INFINITY.md docs/api/qiskit/0.29/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.29/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.31/aer.md docs/api/qiskit/0.31/aqua.md docs/api/qiskit/0.31/ibmq-provider.md docs/api/qiskit/0.31/ibmq_jupyter.md docs/api/qiskit/0.31/ibmq_visualization.md docs/api/qiskit/0.31/parallel.md docs/api/qiskit/0.31/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.31/qiskit.optimization.INFINITY.md docs/api/qiskit/0.31/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.31/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.28/aer.md docs/api/qiskit/0.28/aqua.md docs/api/qiskit/0.28/ibmq-provider.md docs/api/qiskit/0.28/ibmq_jupyter.md docs/api/qiskit/0.28/ibmq_visualization.md docs/api/qiskit/0.28/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.28/qiskit.optimization.INFINITY.md docs/api/qiskit/0.28/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.28/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.32/aer.md docs/api/qiskit/0.32/aqua.md docs/api/qiskit/0.32/ibmq-provider.md docs/api/qiskit/0.32/ibmq_jupyter.md docs/api/qiskit/0.32/ibmq_visualization.md docs/api/qiskit/0.32/parallel.md docs/api/qiskit/0.32/qiskit.aqua.aqua_globals.md docs/api/qiskit/0.32/qiskit.optimization.INFINITY.md docs/api/qiskit/0.32/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.32/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.35/aer.md docs/api/qiskit/0.35/ibmq-provider.md docs/api/qiskit/0.35/ibmq_jupyter.md docs/api/qiskit/0.35/ibmq_visualization.md docs/api/qiskit/0.35/parallel.md docs/api/qiskit/0.35/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.35/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.35/transpiler_builtin_plugins.md docs/api/qiskit/0.33/aer.md docs/api/qiskit/0.33/ibmq-provider.md docs/api/qiskit/0.33/ibmq_jupyter.md docs/api/qiskit/0.33/ibmq_visualization.md docs/api/qiskit/0.33/parallel.md docs/api/qiskit/0.33/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.33/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.33/transpiler_builtin_plugins.md docs/api/qiskit/0.36/aer.md docs/api/qiskit/0.36/ibmq-provider.md docs/api/qiskit/0.36/ibmq_jupyter.md docs/api/qiskit/0.36/ibmq_visualization.md docs/api/qiskit/0.36/parallel.md docs/api/qiskit/0.36/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.36/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.36/transpiler_builtin_plugins.md docs/api/qiskit/0.37/aer.md docs/api/qiskit/0.37/ibmq-provider.md docs/api/qiskit/0.37/ibmq_jupyter.md docs/api/qiskit/0.37/ibmq_visualization.md docs/api/qiskit/0.37/parallel.md docs/api/qiskit/0.37/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.37/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.37/transpiler_builtin_plugins.md docs/api/qiskit/0.38/aer.md docs/api/qiskit/0.38/ibmq-provider.md docs/api/qiskit/0.38/ibmq_jupyter.md docs/api/qiskit/0.38/ibmq_visualization.md docs/api/qiskit/0.38/parallel.md docs/api/qiskit/0.38/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.38/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.38/transpiler_builtin_plugins.md docs/api/qiskit/0.39/aer.md docs/api/qiskit/0.39/ibmq-provider.md docs/api/qiskit/0.39/ibmq_jupyter.md docs/api/qiskit/0.39/ibmq_visualization.md docs/api/qiskit/0.39/parallel.md docs/api/qiskit/0.39/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.39/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.39/transpiler_builtin_plugins.md docs/api/qiskit/0.40/aer.md docs/api/qiskit/0.40/ibmq-provider.md docs/api/qiskit/0.40/ibmq_jupyter.md docs/api/qiskit/0.40/ibmq_visualization.md docs/api/qiskit/0.40/parallel.md docs/api/qiskit/0.40/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.40/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.40/transpiler_builtin_plugins.md docs/api/qiskit/0.42/aer.md docs/api/qiskit/0.42/ibmq-provider.md docs/api/qiskit/0.42/ibmq_jupyter.md docs/api/qiskit/0.42/ibmq_visualization.md docs/api/qiskit/0.42/parallel.md docs/api/qiskit/0.42/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.42/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.42/transpiler_builtin_plugins.md docs/api/qiskit/0.43/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.43/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.43/transpiler_builtin_plugins.md docs/api/qiskit/0.44/transpiler_builtin_plugins.md docs/api/qiskit/0.41/aer.md docs/api/qiskit/0.41/ibmq-provider.md docs/api/qiskit/0.41/ibmq_jupyter.md docs/api/qiskit/0.41/ibmq_visualization.md docs/api/qiskit/0.41/parallel.md docs/api/qiskit/0.41/qiskit.quantum_info.two_qubit_cnot_decompose.md docs/api/qiskit/0.41/qiskit.utils.algorithm_globals.md docs/api/qiskit/0.41/transpiler_builtin_plugins.md docs/api/qiskit/0.45/transpiler_builtin_plugins.md docs/api/qiskit/dev/transpiler_builtin_plugins.md |
Part of #66. We were failing to detect modules using old versions of Sphinx that set the module metadata in `<div>` rather than `<span>` or `<section>`. Some of the module pages had no metadata at all, whereas some were misclassified as `functions` corresponding to the first function in the module's page. Fixing this metadata will fix the HTML meta properties, and it also fixes the table of contents to have correct nesting.
Closes Qiskit#9. Once this lands, we will update the closed source repository to start consuming this repository and remove the API pipeline from there. Note that these API docs are not identical to the closed source versions! This uses qiskit-ibm-provider 0.7 rather than 0.6.3, and qiskit-ibm-runtime 0.12.2 rather than 0.11.3. We skip spellcheck issues and the metadata check for certain files (Qiskit#66) to facilitate landing this. They were already issues in closed source.
Closes Qiskit#558. Before: <img width="248" alt="Screenshot 2023-12-29 at 1 38 50 PM" src="https://github.com/Qiskit/documentation/assets/14852634/299bd13b-e681-4105-93b6-9525312c547a"> After: <img width="251" alt="Screenshot 2023-12-29 at 1 39 08 PM" src="https://github.com/Qiskit/documentation/assets/14852634/21c900af-b44c-4c69-9ac5-133bbc251b00"> This new left sidebar layout aligns with Qiskit. The consistency is useful, but also I think this new layout is more functional anyways. It reduces the amount of nesting. It also allows us to collapse the left sidebar by default, which we do in the rest of the docs. ## Changes index page Before, the index page was the description for the code components belonging to the top-level modules `qiskit_ibm_provider` and `qiskit_ibm_runtime`, rather than enumerating what all the modules are: Before: <img width="625" alt="Screenshot 2023-12-29 at 1 40 19 PM" src="https://github.com/Qiskit/documentation/assets/14852634/c2e08d6f-365e-4775-8719-c6aad01cc77a"> After: <img width="658" alt="Screenshot 2023-12-29 at 1 41 30 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4a58cdd7-48f3-4e28-a0e4-cb716f095e4e"> Note that this index page is not accessible from the left sidebar; it's not clear what we would call it. But you can access it from the top nav-bar: <img width="234" alt="Screenshot 2023-12-29 at 1 42 13 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4c9ebdd7-9bf2-45ed-8c3b-b998d319d5ec"> ## Metadata The new index pages have never had metadata. That's because we don't have any technique to determine from Sphinx programatically its metadata because the Sphinx generated HTML page is missing it: https://github.com/Qiskit/documentation/blob/60c836afbf30729fa30a97086b5812b08970ded5/scripts/lib/sphinx/PythonObjectMeta.ts#L13-L24 This is an instance of Qiskit#66. I think we need a generic solution to that problem, such as Axel's suggestion to use filenames as a fallback. But, it's important that the metadata is high quality for these two index pages since they are so high-profile. So, I propose hardcoding the metadata for them. Because there are only two files, I think this approach is acceptable; obviously it wouldn't scale if we were hardcoding dozens of files.
Closes Qiskit#793. This unblocks us starting to check API docs in Qiskit#66. It also speeds up the workflow for non-API docs, which is valuable because non-API and API docs have such different workflows. I only added an `--apis` argument rather than e.g. `--current-apis` vs `--historical-apis` because this check is fast enough to not need the nuance. --------- Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
) Part of Qiskit#66. We were failing to detect modules using old versions of Sphinx that set the module metadata in `<div>` rather than `<span>` or `<section>`. Some of the module pages had no metadata at all, whereas some were misclassified as `functions` corresponding to the first function in the module's page. Fixing this metadata will fix the HTML meta properties, and it also fixes the table of contents to have correct nesting.
#1917 fixed a lot of violations. The remaining failures should be fixed in failuresdocs/api/qiskit/0.19/aer.mdx |
These never had front matter. Axel said it's fine for now, but we should improve it soon.
We need to an
else
clause here:documentation/scripts/lib/sphinx/addFrontMatter.ts
Lines 19 to 30 in e872441
TBD how we determine the title and description!
Update: make sure CI enforces it, per #793.
The text was updated successfully, but these errors were encountered: