Missing method pages for Qiskit API docs before Qiskit 0.44 #542

Eric-Arellano · 2023-12-21T14:56:19Z

Until Qiskit 0.44 via Qiskit/qiskit#10455, in Qiskit docs, methods lived on dedicated HTML pages.

For some reason, when generating the historical API docs for Qiskit, the script failed to generate those method pages and it only generated class pages, module pages, and function pages. So, our redirects from qiskit.org to ibm.com are working properly but resulting in 404s because the method pages are not there.

This would have been caught by #495.

As explained in #543, we intentionally inlined methods/attributes into their class page via the file mergeClassMembers.ts. That in general worked great, but there are a couple of instances where it fails, like https://docs.quantum.ibm.com/api/qiskit/0.33/qiskit.result.Result mentioned in that PR description. We need to figure out why those failed and get them to work consistently.

The other issue was that I did not realize this inlining was happening when setting up redirects from qiskit.org to ibm.com, so we were trying to redirect method pages to non-existent method pages. I have a PR up for review to fix our redirect logic to instead go to the parent class's page.

To close this issue, we need to:

Properly inline all methods. That can be verified by running our link checker over these API docs and making sure that all internal links work.
Land the redirects change.

The text was updated successfully, but these errors were encountered:

Part of fixing #542. ## Methods living on dedicated pages Before Qiskit 0.44, methods lived on dedicated HTML pages. We changed that in Qiskit 0.44 because it resulted in horrible build-time performance when migrating `qiskit.org/documentation` from the old Pytorch theme to the new Furo theme, so that instead methods lived directly on their class pages. It looks like the script `updateApiDocs.ts` was trying to emulate methods living on class pages before Qiskit 0.44 through the file `mergeClassMembers.ts`. This code attempted to remove the method pages and instead have them live directly on the class pages. I believe the original script author had `mergeClassMembers.ts` to try to avoid performance issues. Until a fix a few weeks ago to the docs application, having a huge amount of pages would cause the site to load extremely slowly due to the left side bar being too large. That is now fixed because the left side bar is loaded dynamically rather than statically. ## `mergeClassMembers.ts` was causing problems 1. It looks like it wasn't behaving properly, at least some of the time. We did not exhaustively audit every page, but for example, https://docs.quantum.ibm.com/api/qiskit/0.33/qiskit.result.Result only had properties at the top, then a table summarizing all the methods below, but not the methods actually inlined: <img width="774" alt="Screenshot 2023-12-21 at 11 43 47 AM" src="https://github.com/Qiskit/documentation/assets/14852634/576ff54a-763c-484d-bc3b-42068693b0d1"> 2. We didn't know about this inlining when setting up qiskit.org redirects, which do a 1:1 mapping so that dedicated method pages take you to the dedicated method page on IBM, which was 404ing. ## Solution: allow dedicated method pages By deleting `mergeClassMembers.ts`, the script will properly generate dedicated HTML pages for each method. We took this approach—rather than instead fixing `mergeClassMembers.ts`—for a few reasons: 1. It allows us to avoid messing with our redirect rules, which are the 1:1 mapping. 2. We've gotten user feedback that the API docs are not as usable as they could be. We are planning to fix that in #479, but it won't be fixed in time for putting out the fire of #542. In the meantime, it is more user-friendly to have dedicated method pages for those historical API docs. The biggest reason we would not want to take this approach of dedicated method pages is the possible impact on performance mentioned above. But that has been fixed already in the IBM application. ## Impact of this PR No impact when generating docs where methods already live on class pages, like Qiskit 0.44+. For earlier Qiskit versions, it results in the method pages being generated. Those will be added in follow up PRs. --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

The generation script was not inlining all the methods in the class pages because we weren't assigning the correct value to the `python_api_name` metadata. With this PR, we change the way we search for the id we set as the name in the `sphinxHtmlToMarkdown.ts` The problem comes from we are missing the class `sig-object` in the `dt` tags we used to extract the `python_api_name` metadata in the HTML used to generate the markdown API files. We actually don't need to specify the class because the `dt` tag we are looking for is unique, and this PR fixes that. Moreover, the changes introduced in #543 are reverted to recover the mergeClassMembers.ts script that we need to inline all the methods in historical versions. Tested the generation of Qiskit 0.33, where we will inline the methods in a follow-up, and also the generation of Qiskit 0.45 to validate we are not modifying any version that was working previously. Commands used (Notice we need to have the API docs downloaded in .out): > npm run gen-api -- -p qiskit -v 0.33.0 -a "" --historical > npm run gen-api -- -p qiskit -v 0.45.0 -a "" Part of #542

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.42. The rest of the versions will be added in follow-up PRs in batches of two versions.

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.41.

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.33. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.40 and 0.39. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.38 and 0.37. All the GitHub source links work!

