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

Don't show h1s in module page table of contents #949

Merged
merged 40 commits into from
Mar 4, 2024

Conversation

Eric-Arellano
Copy link
Collaborator

@Eric-Arellano Eric-Arellano commented Mar 1, 2024

Closes #932.

We decided:

  1. We are going to keep showing h1s for class and function pages. It's useful because they have non-trivial code at the top level, like their docstring and constructor. It's nice to have the quick way to access the value.
  2. For now at least, we won't show h4s in the module pages. There are 8 module pages in the current API docs that use h4s. I think showing h4s improved ~3 of them, and made ~5 worse. So, for now, let's not include them. This can be revisited, especially after Initial audit of header hierarchy for all module API pages #942.

This regens all APIs but reverts dev docs, which have unrelated changes and will be regenerated in a dedicated PR.

@Eric-Arellano Eric-Arellano changed the title [wip] Don't include h1s in module page table of contents [wip] Don't show h1s in module page table of contents Mar 1, 2024
@Eric-Arellano Eric-Arellano changed the title [wip] Don't show h1s in module page table of contents Don't show h1s in module page table of contents Mar 4, 2024
@Eric-Arellano Eric-Arellano marked this pull request as ready for review March 4, 2024 13:58
@Eric-Arellano
Copy link
Collaborator Author

Any opinion on whether we should simply not set the line in_page_toc_min_heading_level for modules since 2 is already the default? It makes zero difference for the docs app / for users. I figured always setting in_page_toc_min_heading_level was simpler code, and it also maybe makes more explicit to devs the difference between class pages & module pages.

Copy link
Collaborator

@arnaucasau arnaucasau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@Eric-Arellano Eric-Arellano added this pull request to the merge queue Mar 4, 2024
Merged via the queue into main with commit d10df26 Mar 4, 2024
5 checks passed
@Eric-Arellano Eric-Arellano deleted the EA/module-metadata branch March 4, 2024 17:35
frankharkins pushed a commit to frankharkins/documentation that referenced this pull request Jul 22, 2024
Closes Qiskit#932.

We decided:

1. We are going to keep showing h1s for class and function pages. It's
useful because they have non-trivial code at the top level, like their
docstring and constructor. It's nice to have the quick way to access the
value.
2. For now at least, we won't show h4s in the module pages. There are 8
module pages in the current API docs that use h4s. I think showing h4s
improved ~3 of them, and made ~5 worse. So, for now, let's not include
them. This can be revisited, especially after
Qiskit#942.

This regens all APIs but reverts dev docs, which have unrelated changes
and will be regenerated in a dedicated PR.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

Module API pages should not include h1 in their page table of contents
2 participants