API docs need to handle functions better #231
Comments
|
As part of this work can we also add anchor tags to the functions? I came across this issue earlier this week where i couldnt link people to |
|
@javabster you can: the syntax is <span id="qiskit.compiler.assemble"></span>But much better would be having it obvious how to copy the anchor from users simply using the website directly, which would be through the headers. |
github-merge-queue bot
pushed a commit
that referenced
this issue
Jan 25, 2024
This PR improves how the API generation script handles functions. ## Changes ### Demote some `h2` tags to `strong` We currently convert all `.rubric` elements to `h2`, but this makes some headings higher-level than they should be (specifically "Example" and "References" headings). For an example see [api/qiskit/converters](https://docs.quantum.ibm.com/api/qiskit/converters). <img width="197" alt="Screenshot 2024-01-23 at 17 37 33" src="https://github.com/Qiskit/documentation/assets/36071638/618a256b-9bdf-481b-bb49-e3eea7476b8e"> This PR converts rubrics to `strong` (rather than `h2`) if the name is "Example(s)" or "Reference(s)". This is a bit hacky, but it seems to work and I can't think of a better way of doing it. The Sphinx LaTeX writer also takes a [similar approach](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric). I've regenerated the docs using this new logic and I can see no false positives (that is, cases in which we use `strong` where we should use `h2`). ### Add function names as headings Functions currently have no headings. This PR adds a `h3` with the function name, which improves readability, gives anchor tag icons, and will add more functions to the right sidebar. I've also included some logic to avoid adding function names when the page is already dedicated to the function (such as [least_busy](https://docs.quantum.ibm.com/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy)). One quirk with this I spotted was some function names not appearing in the sidebar in `/api/qiskit/utils` (see `add_deprecation_to_docstring` in the screenshot). This is possibly because the title hierarchy skips `h2`.  *** Closes #231 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
frankharkins
added a commit
to frankharkins/documentation
that referenced
this issue
Jul 22, 2024
This PR improves how the API generation script handles functions. ## Changes ### Demote some `h2` tags to `strong` We currently convert all `.rubric` elements to `h2`, but this makes some headings higher-level than they should be (specifically "Example" and "References" headings). For an example see [api/qiskit/converters](https://docs.quantum.ibm.com/api/qiskit/converters). <img width="197" alt="Screenshot 2024-01-23 at 17 37 33" src="https://github.com/Qiskit/documentation/assets/36071638/618a256b-9bdf-481b-bb49-e3eea7476b8e"> This PR converts rubrics to `strong` (rather than `h2`) if the name is "Example(s)" or "Reference(s)". This is a bit hacky, but it seems to work and I can't think of a better way of doing it. The Sphinx LaTeX writer also takes a [similar approach](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric). I've regenerated the docs using this new logic and I can see no false positives (that is, cases in which we use `strong` where we should use `h2`). ### Add function names as headings Functions currently have no headings. This PR adds a `h3` with the function name, which improves readability, gives anchor tag icons, and will add more functions to the right sidebar. I've also included some logic to avoid adding function names when the page is already dedicated to the function (such as [least_busy](https://docs.quantum.ibm.com/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy)). One quirk with this I spotted was some function names not appearing in the sidebar in `/api/qiskit/utils` (see `add_deprecation_to_docstring` in the screenshot). This is possibly because the title hierarchy skips `h2`.  *** Closes Qiskit#231 --------- 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
E.g. https://docs.quantum-computing.ibm.com/api/qiskit/compiler
The header should better show what the function name is. And the right sidebar should be more useful:
But it is important the function still shows the whole import path because we have some modules right now that have functions that have functions with submodules, e.g. the module page for
my_modulehas a functionmy_module.submodule.my_func-- you have to show the whole import path for the docs to be correct.The text was updated successfully, but these errors were encountered: