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

Redesign API docs #459

Closed
Eric-Arellano opened this issue Jul 5, 2023 · 2 comments
Closed

Redesign API docs #459

Eric-Arellano opened this issue Jul 5, 2023 · 2 comments
Assignees
@frankharkins

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Jul 5, 2023 •
edited by javabster
Loading

From a Slack conversation:

I think some of the concern about crowding/size is kind of a styling effect - our current styles are (imo) kind of hard to read; internal section headers like “Arguments” and “Returns” get way too much weight and vertical space, which makes longer pages much harder to scan. (I know we inherited that - it’s not meant as a slight at the current design team.) I think if we could tighten the layouts up, it’d go a long way to making composite pages better
@Eric-Arellano Eric-Arellano mentioned this issue Jul 7, 2023
Merged
Eric-Arellano added a commit that referenced this issue Jul 11, 2023
@Eric-Arellano
Fix Furo styling for API pages with methods on class page (#458)
43d7442 
## Background

We're planning to switch some Qiskit projects to stop having dedicated
HTML pages per method, mostly due to performance concerns.

## Styling changes

Closes #466. Methods
were using `inline-block` rather than `block` when on the classes page,
which resulted in a bug when highlighting over the method to show the
`#` anchor tag:

![Screenshot 2023-07-07 at 11 25 45
AM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/004da4c0-3702-4cd7-9601-5baa46a992a7)

Instead, we now turn off floating of the `[source]` label because it
causes issues on long code signatures:

![Screenshot 2023-07-07 at 3 02 44
PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/19c45f5a-8fc7-44f5-a9d8-997b9a0bfa6e)

After:

![Screenshot 2023-07-07 at 3 03 08
PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/55e865c9-b376-40e0-846d-cfdd4b1efd1a)

Even though the `[source]` floating to the right is more "elegant", we
have too many long signatures in Qiskit to be worth it. It's safer to
turn off the float.

This also improves the information hierarchy so that page feels less
crowded. Relates to
#459:

* Use a border-width of 2px for top-level code objects, but otherwise 1
* Increases the font sizes so headings look bigger.
Eric-Arellano added a commit to Eric-Arellano/qiskit_sphinx_theme that referenced this issue Jul 11, 2023
@Eric-Arellano
Fix Furo styling for API pages with methods on class page (Qiskit#458)
854892a 
We're planning to switch some Qiskit projects to stop having dedicated
HTML pages per method, mostly due to performance concerns.

Closes Qiskit#466. Methods
were using `inline-block` rather than `block` when on the classes page,
which resulted in a bug when highlighting over the method to show the
`#` anchor tag:

![Screenshot 2023-07-07 at 11 25 45
AM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/004da4c0-3702-4cd7-9601-5baa46a992a7)

Instead, we now turn off floating of the `[source]` label because it
causes issues on long code signatures:

![Screenshot 2023-07-07 at 3 02 44
PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/19c45f5a-8fc7-44f5-a9d8-997b9a0bfa6e)

After:

![Screenshot 2023-07-07 at 3 03 08
PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/55e865c9-b376-40e0-846d-cfdd4b1efd1a)

Even though the `[source]` floating to the right is more "elegant", we
have too many long signatures in Qiskit to be worth it. It's safer to
turn off the float.

This also improves the information hierarchy so that page feels less
crowded. Relates to
Qiskit#459:

* Use a border-width of 2px for top-level code objects, but otherwise 1
* Increases the font sizes so headings look bigger.
@Eric-Arellano Eric-Arellano mentioned this issue Jul 11, 2023
Merged
Eric-Arellano added a commit that referenced this issue Jul 11, 2023
@Eric-Arellano
Fix Furo styling for API pages with methods on class page (Cherry-pic…
99e0342 
…k of #458) (#478)

We're planning to switch some Qiskit projects to stop having dedicated
HTML pages per method, mostly due to performance concerns.

Closes #466. Methods
were using `inline-block` rather than `block` when on the classes page,
which resulted in a bug when highlighting over the method to show the
`#` anchor tag:

![Screenshot 2023-07-07 at 11 25 45

AM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/004da4c0-3702-4cd7-9601-5baa46a992a7)

Instead, we now turn off floating of the `[source]` label because it
causes issues on long code signatures:

![Screenshot 2023-07-07 at 3 02 44

PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/19c45f5a-8fc7-44f5-a9d8-997b9a0bfa6e)

After:

![Screenshot 2023-07-07 at 3 03 08

PM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/55e865c9-b376-40e0-846d-cfdd4b1efd1a)

Even though the `[source]` floating to the right is more "elegant", we
have too many long signatures in Qiskit to be worth it. It's safer to
turn off the float.

This also improves the information hierarchy so that page feels less
crowded. Relates to
#459:

* Use a border-width of 2px for top-level code objects, but otherwise 1
* Increases the font sizes so headings look bigger.
@Eric-Arellano
Copy link
Collaborator Author

@frankharkins is this still something you're hoping to get to in the next ~3 months? Given that we'll be working less actively in this repository due to new priorities, I'm closing out what are nice-to-haves that we are unlikely to get to realistically.

Fwiw, I think the current design is "good enough".

@frankharkins
Copy link
Member

Sounds good :)

@frankharkins frankharkins closed this as not planned Won't fix, can't repro, duplicate, stale Aug 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@frankharkins frankharkins

Labels
None yet
Projects
No open projects
Qiskit Sphinx Theme
Status: Done
Milestone
No milestone
Development

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