Part of #542 and #681. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.36. In addition, this PR corrects one part of the problem we have with versions 0.36, 0.35, and 0.34. Those three versions have the documentation of the next version instead of its own. The rest of the versions will be corrected in a follow-up All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.35. In addition, this PR corrects one part of the problem we have with versions 0.36, 0.35, and 0.34 described in #681. Those three versions have the documentation of the next version instead of its own. The rest of the versions will be corrected in a follow-up. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.27. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.25. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.26. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.24. All the GitHub source links work!

Part of #542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.19. **Broken GitHub source links:** https://github.com/qiskit-community/qiskit-aqua/tree/stable/0.7/qiskit/optimization/converters/quadratic_program_to_negative_value_oracle.py The link is correct but the files was removed and we can't access to the latest content of that branch. This PR manually fixes that link to instead of pointing to the stable branch, go to the latest tag that had the file. The new link is: https://github.com/qiskit-community/qiskit-aqua/tree/0.7.3/qiskit/optimization/converters/quadratic_program_to_negative_value_oracle.py

Eric-Arellano · 2024-01-24T22:26:35Z

Every version of the API docs has been regenerated. This should be fixed. Thanks @arnaucasau 🚀

Part of fixing Qiskit#542. ## Methods living on dedicated pages Before Qiskit 0.44, methods lived on dedicated HTML pages. We changed that in Qiskit 0.44 because it resulted in horrible build-time performance when migrating `qiskit.org/documentation` from the old Pytorch theme to the new Furo theme, so that instead methods lived directly on their class pages. It looks like the script `updateApiDocs.ts` was trying to emulate methods living on class pages before Qiskit 0.44 through the file `mergeClassMembers.ts`. This code attempted to remove the method pages and instead have them live directly on the class pages. I believe the original script author had `mergeClassMembers.ts` to try to avoid performance issues. Until a fix a few weeks ago to the docs application, having a huge amount of pages would cause the site to load extremely slowly due to the left side bar being too large. That is now fixed because the left side bar is loaded dynamically rather than statically. ## `mergeClassMembers.ts` was causing problems 1. It looks like it wasn't behaving properly, at least some of the time. We did not exhaustively audit every page, but for example, https://docs.quantum.ibm.com/api/qiskit/0.33/qiskit.result.Result only had properties at the top, then a table summarizing all the methods below, but not the methods actually inlined: <img width="774" alt="Screenshot 2023-12-21 at 11 43 47 AM" src="https://github.com/Qiskit/documentation/assets/14852634/576ff54a-763c-484d-bc3b-42068693b0d1"> 2. We didn't know about this inlining when setting up qiskit.org redirects, which do a 1:1 mapping so that dedicated method pages take you to the dedicated method page on IBM, which was 404ing. ## Solution: allow dedicated method pages By deleting `mergeClassMembers.ts`, the script will properly generate dedicated HTML pages for each method. We took this approach—rather than instead fixing `mergeClassMembers.ts`—for a few reasons: 1. It allows us to avoid messing with our redirect rules, which are the 1:1 mapping. 2. We've gotten user feedback that the API docs are not as usable as they could be. We are planning to fix that in Qiskit#479, but it won't be fixed in time for putting out the fire of Qiskit#542. In the meantime, it is more user-friendly to have dedicated method pages for those historical API docs. The biggest reason we would not want to take this approach of dedicated method pages is the possible impact on performance mentioned above. But that has been fixed already in the IBM application. ## Impact of this PR No impact when generating docs where methods already live on class pages, like Qiskit 0.44+. For earlier Qiskit versions, it results in the method pages being generated. Those will be added in follow up PRs. --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

The generation script was not inlining all the methods in the class pages because we weren't assigning the correct value to the `python_api_name` metadata. With this PR, we change the way we search for the id we set as the name in the `sphinxHtmlToMarkdown.ts` The problem comes from we are missing the class `sig-object` in the `dt` tags we used to extract the `python_api_name` metadata in the HTML used to generate the markdown API files. We actually don't need to specify the class because the `dt` tag we are looking for is unique, and this PR fixes that. Moreover, the changes introduced in Qiskit#543 are reverted to recover the mergeClassMembers.ts script that we need to inline all the methods in historical versions. Tested the generation of Qiskit 0.33, where we will inline the methods in a follow-up, and also the generation of Qiskit 0.45 to validate we are not modifying any version that was working previously. Commands used (Notice we need to have the API docs downloaded in .out): > npm run gen-api -- -p qiskit -v 0.33.0 -a "" --historical > npm run gen-api -- -p qiskit -v 0.45.0 -a "" Part of Qiskit#542

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.42. The rest of the versions will be added in follow-up PRs in batches of two versions.

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.41.

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.33. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.40 and 0.39. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.38 and 0.37. All the GitHub source links work!

Part of Qiskit#542 and Qiskit#681. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the versions 0.36. In addition, this PR corrects one part of the problem we have with versions 0.36, 0.35, and 0.34. Those three versions have the documentation of the next version instead of its own. The rest of the versions will be corrected in a follow-up All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.35. In addition, this PR corrects one part of the problem we have with versions 0.36, 0.35, and 0.34 described in Qiskit#681. Those three versions have the documentation of the next version instead of its own. The rest of the versions will be corrected in a follow-up. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.32. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.31. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.30. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.29. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.28. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.27. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.25. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.26. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.24. All the GitHub source links work!

Part of Qiskit#542. Regeneration of the Qiskit API docs (historical versions) with the methods inlined and the GitHub source links. Given the number of files modified, the regeneration is split into different PRs. This one only updates the version 0.19. **Broken GitHub source links:** https://github.com/qiskit-community/qiskit-aqua/tree/stable/0.7/qiskit/optimization/converters/quadratic_program_to_negative_value_oracle.py The link is correct but the files was removed and we can't access to the latest content of that branch. This PR manually fixes that link to instead of pointing to the stable branch, go to the latest tag that had the file. The new link is: https://github.com/qiskit-community/qiskit-aqua/tree/0.7.3/qiskit/optimization/converters/quadratic_program_to_negative_value_oracle.py

github-project-automation bot added this to Docs Planning Dec 21, 2023

Eric-Arellano self-assigned this Dec 21, 2023

Eric-Arellano added the infra 🏗️ label Dec 21, 2023

Eric-Arellano added this to the 24-02-13 Qiskit 1.0 milestone Dec 21, 2023

Eric-Arellano mentioned this issue Dec 21, 2023

Allow dedicated page for each method #543

Merged

Eric-Arellano mentioned this issue Dec 21, 2023

Add missing method pages for Qiskit 0.19 to Qiskit 0.33 #546

Closed

arnaucasau mentioned this issue Dec 22, 2023

Inline all methods for Qiskit API #552

Merged

arnaucasau mentioned this issue Jan 5, 2024

Regeneration Qiskit historical versions with methods inlined #588

Closed

Eric-Arellano mentioned this issue Jan 10, 2024

Redirects: set up ibm.com redirects for methods #615

Closed

Eric-Arellano moved this to In Progress in Docs Planning Jan 16, 2024

javabster assigned arnaucasau Jan 16, 2024

arnaucasau mentioned this issue Jan 17, 2024

Regeneration Qiskit API historical docs v0.44-v0.42 #637

Closed

Eric-Arellano removed their assignment Jan 19, 2024

This was referenced Jan 19, 2024

Add GitHub links to Qiskit v0.44 API docs #653

Merged

Regeneration Qiskit v0.42 API docs #658

Merged

arnaucasau mentioned this issue Jan 22, 2024

Regeneration Qiskit v0.41 API docs #664

Merged

arnaucasau mentioned this issue Jan 22, 2024

Regeneration Qiskit v0.33 API docs #667

Merged

arnaucasau mentioned this issue Jan 22, 2024

Regeneration Qiskit v0.40 and v0.39 API docs #672

Merged

arnaucasau mentioned this issue Jan 23, 2024

Regeneration Qiskit v0.38 and v0.37 API docs #678

Merged

arnaucasau mentioned this issue Jan 23, 2024

Regeneration Qiskit v0.36 API docs #680

Merged

arnaucasau mentioned this issue Jan 23, 2024

Regeneration Qiskit v0.35 API docs #682

Merged

arnaucasau mentioned this issue Jan 24, 2024

Regeneration Qiskit v0.19 API docs #698

Merged

Eric-Arellano closed this as completed Jan 24, 2024

github-project-automation bot moved this from In Progress to Done in Docs Planning Jan 24, 2024

Eric-Arellano mentioned this issue Jan 30, 2024

Check links for API docs (Qiskit 0.46+) #495

Closed

javabster removed this from Docs Planning Feb 6, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Missing method pages for Qiskit API docs before Qiskit 0.44 #542

Missing method pages for Qiskit API docs before Qiskit 0.44 #542

Eric-Arellano commented Dec 21, 2023 •

edited

Loading

Eric-Arellano commented Jan 24, 2024

Missing method pages for Qiskit API docs before Qiskit 0.44 #542

Missing method pages for Qiskit API docs before Qiskit 0.44 #542

Comments

Eric-Arellano commented Dec 21, 2023 • edited Loading

Eric-Arellano commented Jan 24, 2024

Eric-Arellano commented Dec 21, 2023 •

edited

Loading