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.

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

Properly support global variables in API docs (.. py:data::) #1401

Open
Eric-Arellano opened this issue May 16, 2024 · 1 comment
Open

Properly support global variables in API docs (.. py:data::) #1401

Eric-Arellano opened this issue May 16, 2024 · 1 comment

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented May 16, 2024

This builds on top of #935, which is about broken cross-references. This issue is to also have a more intentional visual design for .. py:data::, such as an MDX component like <GlobalVariable> (name tbd).

unannotated screenshot Screenshot 2024-05-17 at 1 31 41 PM
annotated screenshot Screenshot 2024-05-17 at 1 31 41 PM
offending code

Qiskit ships with a large set of predefined equivalence relationships for all of its standard gates. This base library is called [`StandardEquivalenceLibrary`](#qiskit.circuit.StandardEquivalenceLibrary "qiskit.circuit.StandardEquivalenceLibrary"), and should be treated as immutable.
**qiskit.circuit.StandardEquivalenceLibrary**
A [`EquivalenceLibrary`](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary") that stores of all Qiskit’s built-in standard gate relationships. You should not mutate this, but instead either create your own [`EquivalenceLibrary`](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary") using this one as its `base`, or modify the global-state [`SessionEquivalenceLibrary`](#qiskit.circuit.SessionEquivalenceLibrary "qiskit.circuit.SessionEquivalenceLibrary").
Qiskit also defines a shared global-state object, [`SessionEquivalenceLibrary`](#qiskit.circuit.SessionEquivalenceLibrary "qiskit.circuit.SessionEquivalenceLibrary"), which is the default equivalences used by various places in Qiskit, most notably the [`BasisTranslator`](qiskit.transpiler.passes.BasisTranslator "qiskit.transpiler.passes.BasisTranslator") transpiler pass. You should feel free to add your own equivalences to this using its [`add_equivalence()`](qiskit.circuit.EquivalenceLibrary#add_equivalence "qiskit.circuit.EquivalenceLibrary.add_equivalence") method, and they will be automatically picked up by default instances of the [`BasisTranslator`](qiskit.transpiler.passes.BasisTranslator "qiskit.transpiler.passes.BasisTranslator").
**qiskit.circuit.SessionEquivalenceLibrary**
The default instance of [`EquivalenceLibrary`](qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary"), which will be used by most Qiskit objects if no library is manually specified. You can feel free to add equivalences to this using [`add_equivalence()`](qiskit.circuit.EquivalenceLibrary#add_equivalence "qiskit.circuit.EquivalenceLibrary.add_equivalence"). It inherits all the built-in rules of [`StandardEquivalenceLibrary`](#qiskit.circuit.StandardEquivalenceLibrary "qiskit.circuit.StandardEquivalenceLibrary").

I propose the design should look the same as our other components: a purple or blue left bar, header inside the component (#1395) with whatever the correct surrounding level would be, and ensure there is a <span id> or that the header has the ID.

github-merge-queue bot pushed a commit that referenced this issue May 17, 2024
We will set up redirects in closed source.

The new circuit module rewrite suffers from
#1401. That's not blocking
this release, though.
@jakelishman
Copy link
Member

jakelishman commented May 17, 2024

Oh boy - "A EquivalenceLibrary" haha. No points for English for me.

@Eric-Arellano Eric-Arellano changed the title Properly support .. py:data:: Properly support global variables in API docs (.. py:data::) May 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: No status
Development

No branches or pull requests

2 participants