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

Qiskit API: group modules into logical sections #1211

Closed
Tracked by #1213
Eric-Arellano opened this issue Apr 19, 2024 · 2 comments · Fixed by #1255
Closed
Tracked by #1213

Qiskit API: group modules into logical sections #1211

Eric-Arellano opened this issue Apr 19, 2024 · 2 comments · Fixed by #1255
Assignees
@Eric-Arellano
Labels
API docs infra 🏗️

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Apr 19, 2024 •
edited
Loading

For example

image

image

The main changes:

  1. group related modules into new categories
  2. flatten submodules to reduce overall nesting

Qiskit 1.0 modules

code to find modules 
from pathlib import Path
import json

raw = Path("docs/api/qiskit/_toc.json").read_text()
content = json.loads(raw)

all_modules = set()

def add_modules(entry) -> None:
    if entry.get("title").startswith("qiskit."):
        all_modules.add(entry["title"])
    if "children" in entry:
        for child in entry["children"]:
            add_modules(child)


add_modules(content)
print("\n".join(sorted(all_modules)))
module list

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 Apr 19, 2024
Closed
Closed
@javabster

This comment was marked as outdated.

Sign in to view
@Eric-Arellano Eric-Arellano mentioned this issue Apr 24, 2024
Merged
github-merge-queue bot pushed a commit that referenced this issue Apr 25, 2024
@Eric-Arellano
Flatten left table of contents for Runtime and Provider (#1241)
122cb1a 
Closes #1212. As explained
there, this is because:

1. Qiskit SDK is getting a bigger revamp in
#1211 and it will also
flatten submodules, so we want to be consistent.
2. The module list is so short that it's useful to have the navbar be
flatter. It makes things less crowded and more discoverable.

Note that some of the Runtime provider pages aren't very useful...I
opened #1240 to track
that.

For now, this is implemented as the `Pkg` constructor setting a boolean
argument for whether modules should be nested or not. I'm coming up with
an alternative—but similar factoring—while working on
#1211. This PR is
~prework.

<img width="253" alt="Screenshot 2024-04-24 at 4 02 34 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/2bbbaa7f-e187-4170-b2c5-02273e340b07">

<img width="257" alt="Screenshot 2024-04-24 at 4 02 10 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/53816ee2-f7ee-4d1d-90a5-64d7795fd776">
This was referenced Apr 26, 2024
Closed
Closed
@Eric-Arellano
Copy link
Collaborator Author

Eric-Arellano commented Apr 29, 2024 •
edited
Loading

Module list when you include 0.19 up to 1.0

Circuit construction

  • qiskit.circuit
  • qiskit.circuit.classical
  • qiskit.circuit.classicalfunction
  • qiskit.circuit.library
  • qiskit.circuit.singleton
  • qiskit.extensions

Quantum Information (qiskit.quantum_info)

  • qiskit.quantum_info

Transpilation

  • qiskit.converters
  • qiskit.dagcircuit
  • qiskit.passmanager
  • 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.transpiler.synthesis.aqc

Primitives and providers

  • qiskit.primitives
  • qiskit.providers
  • qiskit.providers.basic_provider
  • qiskit.providers.basicaer
  • qiskit.providers.fake_provider
  • qiskit.providers.models

Results and visualisations

  • qiskit.result
  • qiskit.validation
  • qiskit.visualization
  • qiskit.visualization.pulse.interpolation
  • qiskit.visualization.pulse.qcstyle

Opflow

  • qiskit.opflow
  • qiskit.opflow.converters
  • qiskit.opflow.evolutions
  • qiskit.opflow.expectations
  • qiskit.opflow.gradients
  • qiskit.opflow.list_ops
  • qiskit.opflow.primitive_ops
  • qiskit.opflow.state_fns

Serialization (OpenQASM and QPy)

  • qiskit.circuit.qpy_serialization
  • qiskit.qpy
  • qiskit.qasm
  • qiskit.qasm2
  • qiskit.qasm3

Pulse-level programming

  • qiskit.pulse
  • qiskit.pulse.channels
  • qiskit.pulse.instructions
  • qiskit.pulse.library
  • qiskit.pulse.library.discrete
  • qiskit.pulse.pulse_lib
  • qiskit.pulse.pulse_lib.discrete
  • qiskit.scheduler
  • qiskit.scheduler.methods.basic
  • qiskit.scheduler.schedule_circuit
  • qiskit.scheduler.utils

qiskit.execute
qiskit.execute_function

Other

  • qiskit.assembler
  • qiskit.compiler
  • qiskit.exceptions
  • qiskit.qobj
  • qiskit.tools
  • qiskit.tools.jupyter
  • qiskit.utils
  • qiskit.utils.mitigation

Qiskit Aer

  • qiskit.providers.aer
  • qiskit.providers.aer.extensions
  • qiskit.providers.aer.jobs
  • qiskit.providers.aer.library
  • qiskit.providers.aer.noise
  • qiskit.providers.aer.pulse
  • qiskit.providers.aer.utils

IBM Q Provider

  • qiskit.providers.ibmq
  • qiskit.providers.ibmq.credentials
  • qiskit.providers.ibmq.experiment
  • qiskit.providers.ibmq.job
  • qiskit.providers.ibmq.managed
  • qiskit.providers.ibmq.random
  • qiskit.providers.ibmq.runtime
  • qiskit.providers.ibmq.utils

Algorithms

  • qiskit.algorithms
  • qiskit.algorithms.eigensolvers
  • qiskit.algorithms.gradients
  • qiskit.algorithms.linear_solvers
  • qiskit.algorithms.minimum_eigensolvers
  • qiskit.algorithms.optimizers
  • qiskit.algorithms.optimizers.nlopts
  • qiskit.algorithms.optimizers.optimizer_utils
  • qiskit.algorithms.state_fidelities
  • qiskit.algorithms.time_evolvers.trotterization
  • qiskit.algorithms.time_evolvers.variational

Qiskit Aqua

  • qiskit.aqua
  • qiskit.aqua.algorithms
  • qiskit.aqua.algorithms.minimum_eigen_solvers.cplex
  • qiskit.aqua.circuits
  • qiskit.aqua.components
  • qiskit.aqua.components.eigs
  • qiskit.aqua.components.feature_maps
  • qiskit.aqua.components.initial_states
  • qiskit.aqua.components.iqfts
  • qiskit.aqua.components.multiclass_extensions
  • qiskit.aqua.components.neural_networks
  • qiskit.aqua.components.optimizers
  • qiskit.aqua.components.optimizers.nlopts
  • qiskit.aqua.components.oracles
  • qiskit.aqua.components.qfts
  • qiskit.aqua.components.reciprocals
  • qiskit.aqua.components.uncertainty_models
  • qiskit.aqua.components.uncertainty_problems
  • qiskit.aqua.components.variational_forms
  • qiskit.aqua.operators
  • qiskit.aqua.operators.converters
  • qiskit.aqua.operators.evolutions
  • qiskit.aqua.operators.expectations
  • qiskit.aqua.operators.gradients
  • qiskit.aqua.operators.legacy
  • qiskit.aqua.operators.list_ops
  • qiskit.aqua.operators.primitive_ops
  • qiskit.aqua.operators.state_fns
  • qiskit.aqua.utils

Qiskit Ignis

  • qiskit.ignis
  • qiskit.ignis.characterization
  • qiskit.ignis.logging
  • qiskit.ignis.measurement
  • qiskit.ignis.mitigation
  • qiskit.ignis.verification
  • qiskit.ignis.verification.basis

Finance

  • qiskit.finance
  • qiskit.finance.applications
  • qiskit.finance.applications.ising
  • qiskit.finance.applications.ising.portfolio
  • qiskit.finance.applications.ising.portfolio_diversification
  • qiskit.finance.components
  • qiskit.finance.components.uncertainty_problems
  • qiskit.finance.data_providers

Chemistry

  • qiskit.chemistry
  • qiskit.chemistry.algorithms
  • qiskit.chemistry.algorithms.pes_samplers
  • qiskit.chemistry.applications
  • qiskit.chemistry.components
  • qiskit.chemistry.components.bosonic_bases
  • qiskit.chemistry.components.initial_states
  • qiskit.chemistry.components.variational_forms
  • qiskit.chemistry.core
  • qiskit.chemistry.drivers
  • qiskit.chemistry.drivers.gaussiand
  • qiskit.chemistry.drivers.psi4d
  • qiskit.chemistry.drivers.pyquanted
  • qiskit.chemistry.drivers.pyscfd
  • qiskit.chemistry.results
  • qiskit.chemistry.transformations

Machine Learning

  • qiskit.ml
  • qiskit.ml.circuit.library
  • qiskit.ml.datasets

Optimization

  • qiskit.optimization
  • qiskit.optimization.algorithms
  • qiskit.optimization.applications
  • qiskit.optimization.applications.ising
  • qiskit.optimization.applications.ising.clique
  • qiskit.optimization.applications.ising.common
  • qiskit.optimization.applications.ising.docplex
  • qiskit.optimization.applications.ising.exact_cover
  • qiskit.optimization.applications.ising.graph_partition
  • qiskit.optimization.applications.ising.knapsack
  • qiskit.optimization.applications.ising.max_cut
  • qiskit.optimization.applications.ising.partition
  • qiskit.optimization.applications.ising.set_packing
  • qiskit.optimization.applications.ising.stable_set
  • qiskit.optimization.applications.ising.tsp
  • qiskit.optimization.applications.ising.vehicle_routing
  • qiskit.optimization.applications.ising.vertex_cover
  • qiskit.optimization.converters
  • qiskit.optimization.problems

This was referenced Apr 29, 2024
Merged
Merged
github-merge-queue bot pushed a commit that referenced this issue Apr 30, 2024
@Eric-Arellano
Remove confusing API index pages in Qiskit 0.19 (#1258)
977d53d 
## Problem

This is how Qiskit 0.19 looks:

<img width="260" alt="Screenshot 2024-04-29 at 5 00 14 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/151d56df-09d2-47c6-885b-a8ce6f6e931a">

The three `qiskit` entries are:

https://docs.quantum.ibm.com/api/qiskit/0.19
https://docs.quantum.ibm.com/api/qiskit/0.19/ibmq-provider
https://docs.quantum.ibm.com/api/qiskit/0.19/aqua

0.19 is the only version like that, e.g. Qiskit 0.24 doesn't have
duplicates:

<img width="266" alt="Screenshot 2024-04-29 at 5 00 36 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/93f4c64e-7427-41d3-9deb-ae8f5ebcd758">

In 0.19 docs, the first two `qiskit` entries are index pages for Qiskit
Aqua and Qiskit IBMQ Provider. Those are index pages that simply list
all modules, rather than module overview pages that describe the modules
`qiskit.aqua` and `qiskit.providers.ibmq`.

Having the three duplicate `qiskit` entries is going to be a problem
with #1211 when we group
modules.

## Solution

I simply deleted the two index files from the HTML and regenerated the
docs. If we like this PR, I will upload that HTML change to Box.

I went with deletion because it's the simplest fix. We don't have these
index pages in every version after 0.19, and it works fine.
#1211 will also help with
module discovery through better grouping.

We could instead rewrite the HTML for the two problematic files, but I
figured it's fine to do the simpler approach that's consistent with
later versions.
@Eric-Arellano Eric-Arellano self-assigned this Apr 30, 2024
@Eric-Arellano Eric-Arellano mentioned this issue May 2, 2024
Merged
@javabster javabster moved this to In Review in Docs Planning May 6, 2024
github-merge-queue bot pushed a commit that referenced this issue May 7, 2024
@Eric-Arellano
Group Qiskit table of contents into sections (#1255)
6ca32f3 
Closes #1211. See
Qiskit/qiskit#12333 for the sibling PR in
Qiskit. We'll land the test
#1300 once both PRs have
landed.

This uses the same grouping as
#1211 (comment),
if people prefer reviewing the list over code.

Before:
<img width="254" alt="Screenshot 2024-05-01 at 10 27 43 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/5b503347-accd-4847-a7e2-aedf3546fcba">

After:

<img width="269" alt="Screenshot 2024-05-01 at 10 28 02 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c1a358f6-26f5-4e6e-80e9-2ee440eec94f">

<img width="272" alt="Screenshot 2024-05-01 at 10 28 15 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c3c80ca7-96e5-4942-ac39-6795b9504277">

This also improves historical APIs

<img width="271" alt="Screenshot 2024-05-01 at 10 29 08 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/362cc70f-4c7e-49c4-9447-78af2a648452">
@github-project-automation github-project-automation bot moved this from In Review to Done in Docs Planning May 7, 2024
@mergify mergify bot mentioned this issue May 9, 2024
Merged
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
@Eric-Arellano
Flatten left table of contents for Runtime and Provider (Qiskit#1241)
4cd9729 
Closes Qiskit#1212. As explained
there, this is because:

1. Qiskit SDK is getting a bigger revamp in
Qiskit#1211 and it will also
flatten submodules, so we want to be consistent.
2. The module list is so short that it's useful to have the navbar be
flatter. It makes things less crowded and more discoverable.

Note that some of the Runtime provider pages aren't very useful...I
opened Qiskit#1240 to track
that.

For now, this is implemented as the `Pkg` constructor setting a boolean
argument for whether modules should be nested or not. I'm coming up with
an alternative—but similar factoring—while working on
Qiskit#1211. This PR is
~prework.

<img width="253" alt="Screenshot 2024-04-24 at 4 02 34 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/2bbbaa7f-e187-4170-b2c5-02273e340b07">

<img width="257" alt="Screenshot 2024-04-24 at 4 02 10 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/53816ee2-f7ee-4d1d-90a5-64d7795fd776">
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
@Eric-Arellano
Remove confusing API index pages in Qiskit 0.19 (Qiskit#1258)
34ce7ca 
## Problem

This is how Qiskit 0.19 looks:

<img width="260" alt="Screenshot 2024-04-29 at 5 00 14 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/151d56df-09d2-47c6-885b-a8ce6f6e931a">

The three `qiskit` entries are:

https://docs.quantum.ibm.com/api/qiskit/0.19
https://docs.quantum.ibm.com/api/qiskit/0.19/ibmq-provider
https://docs.quantum.ibm.com/api/qiskit/0.19/aqua

0.19 is the only version like that, e.g. Qiskit 0.24 doesn't have
duplicates:

<img width="266" alt="Screenshot 2024-04-29 at 5 00 36 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/93f4c64e-7427-41d3-9deb-ae8f5ebcd758">

In 0.19 docs, the first two `qiskit` entries are index pages for Qiskit
Aqua and Qiskit IBMQ Provider. Those are index pages that simply list
all modules, rather than module overview pages that describe the modules
`qiskit.aqua` and `qiskit.providers.ibmq`.

Having the three duplicate `qiskit` entries is going to be a problem
with Qiskit#1211 when we group
modules.

## Solution

I simply deleted the two index files from the HTML and regenerated the
docs. If we like this PR, I will upload that HTML change to Box.

I went with deletion because it's the simplest fix. We don't have these
index pages in every version after 0.19, and it works fine.
Qiskit#1211 will also help with
module discovery through better grouping.

We could instead rewrite the HTML for the two problematic files, but I
figured it's fine to do the simpler approach that's consistent with
later versions.
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
@Eric-Arellano
Group Qiskit table of contents into sections (Qiskit#1255)
9c5a5c4 
Closes Qiskit#1211. See
Qiskit/qiskit#12333 for the sibling PR in
Qiskit. We'll land the test
Qiskit#1300 once both PRs have
landed.

This uses the same grouping as
Qiskit#1211 (comment),
if people prefer reviewing the list over code.

Before:
<img width="254" alt="Screenshot 2024-05-01 at 10 27 43 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/5b503347-accd-4847-a7e2-aedf3546fcba">

After:

<img width="269" alt="Screenshot 2024-05-01 at 10 28 02 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c1a358f6-26f5-4e6e-80e9-2ee440eec94f">

<img width="272" alt="Screenshot 2024-05-01 at 10 28 15 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/c3c80ca7-96e5-4942-ac39-6795b9504277">

This also improves historical APIs

<img width="271" alt="Screenshot 2024-05-01 at 10 29 08 AM"
src="https://github.com/Qiskit/documentation/assets/14852634/362cc70f-4c7e-49c4-9447-78af2a648452">
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
Docs Planning
Archived in project
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Group Qiskit table of contents into sections Qiskit/documentation
2 participants
@Eric-Arellano @javabster