Fix header hierarchy for the API docs #1283
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
arnaucasau
commented
May 3, 2024
arnaucasau
changed the title
|
Thanks for contributing to Qiskit documentation! Before your PR can be merged, it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient. Thanks! 🙌 |
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
github-merge-queue bot
pushed a commit
that referenced
this pull request
May 7, 2024
This PR adds the header of a class that was missing its id. The id was manually fixed in Box by modifying the HTML, and this is the regeneration as a follow-up of #1283
github-merge-queue bot
pushed a commit
that referenced
this pull request
May 7, 2024
This PR refactors the dispatch table used to prepare the props of each API component in order to simplify the `generateApiComponents.ts` script. The functions for "functions" and "methods" cannot be merged trivially because they check in different ways the `isDedicatedPage` prop. Using the same method for that gives us false positives on pages like [this](https://docs.quantum.ibm.com/api/qiskit/0.36/execute). Moreover, functions don't need any header in those cases. Thanks @Eric-Arellano for the idea on #1283 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Eric-Arellano
pushed a commit
that referenced
this pull request
May 7, 2024
This PR adds the header of a class that was missing its id. The id was manually fixed in Box by modifying the HTML, and this is the regeneration as a follow-up of #1283
Eric-Arellano
added a commit
that referenced
this pull request
May 7, 2024
This PR refactors the dispatch table used to prepare the props of each API component in order to simplify the `generateApiComponents.ts` script. The functions for "functions" and "methods" cannot be merged trivially because they check in different ways the `isDedicatedPage` prop. Using the same method for that gives us false positives on pages like [this](https://docs.quantum.ibm.com/api/qiskit/0.36/execute). Moreover, functions don't need any header in those cases. Thanks @Eric-Arellano for the idea on #1283 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this pull request
Jul 22, 2024
The PR adds a method to autogenerate the correct level for the headers of the MDX components (Attribute, Function, and Class) and regenerates the API docs. ### How to find the heading level Before setting the header, the script looks for the level of the previous header to determine which one corresponds to the component that is being generated. The script looks at all the siblings of the `Cheerio` element we use to define the component to find the previous header that wasn't created by the script before. We need to skip the generated headers to avoid the case where we have multiple methods/attributes/classes at the same level which shouldn't be mixed with the header of the previous level. If there's no header found in the first step, it means that we are dealing with a component inside of an inline class, and therefore, the script searches for the last header that corresponds to an inline class to determine the new level. This is true because when we are inside an inline class, there are no headers that haven't been generated by the script. Notice that the script always sets the header of an inline class in the parent level instead of creating another sibling, so we cannot search for generated siblings' headers. To distinguish between the headers of the different components, an attribute called `data-header-type` is used. This attribute is useful in the last search. Closes Qiskit#1215 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this pull request
Jul 22, 2024
This PR adds the header of a class that was missing its id. The id was manually fixed in Box by modifying the HTML, and this is the regeneration as a follow-up of Qiskit#1283
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this pull request
Jul 22, 2024
This PR refactors the dispatch table used to prepare the props of each API component in order to simplify the `generateApiComponents.ts` script. The functions for "functions" and "methods" cannot be merged trivially because they check in different ways the `isDedicatedPage` prop. Using the same method for that gives us false positives on pages like [this](https://docs.quantum.ibm.com/api/qiskit/0.36/execute). Moreover, functions don't need any header in those cases. Thanks @Eric-Arellano for the idea on Qiskit#1283 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The PR adds a method to autogenerate the correct level for the headers of the MDX components (Attribute, Function, and Class) and regenerates the API docs.
How to find the heading level
Before setting the header, the script looks for the level of the previous header to determine which one corresponds to the component that is being generated. The script looks at all the siblings of the
Cheerioelement we use to define the component to find the previous header that wasn't created by the script before. We need to skip the generated headers to avoid the case where we have multiple methods/attributes/classes at the same level which shouldn't be mixed with the header of the previous level.If there's no header found in the first step, it means that we are dealing with a component inside of an inline class, and therefore, the script searches for the last header that corresponds to an inline class to determine the new level. This is true because when we are inside an inline class, there are no headers that haven't been generated by the script.
Notice that the script always sets the header of an inline class in the parent level instead of creating another sibling, so we cannot search for generated siblings' headers.
To distinguish between the headers of the different components, an attribute called
data-header-typeis used. This attribute is useful in the last search.Closes #1215