Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Fix missing anchors for global variables (.. py:data::) #935

Closed
Eric-Arellano opened this issue Feb 29, 2024 · 1 comment
Closed

Fix missing anchors for global variables (.. py:data::) #935

Eric-Arellano opened this issue Feb 29, 2024 · 1 comment
Assignees
@Eric-Arellano
Labels
API docs infra 🏗️

Comments

@Eric-Arellano
Copy link
Collaborator

That is, remove these link checker ignores:

documentation/scripts/lib/links/ignores.ts

Lines 100 to 132 in c7bbfb1

"/api/qiskit/utils#qiskit.utils.optionals.HAS_AER",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_CONSTRAINT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_CPLEX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_CVXPY",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_DOCPLEX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_FIXTURES",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_GRAPHVIZ",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_IBMQ",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_IGNIS",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_IPYTHON",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_IPYWIDGETS",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_JAX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_JUPYTER",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_MATPLOTLIB",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_NETWORKX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_NLOPT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PDFLATEX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PDFTOCAIRO",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PIL",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PYDOT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PYGMENTS",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_PYLATEX",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_QASM3_IMPORT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SEABORN",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SKLEARN",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SKQUANT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SKSNFIT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SQSNOBFIT",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_SYMENGINE",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_TESTTOOLS",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_TOQM",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_TWEEDLEDUM",
"/api/qiskit/utils#qiskit.utils.optionals.HAS_Z3",

They correspond to this RST:

https://github.com/Qiskit/qiskit/blob/d26d3069254a669a43991da73e161abd57f897d3/qiskit/utils/optionals.py#L28-L45

Which results in this markdown:

documentation/docs/api/qiskit/utils.md

Lines 329 to 336 in c7bbfb1

##### Qiskit Components
| | |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **qiskit.utils.optionals.HAS\_AER** | Qiskit Aer \<[https://qiskit.github.io/qiskit-aer/](https://qiskit.github.io/qiskit-aer/)> provides high-performance simulators for the quantum circuits constructed within Qiskit. |
| **qiskit.utils.optionals.HAS\_IBMQ** | The `Qiskit IBMQ Provider` is used for accessing IBM Quantum hardware in the IBM cloud. |
| **qiskit.utils.optionals.HAS\_IGNIS** | `Qiskit Ignis` provides tools for quantum hardware verification, noise characterization, and error correction. |
| **qiskit.utils.optionals.HAS\_TOQM** | [Qiskit TOQM](https://github.com/qiskit-toqm/qiskit-toqm) provides transpiler passes for the [Time-optimal Qubit mapping algorithm](https://doi.org/10.1145/3445814.3446706). |

--

To avoid dealing with the table nuance, it may be easier to look at qasm2.md:

documentation/scripts/lib/links/ignores.ts

Lines 95 to 97 in c7bbfb1

"/api/qiskit/qasm2#qiskit.qasm2.LEGACY_CUSTOM_CLASSICAL",
"/api/qiskit/qasm2#qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS",
"/api/qiskit/qasm2#qiskit.qasm2.LEGACY_INCLUDE_PATH",

https://github.com/Qiskit/qiskit/blob/d26d3069254a669a43991da73e161abd57f897d3/qiskit/qasm2/__init__.py#L454-L470

documentation/docs/api/qiskit/qasm2.md

Lines 497 to 509 in c7bbfb1

You can emulate this behaviour in [`load()`](#qiskit.qasm2.load "qiskit.qasm2.load") and [`loads()`](#qiskit.qasm2.loads "qiskit.qasm2.loads") by setting include\_path appropriately (try inspecting the variable `qiskit.__file__` to find the installed location), and by passing a list of [`CustomInstruction`](#qiskit.qasm2.CustomInstruction "qiskit.qasm2.CustomInstruction") instances for each of the custom gates you care about. To make things easier we make three tuples available, which each contain one component of a configuration that is equivalent to Qiskit’s legacy converter behaviour.
**qiskit.qasm2.LEGACY\_CUSTOM\_INSTRUCTIONS**
A tuple containing the extra custom\_instructions that Qiskit’s legacy built-in converters used if `qelib1.inc` is included, and there is any definition of a `delay` instruction. The gates in the paper version of `qelib1.inc` and `delay` all require a compatible declaration statement to be present within the OpenQASM 2 program, but Qiskit’s legacy additions are all marked as builtins since they are not actually present in any include file this parser sees.
**qiskit.qasm2.LEGACY\_CUSTOM\_CLASSICAL**
A tuple containing the extra custom\_classical functions that Qiskit’s legacy built-in converters use beyond those specified by the paper. This is the three basic inverse trigonometric functions: $\asin$, $\acos$ and $\atan$.
**qiskit.qasm2.LEGACY\_INCLUDE\_PATH**
A tuple containing the exact include\_path used by the legacy Qiskit converter.

--

We should be adding a <span id="qiskit.utils.optionals.HAS_AER"></span> for example.
@Eric-Arellano Eric-Arellano mentioned this issue May 16, 2024
Closed
@Eric-Arellano Eric-Arellano changed the title Fix missing anchors for .. py:data:: entries from utils module page Fix missing anchors for global variables (.. py:data::) May 17, 2024
@Eric-Arellano Eric-Arellano mentioned this issue Sep 4, 2024
Merged
@Eric-Arellano Eric-Arellano self-assigned this Sep 4, 2024
@Eric-Arellano Eric-Arellano mentioned this issue Sep 6, 2024
Merged
github-merge-queue bot pushed a commit that referenced this issue Sep 6, 2024
@Eric-Arellano
Handle Sphinx data type (#1917)
1d89837 
Closes #1401 and
#935.

We reuse `<Attribute>`, which actually works out quite well! It
understands how to parse when the data object has a value assigned to it
like `= "my_value"`. It can also properly detect `isDedicatedPage`.


![image](https://github.com/user-attachments/assets/dd938c50-3182-4573-a678-74271a3b72cf)

There is one weird edge case: Qiskit was improperly using `.. py:data::`
inside a table in `utils.mdx`. Naively, it would cause issues with
trying to render the component inside the table, which does not work. I
fixed it in Qiskit `main`, but it would be too time consuming to fix on
0.35+. So, we now have a line to skip over converting to an `Attribute`
Component if the element is inside a table. That means the table will
continue to render the same as before on those historical docs - the
biggest downside is that anchor links still will be broken for the page.

<img width="863" alt="Screenshot 2024-09-06 at 9 40 51 AM"
src="https://github.com/user-attachments/assets/f7355c1f-ed50-4293-976d-42f02fdf6013">

A follow up will simplify our linters like checking for orphan pages,
since this PR fixes a lot of those problems.
@Eric-Arellano
Copy link
Collaborator Author

Fixed by #1917. The utils table is broken on historical versions, but we're not going to fix that because it's too finicky with modifying the HTML.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Eric-Arellano Eric-Arellano

Labels
API docs infra 🏗️
Projects
Docs Planning
Archived in project
Milestone
No milestone
Development

No branches or pull requests
2 participants
@Eric-Arellano @javabster