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

Furo looks bad with methods on same page as class #466

Closed
Eric-Arellano opened this issue Jul 6, 2023 · 0 comments · Fixed by #458
Closed

Furo looks bad with methods on same page as class #466

Eric-Arellano opened this issue Jul 6, 2023 · 0 comments · Fixed by #458
Assignees
Milestone

Comments

@Eric-Arellano
Copy link
Collaborator

See
api-docs-class-page-1-actual

The specific problem is when you highlight over the header for the method, a # anchor pops up. That overlaps with the [source] button. This is why we have this rule in our CSS atm:

// Rules that impact the top-level entry for the code object, which e.g. has the `[source]` button.
section > dl.py:not(.docutils) {
> dt {
// We normally want to use inline-block for definition terms so that the purple border we add on
// top does not stretch across the whole screen. But, we make an exception here it will have a
// `[source]` button that floats to the right. The spacing of that is non-trivial and was the
// source of issues in Pytorch, so we stick with Furo's spacing.
display: block;
// Make the border less thick so its clear the top-level page header corresponds to this line.
border-top-width: 1px;
margin-bottom: 1rem;
}
// It's possible to have multiple entries for the same code object, e.g. when using typing.overload.
// This cancels out the margin-bottom such that only the bottom-most `dt` will have a margin-bottom
// in effect.
> dt:not(:first-child) {
margin-top: -1rem;
}
}

But that assumes we have one "code object" per HTML page. We somehow need to handle multiple code objects, specifically when there is the [source] button.

@Eric-Arellano Eric-Arellano self-assigned this Jul 6, 2023
@Eric-Arellano Eric-Arellano added this to the Furo 1.0 milestone Jul 6, 2023
Eric-Arellano added a commit that referenced this issue Jul 11, 2023
## 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
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 added a commit that referenced this issue Jul 11, 2023
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant