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

Reorganize API docs (backport #24) #29

Merged
merged 3 commits into from
Oct 28, 2024
Merged

Reorganize API docs (backport #24) #29

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e8656ee
Reorganize API docs (#24)
Eric-Arellano Oct 28, 2024
8d5c8fe
Fix merge conflicts
Eric-Arellano Oct 28, 2024
5f94f19
Merge branch 'stable/0.1' into mergify/bp/stable/0.1/pr-24
Eric-Arellano Oct 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/apidocs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
**********************************
``qiskit-addon-obp`` API reference
**********************************

.. toctree::
:maxdepth: 1

qiskit_addon_obp
qiskit_addon_obp.utils.metadata
qiskit_addon_obp.utils.operations
qiskit_addon_obp.utils.simplify
qiskit_addon_obp.utils.truncating
qiskit_addon_obp.utils.visualization
12 changes: 7 additions & 5 deletions docs/apidocs/qiskit_addon_obp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
============================================
Qiskit addon: operator backpropagation (OBP)
============================================

.. _qiskit_addon_obp:
==================================================
Operator backpropagation (:mod:`qiskit_addon_obp`)
==================================================

.. automodule:: qiskit_addon_obp
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp

.. autofunction:: backpropagate
17 changes: 12 additions & 5 deletions docs/apidocs/qiskit_addon_obp.utils.metadata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,17 @@
========
metadata
========

.. _qiskit_addon_obp-utils-metadata:
===========================================================
Metadata utilities (:mod:`qiskit_addon_obp.utils.metadata`)
===========================================================

.. automodule:: qiskit_addon_obp.utils.metadata
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp.utils.metadata

.. autosummary::
:toctree: ../stubs/
:nosignatures:

OBPMetadata
SliceMetadata
15 changes: 10 additions & 5 deletions docs/apidocs/qiskit_addon_obp.utils.operations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
==========
operations
==========

.. _qiskit_addon_obp-utils-operations:
=============================================================
Operator utilities (:mod:`qiskit_addon_obp.utils.operations`)
=============================================================

.. automodule:: qiskit_addon_obp.utils.operations
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp.utils.operations

.. autofunction:: apply_op_to
.. autofunction:: apply_reset_to
.. autofunction:: to_global_op
.. autofunction:: reduce_op
10 changes: 0 additions & 10 deletions docs/apidocs/qiskit_addon_obp.utils.rst
View file
Open in desktop

This file was deleted.

14 changes: 9 additions & 5 deletions docs/apidocs/qiskit_addon_obp.utils.simplify.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
========
simplify
========

.. _qiskit_addon_obp-utils-simplify:
======================================================================
Pauli operator simplification (:mod:`qiskit_addon_obp.utils.simplify`)
======================================================================

.. automodule:: qiskit_addon_obp.utils.simplify
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp.utils.simplify

.. autoclass:: OperatorBudget
.. autoclass:: SimplifyMetadata
.. autofunction:: simplify
14 changes: 9 additions & 5 deletions docs/apidocs/qiskit_addon_obp.utils.truncating.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
==========
truncating
==========

.. _qiskit_addon_obp-utils-truncating:
===============================================================
Truncation utilities (:mod:`qiskit_addon_obp.utils.truncating`)
===============================================================

.. automodule:: qiskit_addon_obp.utils.truncating
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp.utils.truncating

.. autoclass:: TruncationErrorBudget
.. autofunction:: setup_budget
.. autofunction:: truncate_binary_search
18 changes: 13 additions & 5 deletions docs/apidocs/qiskit_addon_obp.utils.visualization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
=============
visualization
=============

.. _qiskit_addon_obp-utils-visualization:
=====================================================================
Visualization utilities (:mod:`qiskit_addon_obp.utils.visualization`)
=====================================================================

.. automodule:: qiskit_addon_obp.utils.visualization
:no-members:
:no-inherited-members:
:no-special-members:

.. currentmodule:: qiskit_addon_obp.utils.visualization

.. autofunction:: plot_accumulated_error
.. autofunction:: plot_left_over_error_budget
.. autofunction:: plot_slice_errors
.. autofunction:: plot_num_paulis
.. autofunction:: plot_num_truncated_paulis
.. autofunction:: plot_sum_paulis
.. autofunction:: plot_num_qwc_groups
33 changes: 33 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@
"sphinx.ext.intersphinx",
"matplotlib.sphinxext.plot_directive",
"sphinx_copybutton",
"sphinx_reredirects",
"reno.sphinxext",
"nbsphinx",
"qiskit_sphinx_theme",
Expand Down Expand Up @@ -108,6 +109,38 @@
plot_working_directory = "."
plot_html_show_source_link = False

# ----------------------------------------------------------------------------------
# Redirects
# ----------------------------------------------------------------------------------

_inlined_apis = [
("qiskit_addon_obp", "backpropagate"),
("qiskit_addon_obp.utils.operations", "apply_op_to"),
("qiskit_addon_obp.utils.operations", "to_global_op"),
("qiskit_addon_obp.utils.operations", "reduce_op"),
("qiskit_addon_obp.utils.simplify", "OperatorBudget"),
("qiskit_addon_obp.utils.simplify", "SimplifyMetadata"),
("qiskit_addon_obp.utils.simplify", "simplify"),
("qiskit_addon_obp.utils.truncating", "TruncationErrorBudget"),
("qiskit_addon_obp.utils.truncating", "setup_budget"),
("qiskit_addon_obp.utils.truncating", "truncate_binary_search"),
("qiskit_addon_obp.utils.visualization", "plot_accumulated_error"),
("qiskit_addon_obp.utils.visualization", "plot_left_over_error_budget"),
("qiskit_addon_obp.utils.visualization", "plot_slice_errors"),
("qiskit_addon_obp.utils.visualization", "plot_num_paulis"),
("qiskit_addon_obp.utils.visualization", "plot_num_truncated_paulis"),
("qiskit_addon_obp.utils.visualization", "plot_sum_paulis"),
("qiskit_addon_obp.utils.visualization", "plot_num_qwc_groups"),
]

redirects = {
"apidocs/qiskit_addon_obp.utils": "./index.html",
**{
f"stubs/{module}.{name}": f"../apidocs/{module}.html#{module}.{name}"
for module, name in _inlined_apis
},
}

# ----------------------------------------------------------------------------------
# Source code links
# ----------------------------------------------------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,6 @@ License
Installation Instructions <install>
Tutorials <tutorials/index>
How-To Guides <how_tos/index>
API Reference <apidocs/qiskit_addon_obp>
API Reference <apidocs/index>
GitHub <https://github.com/Qiskit/qiskit-addon-obp>
Release Notes <release-notes>
1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ docs = [
"jupyter-sphinx",
"sphinx-design",
"sphinx-autodoc-typehints",
"sphinx-reredirects",
"sphinx-copybutton",
"nbsphinx>=0.9.4",
"reno>=4.1",
Expand Down
20 changes: 2 additions & 18 deletions qiskit_addon_obp/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""Main operator backpropagation functionality.

.. currentmodule:: qiskit_addon_obp

.. autosummary::
:toctree: ../stubs/
:nosignatures:

backpropagate

Submodules
==========

.. autosummary::
:toctree:

utils
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Main operator backpropagation functionality."""

from .backpropagation import backpropagate

Expand Down
18 changes: 4 additions & 14 deletions qiskit_addon_obp/utils/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,7 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Utility functionality for conducting operator backpropagation.

.. currentmodule:: qiskit_addon_obp.utils

.. autosummary::
:toctree:

metadata
operations
simplify
truncating
visualization
"""
# Warning: this module is not documented and it does not have an RST file.
# If we ever publicly expose interfaces users can import from this module,
# we should set up its RST file.
"""Utility functionality for conducting operator backpropagation."""
14 changes: 2 additions & 12 deletions qiskit_addon_obp/utils/metadata.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Container classes for holding backpropagation metadata.

.. currentmodule:: qiskit_addon_obp.utils.metadata

.. autosummary::
:toctree: ../stubs/
:nosignatures:

OBPMetadata
SliceMetadata
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Container classes for holding backpropagation metadata."""

from __future__ import annotations

Expand Down
15 changes: 2 additions & 13 deletions qiskit_addon_obp/utils/operations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Utility functions for operator backpropagation.

.. currentmodule:: qiskit_addon_obp.utils.operations

.. autosummary::
:toctree: ../stubs/
:nosignatures:

apply_op_to
to_global_op
reduce_op
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Utility functions for operator backpropagation."""

from __future__ import annotations

Expand Down
15 changes: 2 additions & 13 deletions qiskit_addon_obp/utils/simplify.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Functions for simplifying Pauli operators.

.. currentmodule:: qiskit_addon_obp.utils.simplify

.. autosummary::
:toctree: ../stubs/
:nosignatures:

OperatorBudget
SimplifyMetadata
simplify
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Functions for simplifying Pauli operators."""

from __future__ import annotations

Expand Down
15 changes: 2 additions & 13 deletions qiskit_addon_obp/utils/truncating.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Functions for truncating Pauli operators within given error budgets.

.. currentmodule:: qiskit_addon_obp.utils.truncating

.. autosummary::
:toctree: ../stubs/
:nosignatures:

TruncationErrorBudget
setup_budget
truncate_binary_search
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Functions for truncating Pauli operators within given error budgets."""

from __future__ import annotations

Expand Down
19 changes: 2 additions & 17 deletions qiskit_addon_obp/utils/visualization.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,8 @@
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

"""
Various visualization utilities.

.. currentmodule:: qiskit_addon_obp.utils.visualization

.. autosummary::
:toctree: ../stubs/
:nosignatures:

plot_accumulated_error
plot_left_over_error_budget
plot_slice_errors
plot_num_paulis
plot_num_truncated_paulis
plot_sum_paulis
plot_num_qwc_groups
"""
# Reminder: update the RST file in docs/apidocs when adding new interfaces.
"""Various visualization utilities."""

from __future__ import annotations

Expand Down