Switch to using the sphinx-autoapi extension for auto building the API reference. It better maintained and produces nicer formatted docs.
#1030
Conversation
…API reference. It better maintained and produces nicer formatted docs.
There was a problem hiding this comment.
After running ./checks/build_docs.py locally I get
WARNING: Cannot resolve import of cirq_superstaq.ops.qubit_gates.AQTICCX in cirq_superstaq.ops
WARNING: Cannot resolve import of cirq_superstaq.ops.qubit_gates.AQTITOFFOLI in cirq_superstaq.ops
WARNING: Cannot resolve import of cirq_superstaq.ops.qubit_gates.CR in cirq_superstaq.ops
WARNING: Cannot resolve import of cirq_superstaq.ops.qubit_gates.ZX in cirq_superstaq.ops
WARNING: Cannot resolve import of cirq_superstaq.ops.AQTICCX in cirq_superstaq
WARNING: Cannot resolve import of cirq_superstaq.ops.AQTITOFFOLI in cirq_superstaq
WARNING: Cannot resolve import of cirq_superstaq.ops.CR in cirq_superstaq
WARNING: Cannot resolve import of cirq_superstaq.ops.ZX in cirq_superstaq
but the docs do indeed build. I think it's fine to merge this and fix the warnings in follow-up PRs.
Turns out Sphinx didn't like the double = signs so I changed that. I also fixed (hopefully!) all the other warnings that Sphinx was generating. It might be worth in future having the build fail if there are any Sphinx warnings. |
There was a problem hiding this comment.
adding a few nits - leaving the big picture review to @vtomole
we should also check that this works w/ the other repo before merging
cirq-superstaq/cirq_superstaq/job.py
Outdated
| gss.SuperstaqServerException: If unable to get the status of the job from the API or | ||
| cancellations were unsuccessful. | ||
| general_superstaq.SuperstaqServerException: If unable to get the status of the job | ||
| from the API orcancellations were unsuccessful. |
There was a problem hiding this comment.
honestly i kinda like the smaller indent here so maybe it's worth reconsidering, but i think our style specifies four spaces instead of three for these indents
| from the API orcancellations were unsuccessful. | |
| from the API orcancellations were unsuccessful. |
(same occurs elsewhere in this pr)
There was a problem hiding this comment.
This was an oversight on my part sorry. I've always used 3-spaces for indenting docstrings and thought this was a requirement, when it turns out its not. I have hopefully now fixed all the places I modified this
cirq-superstaq/cirq_superstaq/job.py
Outdated
| general_superstaq.SuperstaqServerException: If unable to get the status of the job | ||
| from the API. |
There was a problem hiding this comment.
is this allowed?
| general_superstaq.SuperstaqServerException: If unable to get the status of the job | |
| from the API. | |
| SuperstaqServerException: If unable to get the status of the job from the API. |
not super important but it'd be nice not to have to write out general_superstaq in docstrings when we use gss everywhere else
There was a problem hiding this comment.
I don't think this is possible but I'll look into it.
There was a problem hiding this comment.
I managed to fix this so we can continue using gss, css, and qss in docstrings. Note that the ~ which I have now included is there to make the compiled documentation look nicer by suppressing the general_superstaq in the return type.
| @@ -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") | |||
|
|
|||
There was a problem hiding this comment.
we might want to add something like
| if not os.path.isdir(os.path.join(docs_dir, "source")): | |
| print(check_utils.warning("No docs to build.")) | |
| return 0 |
|
@cdbf1 to confirm that this doesn't affect server docs, then this is good to go. |
@vtomole see the minor fixes that are needed for server-superstaq here: https://github.com/Infleqtion/server-superstaq/pull/3407 |
The sphinx auto-summary, auto-doc and apidoc extensions have more recently been improved upon by the single extension
sphinx-autoapiwhich I think is simpler and build nicer looking documentation.This PR updates our docs to use
sphinx-autoapi