Reorganize API docs (backport #24) #29
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![mergify[bot]](https://avatars.githubusercontent.com/in/10562?s=60&v=4){kind=small}
## Changes ### Adds index page This page is important so that `docs.quantum.ibm.com/api/qiskit-addon-obp` does not 404. It should simply be a flat list of every documented module. ### Flattens submodules We've gotten prior user complaints that they don't like when docs have a lot of nesting. So, docs.quantum.ibm.com expects all modules to be flattened to the same level in the left ToC. This means that users access submodules via the left ToC, rather than through the parent module's page. Due to this change, we delete qiskit_addon_obp.utils because it does not actually have any importable interfaces. If the module list ever gets too big, the qiskit/documentation repository has a mechanism to let you group modules into parent folders (see https://docs.quantum.ibm.com/api/qiskit). ### Sets module metadata & moves structural directives to RST The script in `qiskit/documentation` expects you to set ``(:mod:`qiskit_addon_obp`)`` at the top of every module page. We need this to extract metadata, which we use to set up the left ToC and `<head>` metadata for the page. We also now set all the `.. autodoc` directives like `.. autosummary` in RST. Sphinx [doesn't mix well](https://stackoverflow.com/questions/62855567/headings-when-using-autodoc-in-sphinx) when you have some structural elements like headings in RST and some in Python, so it's important to be consistent with where those structural elements go. Putting it in RST is more conventional, and it avoids us having to disable three Ruff lint rules. For modules, most the docs should be in the RST file other than a one-sentence summary of the module. ### Inlines functions and some classes We've gotten prior user complaints that they don't like when you have to click to a bunch of subpages to see individual functions and classes. So, we've generally adopted the approach of inlining functions and smaller classes. Larger classes and functions can still live on dedicated pages. The right page ToC makes it so that users can still jump around the page. This change is subjective. Feel free to push back if you think any particular interface should be a dedicated page! We set up client-redirects using sphinx-reredirects to avoid 404s. We used this extension well with Qiskit SDK. ## Results <details><summary>docs.quantum.ibm.com</summary> <img width="976" alt="Screenshot 2024-10-22 at 3 22 32 PM" src="https://github.com/user-attachments/assets/33bc2458-397f-4541-a7ba-2655b32c8c80"> </details> <details><summary>GitHub Pages</summary> <img width="289" alt="Screenshot 2024-10-22 at 3 31 20 PM" src="https://github.com/user-attachments/assets/70bd5d2a-fd05-4fd8-ad0d-efed379688bf"> <img width="625" alt="Screenshot 2024-10-22 at 3 31 23 PM" src="https://github.com/user-attachments/assets/9de98b41-d0b0-44b9-bcce-dbb1844b1057"> </details> (cherry picked from commit 9675e1b) # Conflicts: # qiskit_addon_obp/utils/__init__.py # qiskit_addon_obp/utils/metadata.py # qiskit_addon_obp/utils/operations.py # qiskit_addon_obp/utils/simplify.py # qiskit_addon_obp/utils/truncating.py # qiskit_addon_obp/utils/visualization.py
|
Cherry-pick of 9675e1b has failed: To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally |
|
@Mergifyio rebase stable/0.1 |
☑️ Nothing to do
|
Eric-Arellano
approved these changes
Oct 28, 2024
Pull Request Test Coverage Report for Build 11558986174Details
💛 - Coveralls |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
Adds index page
This page is important so that
docs.quantum.ibm.com/api/qiskit-addon-obpdoes not 404. It should simply be a flat list of every documented module.Flattens submodules
We've gotten prior user complaints that they don't like when docs have a lot of nesting. So, docs.quantum.ibm.com expects all modules to be flattened to the same level in the left ToC. This means that users access submodules via the left ToC, rather than through the parent module's page.
Due to this change, we delete qiskit_addon_obp.utils because it does not actually have any importable interfaces.
If the module list ever gets too big, the qiskit/documentation repository has a mechanism to let you group modules into parent folders (see https://docs.quantum.ibm.com/api/qiskit).
Sets module metadata & moves structural directives to RST
The script in
qiskit/documentationexpects you to set(:mod:`qiskit_addon_obp`)at the top of every module page. We need this to extract metadata, which we use to set up the left ToC and<head>metadata for the page.We also now set all the
.. autodocdirectives like.. autosummaryin RST. Sphinx doesn't mix well when you have some structural elements like headings in RST and some in Python, so it's important to be consistent with where those structural elements go. Putting it in RST is more conventional, and it avoids us having to disable three Ruff lint rules. For modules, most the docs should be in the RST file other than a one-sentence summary of the module.Inlines functions and some classes
We've gotten prior user complaints that they don't like when you have to click to a bunch of subpages to see individual functions and classes. So, we've generally adopted the approach of inlining functions and smaller classes. Larger classes and functions can still live on dedicated pages.
The right page ToC makes it so that users can still jump around the page.
This change is subjective. Feel free to push back if you think any particular interface should be a dedicated page!
We set up client-redirects using sphinx-reredirects to avoid 404s. We used this extension well with Qiskit SDK.
Results
docs.quantum.ibm.com
GitHub Pages
This is an automatic backport of pull request #24 done by [Mergify](https://mergify.com).