Switch to using the sphinx-autoapi extension for auto building the API reference. It better maintained and produces nicer formatted docs.

checks-superstaq/checks_superstaq/all_.py

@@ -19,12 +19,11 @@
 )
 
 
-def run(*args: str, sphinx_paths: list[str] | None = None) -> int:
+def run(*args: str) -> int:
  """Runs all checks on the repository.
 
  Args:
  *args: Command line arguments.
- sphinx_paths: List of sphinx paths strings (used for building docs).
 
  Returns:
  Terminal exit code. 0 indicates success, while any other integer indicates a test failure.
@@ -96,7 +95,8 @@ def run(*args: str, sphinx_paths: list[str] | None = None) -> int:
  if default_mode:
  # checks that the docs build
  checks_failed |= build_docs.run(
- *args_to_pass, exit_on_failure=exit_on_failure, sphinx_paths=sphinx_paths
+ *args_to_pass,
+ exit_on_failure=exit_on_failure,
  )
 
  return checks_failed

checks-superstaq/checks_superstaq/build_docs.py

@@ -10,12 +10,11 @@
 
 
 @check_utils.enable_exit_on_failure
-def run(*args: str, sphinx_paths: list[str] | None = None) -> int:
+def run(*args: str) -> int:
  """Checks that the docs build successfully.
 
  Args:
  *args: Command line arguments.
- sphinx_paths: List of sphinx paths (passed to `sphinx-apidoc`).
 
  Returns:
  Terminal exit code. 0 indicates success, while any other integer indicates a test failure.
@@ -33,16 +32,7 @@ def run(*args: str, sphinx_paths: list[str] | None = None) -> int:
 
  docs_dir = os.path.join(check_utils.root_dir, "docs")
 
- if sphinx_paths:
- returncode = 0
- for path in sphinx_paths:
- returncode |= subprocess.call(
- ["sphinx-apidoc", "-f", "-o", "source", path, f"{path}/*_test.py"], cwd=docs_dir
- )
- return subprocess.call(["sphinx-build", "source", "build/html"], cwd=docs_dir)
- else:
- print(check_utils.warning("No docs to build."))
- return 0
+ return subprocess.call(["sphinx-build", "source", "build/html"], cwd=docs_dir)
 
 
 if __name__ == "__main__":

checks-superstaq/requirements.txt

@@ -19,4 +19,5 @@ pytest-socket>=0.7.0
 pytest-xdist>=3.6.1
 ruff>=0.5.6
 setuptools>=67.0.0
+sphinx-autoapi>=3.2.1
 sphinx-rtd-theme>=1.0.0

checks/build_docs.py

@@ -9,11 +9,5 @@
  exit(
  checks.build_docs.run(
  *sys.argv[1:],
- sphinx_paths=[
- "../cirq-superstaq",
- "../qiskit-superstaq",
- "../general-superstaq",
- "../supermarq-benchmarks",
- ],
  )
  )

docs/source/conf.py

@@ -23,11 +23,10 @@
 
 extensions = [
  "nbsphinx",
- "sphinx.ext.autodoc",
- "sphinx.ext.autosummary",
  "sphinx.ext.mathjax", # math rendering in html
  "sphinx.ext.napoleon", # allows google- and numpy- style docstrings
  "IPython.sphinxext.ipython_console_highlighting",
+ "autoapi.extension",
 ]
 
 # since our notebooks can involve network I/O (or even costing $), we don't want them to be
@@ -36,18 +35,30 @@
 
 # In addition, we set the mathjax path to v3, which allows \ket{} (and other commands) to render
 mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
-autosummary_generate = True
+autosummary_generate = False
 
 templates_path = ["_templates"]
 
-# Using `modules` in index.rst gets the first package and ignores additional included packages.
-# Listing out modules explicitly causes building docs to throw error looking for `modules.rst`,
-# so add to excluded search patterns as per suggestion here: https://stackoverflow.com/a/15438962
-exclude_patterns: list[str] = [
- "modules.rst",
- "setup.rst",
- "general_superstaq.check.rst",
- "cirq_superstaq.ops.rst",
+autoapi_dirs = [
+ "../../cirq-superstaq/cirq_superstaq",
+ "../../general-superstaq/general_superstaq",
+ "../../qiskit-superstaq/qiskit_superstaq",
+ "../../supermarq-benchmarks/supermarq",
+]
+autoapi_type = "python"
+
+autoapi_options = [
+ "members",
+ "undoc-members",
+ "show-inheritance",
+ "show-module-summary",
+ "special-members",
+ "imported-members",
+]
+
+autoapi_ignore = [
+ "*_test.py",
+ "*/checks/*.py",
 ]
 
 

docs/source/index.rst

@@ -75,8 +75,9 @@ Learn more about Superstaq `here <https://www.infleqtion.com/superstaq>`_. To co
 .. toctree::
  :maxdepth: 1
  :hidden:
- :caption: Clients
+ :caption: API Reference
 
- cirq_superstaq
- qiskit_superstaq
- general_superstaq
+ autoapi/cirq_superstaq/index
+ autoapi/general_superstaq/index
+ autoapi/qiskit_superstaq/index
+ autoapi/supermarq/index