Provider and Runtime show modules as top-level in sidebar #561
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
Eric-Arellano
force-pushed
the
EA/runtime-index
branch
from
2ffd6e7 to
181527f
Compare
Eric-Arellano
force-pushed
the
EA/runtime-index
branch
from
181527f to
ca0aeb8
Compare
Eric-Arellano
changed the title
Eric-Arellano
force-pushed
the
EA/runtime-index
branch
from
ca0aeb8 to
eee79ac
Compare
Eric-Arellano
commented
Jan 2, 2024
| @@ -0,0 +1,66 @@ | |||
| --- | |||
There was a problem hiding this comment.
This used to be /index. It is the API page for the top-level module.
| @@ -1,66 +1,16 @@ | |||
| --- | |||
There was a problem hiding this comment.
This used to be ibm-provider.md (with -, not _). The only change we've made is the front matter / metadata.
Comment on lines
-22
to
-24
| "docs/start/__migration-guide-algorithms.md", | ||
| "docs/start/__migration-guide-opflow.md", | ||
| "docs/start/__migration-guide-qi.md", |
There was a problem hiding this comment.
These files don't exist anymore.
Comment on lines
-96
to
-101
| tocOptions: { | ||
| collapsed: true, | ||
| nestModule(id: string) { | ||
| return id.split(".").length > 2; | ||
| }, | ||
| }, |
There was a problem hiding this comment.
This is now the universal behavior.
| @@ -20,7 +20,14 @@ export function addFrontMatter<T extends SphinxToMdResult>( | |||
| ): void { | |||
| for (let result of results) { | |||
| let markdown = result.markdown; | |||
| if (result.meta.python_api_name) { | |||
| if (result.meta.hardcoded_frontmatter) { | |||
There was a problem hiding this comment.
The order of this if matters. If you hardcode the frontmatter, we use that no matter what. That will be important when we fix #66 to add a fallback like using the filename. We want to make sure we still use the hardcoded metadata for these two index files.
| test("generate a toc", () => { | ||
| const toc = generateToc(pkg, [ | ||
| { meta: {}, url: "/docs/runtime" }, |
There was a problem hiding this comment.
I changed this test to better reflect reality.
| `); | ||
| }); | ||
|
|
||
| test("nest modules", () => { |
There was a problem hiding this comment.
This test isn't necessary anymore since the nesting behavior is now consistent. The above test should cover this.
Eric-Arellano
requested review from
arnaucasau and
frankharkins
and removed request for
arnaucasau
arnaucasau
approved these changes
Jan 3, 2024
frankharkins
approved these changes
Jan 3, 2024
Is this the staging preview? That image is super out of date and we've had issues updating it. In production, the URL from the top nav bar is https://docs.quantum.ibm.com/api/qiskit-ibm-runtime and it takes you to the correct |
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this pull request
Jul 22, 2024
Closes Qiskit#558. Before: <img width="248" alt="Screenshot 2023-12-29 at 1 38 50 PM" src="https://github.com/Qiskit/documentation/assets/14852634/299bd13b-e681-4105-93b6-9525312c547a"> After: <img width="251" alt="Screenshot 2023-12-29 at 1 39 08 PM" src="https://github.com/Qiskit/documentation/assets/14852634/21c900af-b44c-4c69-9ac5-133bbc251b00"> This new left sidebar layout aligns with Qiskit. The consistency is useful, but also I think this new layout is more functional anyways. It reduces the amount of nesting. It also allows us to collapse the left sidebar by default, which we do in the rest of the docs. ## Changes index page Before, the index page was the description for the code components belonging to the top-level modules `qiskit_ibm_provider` and `qiskit_ibm_runtime`, rather than enumerating what all the modules are: Before: <img width="625" alt="Screenshot 2023-12-29 at 1 40 19 PM" src="https://github.com/Qiskit/documentation/assets/14852634/c2e08d6f-365e-4775-8719-c6aad01cc77a"> After: <img width="658" alt="Screenshot 2023-12-29 at 1 41 30 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4a58cdd7-48f3-4e28-a0e4-cb716f095e4e"> Note that this index page is not accessible from the left sidebar; it's not clear what we would call it. But you can access it from the top nav-bar: <img width="234" alt="Screenshot 2023-12-29 at 1 42 13 PM" src="https://github.com/Qiskit/documentation/assets/14852634/4c9ebdd7-9bf2-45ed-8c3b-b998d319d5ec"> ## Metadata The new index pages have never had metadata. That's because we don't have any technique to determine from Sphinx programatically its metadata because the Sphinx generated HTML page is missing it: https://github.com/Qiskit/documentation/blob/60c836afbf30729fa30a97086b5812b08970ded5/scripts/lib/sphinx/PythonObjectMeta.ts#L13-L24 This is an instance of Qiskit#66. I think we need a generic solution to that problem, such as Axel's suggestion to use filenames as a fallback. But, it's important that the metadata is high quality for these two index pages since they are so high-profile. So, I propose hardcoding the metadata for them. Because there are only two files, I think this approach is acceptable; obviously it wouldn't scale if we were hardcoding dozens of files.
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.
Closes #558.
Before:
After:
This new left sidebar layout aligns with Qiskit. The consistency is useful, but also I think this new layout is more functional anyways. It reduces the amount of nesting. It also allows us to collapse the left sidebar by default, which we do in the rest of the docs.
Changes index page
Before, the index page was the description for the code components belonging to the top-level modules
qiskit_ibm_providerandqiskit_ibm_runtime, rather than enumerating what all the modules are:Before:
After:
Note that this index page is not accessible from the left sidebar; it's not clear what we would call it. But you can access it from the top nav-bar:
Metadata
The new index pages have never had metadata. That's because we don't have any technique to determine from Sphinx programatically its metadata because the Sphinx generated HTML page is missing it:
https://github.com/Qiskit/documentation/blob/92b3fa45c10aa917c3fbc7ada861b2db55203902/scripts/lib/sphinx/PythonObjectMeta.ts#L13-L24
This is an instance of #66. I think we need a generic solution to that problem, such as Axel's suggestion to use filenames as a fallback. But, it's important that the metadata is high quality for these two index pages since they are so high-profile.
So, I propose hardcoding the metadata for them. Because there are only two files, I think this approach is acceptable; obviously it wouldn't scale if we were hardcoding dozens of files.