qiskit
qiskit copied to clipboard
Qiskit
Deprecate warning box in docs
Summary
Following https://github.com/Qiskit/qiskit/pull/1592/, this PR extend deprecate_arguments and deprecate_function so they add a deprecation box note in the docstring.
Thank you for opening a new pull request.
Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.
While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.
One or more of the the following people are requested to review this:
- @Qiskit/terra-core
Pull Request Test Coverage Report for Build 4005589012
- 75 of 76 (98.68%) changed or added relevant lines in 7 files are covered.
- 65 unchanged lines in 2 files lost coverage.
- Overall coverage increased (+0.04%) to 84.937%
| Changes Missing Coverage | Covered Lines | Changed/Added Lines | % |
|---|---|---|---|
| qiskit/utils/deprecation.py | 63 | 64 | 98.44% |
| <!-- | Total: | 75 | 76 |
| Files with Coverage Reduction | New Missed Lines | % |
|---|---|---|
| src/sabre_swap/layer.rs | 2 | 98.95% |
| qiskit/visualization/state_visualization.py | 63 | 57.41% |
| <!-- | Total: | 65 |
| Totals | |
|---|---|
| Change from base Build 4001377713: | 0.04% |
| Covered Lines: | 66729 |
| Relevant Lines: | 78563 |
💛 - Coveralls
From @kdk:
Can you post a screenshot of how this will show up in the docs?
Because of https://github.com/Qiskit/qiskit_sphinx_theme/issues/71, the current look is not the best.
On hold, since qiskit_sphinx_theme needs to be released with https://github.com/Qiskit/qiskit_sphinx_theme/issues/71 in order to support this. And current qiskit_sphinx_theme req needs to be bump.
Can you post a screenshot of how this will show up in the docs?
For deprecate_function:
For deprecate_argument:
When I implemented it broadly, I realize of an unintended benefit. It is very easy now to see deprecation that needs removing:
$ grep -orh "since=\".*\"" qiskit | sort | uniq -c
3 docstring_version="0.15.0"
5 docstring_version="0.15.1"
6 docstring_version="0.16.0"
2 docstring_version="0.17.0"
1 docstring_version="0.18.0"
2 docstring_version="0.19.0"
1 docstring_version="0.20.0"
6 docstring_version="0.21.0"
14 docstring_version="0.22.0"
While we all agree with the final result. This implementation penalises import time and requiere a parser (either "in-house" or a dependency). So new plan is:
- to use the decorator to extend
__qiskit_deprecation__metadata attribute in the function/method - write a sphinx extension in https://github.com/Qiskit/qiskit_sphinx_theme to take that metadata and extend the docstring.