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

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

Closed
Eric-Arellano opened this issue May 16, 2024 · 1 comment · Fixed by #1917
Closed

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

Eric-Arellano opened this issue May 16, 2024 · 1 comment · Fixed by #1917
Assignees
@Eric-Arellano
Labels
API docs bug 🐛 infra 🏗️

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented May 16, 2024 •
edited
Loading

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

documentation/docs/api/qiskit/dev/circuit.mdx

Lines 883 to 893 in 394ca77

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.
@Eric-Arellano Eric-Arellano mentioned this issue May 16, 2024
Merged
github-merge-queue bot pushed a commit that referenced this issue May 17, 2024
@Eric-Arellano
Prepare Qiskit 1.1 docs (#1400)
1ebcd00 
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 •
edited
Loading

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
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
@Eric-Arellano
Prepare Qiskit 1.1 docs (Qiskit#1400)
e057d3c 
We will set up redirects in closed source.

The new circuit module rewrite suffers from
Qiskit#1401. That's not blocking
this release, though.
@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.
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 bug 🐛 infra 🏗️
Projects
Docs Planning
Archived in project
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Handle Sphinx data type Qiskit/documentation
2 participants
@jakelishman @Eric-Arellano