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.

Sign up for GitHub

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

Jump to bottom

Initial audit of header hierarchy for all module API pages #942

Closed
33 tasks done
Tracked by #479
Eric-Arellano opened this issue Mar 1, 2024 · 0 comments · Fixed by Qiskit/qiskit#12325
Closed
33 tasks done
Tracked by #479

Initial audit of header hierarchy for all module API pages #942

Eric-Arellano opened this issue Mar 1, 2024 · 0 comments · Fixed by Qiskit/qiskit#12325
Assignees
@Eric-Arellano
Labels
API docs infra 🏗️
Milestone
24-05-21 qiskit 1...

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Mar 1, 2024 •
edited
Loading

Like Qiskit/qiskit#11923, but for all the other modules. We want to look for a few things:

Note that we should never use more than one h1 on module pages; don't try to improve the header hierarchy that way.

Module pages can be identified by searching for python_api_type: module. This shouldn't be a problem on function and class API pages, which are much more auto-generated than human-written.

--

  • qiskit.assembler
  • qiskit.circuit
  • qiskit.circuit.classical
  • qiskit.circuit.classicalfunction
  • qiskit.circuit.library
  • qiskit.circuit.singleton
  • qiskit.compiler
  • qiskit.converters
  • qiskit.dagcircuit
  • qiskit.exceptions
  • qiskit.passmanager
  • qiskit.primitives
  • qiskit.providers
  • qiskit.providers.basic_provider
  • qiskit.providers.fake_provider
  • qiskit.providers.models
  • qiskit.pulse
  • qiskit.qasm2
  • qiskit.qasm3
  • qiskit.qobj
  • qiskit.qpy
  • qiskit.quantum_info
  • qiskit.result
  • qiskit.scheduler
  • qiskit.synthesis
  • qiskit.synthesis.unitary.aqc
  • qiskit.transpiler
  • qiskit.transpiler.passes
  • qiskit.transpiler.passes.synthesis.plugin
  • qiskit.transpiler.preset_passmanagers
  • qiskit.transpiler.preset_passmanagers.plugin
  • qiskit.utils
  • qiskit.visualization
This was referenced Mar 1, 2024
Merged
Closed
Merged
github-merge-queue bot pushed a commit that referenced this issue Mar 4, 2024
@Eric-Arellano
Don't show h1s in module page table of contents (#949)
d10df26 
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
#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 self-assigned this Apr 30, 2024
@Eric-Arellano Eric-Arellano mentioned this issue Apr 30, 2024
Merged
Eric-Arellano added a commit to Qiskit/qiskit-ibm-runtime that referenced this issue Apr 30, 2024
@Eric-Arellano
Reorganize transpiler modules in API docs (#1645)
e0387bc 
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime.

## Reduces `transpiler` modules

Before:

| module | status |
| --- | --- |
| qiskit.transpiler | only links to `passes` |
| qiskit.transpiler.passes | only links to `basis` and `scheduling` |
| qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't |
| qiskit.transpiler.passes.scheduling | useful |

Now:

| module | status |
| --- | --- |
| qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` |
| qiskit.transpiler.passes.scheduling | useful |

This saves the user clicks. Now each page is useful enough to stand on its own.

This is what the index page now looks like:

<img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b">

This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again.

This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future.

## Improves header hierarchy

### Options

Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers).

### `qiskit_ibm_runtime.transpiler.passes.scheduling`

This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels.

## Removes unused docstrings

The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
Eric-Arellano added a commit to Eric-Arellano/qiskit-ibm-runtime that referenced this issue May 1, 2024
@Eric-Arellano
Reorganize transpiler modules in API docs (Qiskit#1645)
9b110ee 
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime.

## Reduces `transpiler` modules

Before:

| module | status |
| --- | --- |
| qiskit.transpiler | only links to `passes` |
| qiskit.transpiler.passes | only links to `basis` and `scheduling` |
| qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't |
| qiskit.transpiler.passes.scheduling | useful |

Now:

| module | status |
| --- | --- |
| qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` |
| qiskit.transpiler.passes.scheduling | useful |

This saves the user clicks. Now each page is useful enough to stand on its own.

This is what the index page now looks like:

<img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b">

This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again.

This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future.

## Improves header hierarchy

### Options

Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers).

### `qiskit_ibm_runtime.transpiler.passes.scheduling`

This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels.

## Removes unused docstrings

The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
@Eric-Arellano Eric-Arellano mentioned this issue May 1, 2024
Merged
kt474 pushed a commit to Qiskit/qiskit-ibm-runtime that referenced this issue May 1, 2024
@Eric-Arellano
Reorganize transpiler modules in API docs (#1645) (#1646)
60b894c 
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime.

## Reduces `transpiler` modules

Before:

| module | status |
| --- | --- |
| qiskit.transpiler | only links to `passes` |
| qiskit.transpiler.passes | only links to `basis` and `scheduling` |
| qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't |
| qiskit.transpiler.passes.scheduling | useful |

Now:

| module | status |
| --- | --- |
| qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` |
| qiskit.transpiler.passes.scheduling | useful |

This saves the user clicks. Now each page is useful enough to stand on its own.

This is what the index page now looks like:

<img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b">

This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again.

This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future.

## Improves header hierarchy

### Options

Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers).

### `qiskit_ibm_runtime.transpiler.passes.scheduling`

This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels.

## Removes unused docstrings

The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
@Eric-Arellano Eric-Arellano mentioned this issue May 1, 2024
Closed
@Eric-Arellano Eric-Arellano changed the title Audit header hierarchy for all module API pages Initial audit of header hierarchy for all module API pages May 1, 2024
This was referenced May 1, 2024
Closed
Merged
@mergify mergify bot mentioned this issue May 6, 2024
Merged
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
@Eric-Arellano
Don't show h1s in module page table of contents (Qiskit#949)
15586fd 
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.
@javabster javabster removed this from Docs Planning Feb 5, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Eric-Arellano Eric-Arellano

Labels
API docs infra 🏗️
Projects
None yet
Milestone
24-05-21 qiskit 1.0 release part 2
Development

Successfully merging a pull request may close this issue.

Improve header hierarchy for API module pages Eric-Arellano/qiskit-terra
1 participant
@Eric-Arellano