inline classes: fix header hierarchy #1215
Comments
This was referenced Apr 19, 2024
33 tasks
github-merge-queue bot
pushed a commit
that referenced
this issue
May 7, 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 #1215 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this issue
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>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Part of #199.
Right now, we hardcode methods/attributes/exceptions to have an h3 header no matter what. For classes, we don't add any header. That does not work though when you for example a function documented on a module page inside an h3 section already.
Instead, the header should take into account the parent header. Top-level functions / classes / exceptions should be one heading level lower than the parent. If the parent is the h1, then classes/exceptions should probably be h2 and functions h3.
Methods and Attributes should have a lower heading level than their class. Right now, we add the
MethodsandAttributesheaders. That would mean the class should be-1from the parent header,Methods/Attributesheaders should be-2, and Function/Attribute components should be-2. We might want to remove theMethods/Attributesheaders for inline classes, though, to reduce the amount of heading levels.The text was updated successfully, but these errors were encountered: