Fix accidental deletion of GitHub source links for methods #940
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
frankharkins
approved these changes
Feb 29, 2024
scripts/lib/api/processHtml.test.ts
Outdated
| expect(result).toEqual( | ||
| `<a href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101" title="view source code">GitHub</a>`, | ||
| ` <a href="https://github.com/Qiskit/qiskit/blob/stable/1.0/qiskit/utils/deprecation.py#L24-L101" title="view source code">GitHub</a>`, |
There was a problem hiding this comment.
Is the extra space important? If so maybe a quick comment so we don't delete it at some point in the future
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this pull request
Jul 22, 2024
Part of Qiskit#517. Turns out that we would accidentally delete all the GitHub links for methods because we were using `closest().remove()` rather than `.closest().first().remove()`. That means that we'd only have the link for the class definition and not individual methods, which defeats the point of precise source code links from Qiskit#517. ## Historical API docs However, the behavior to not show methods is actually quite sensible for our API docs, where we were using `sphinx.ext.viewcode` rather than `sphinx.ext.linkcode`. That meant that we could only link to the overall file, rather than specific line numbers. So, it's not very useful to keep linking to the overall file for every method since they will each have the same value and the class definition already has the value. So, we check if the link is for a method and proactively remove it if so. This change to proactively remove method links changes some historical API doc versions, but not others. Why? It only removes the links if we were doing method inlining, where the method had a dedicated HTML page originally. That's because the `.remove()` line wouldn't impat the distinct HTML pages.
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.
Part of #517.
Turns out that we would accidentally delete all the GitHub links for methods because we were using
closest().remove()rather than.closest().first().remove(). That means that we'd only have the link for the class definition and not individual methods, which defeats the point of precise source code links from #517.Historical API docs
However, the behavior to not show methods is actually quite sensible for our API docs, where we were using
sphinx.ext.viewcoderather thansphinx.ext.linkcode. That meant that we could only link to the overall file, rather than specific line numbers. So, it's not very useful to keep linking to the overall file for every method since they will each have the same value and the class definition already has the value. So, we check if the link is for a method and proactively remove it if so.This change to proactively remove method links changes some historical API doc versions, but not others. Why? It only removes the links if we were doing method inlining, where the method had a dedicated HTML page originally. That's because the
.remove()line wouldn't impat the distinct HTML pages.