Deprecate warning box in docs

[1ucian0]

Summary

Following #1592, this PR extend deprecate_arguments and deprecate_function so they add a deprecation box note in the docstring.

[qiskit-bot]

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

[coveralls]

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%

Files with Coverage Reduction	New Missed Lines	%
src/sabre_swap/layer.rs	2	98.95%
qiskit/visualization/state_visualization.py	63	57.41%

Totals
Change from base Build 4001377713:	0.04%
Covered Lines:	66729
Relevant Lines:	78563

---

💛 - Coveralls

[kdk]

Can you post a screenshot of how this will show up in the docs?

[1ucian0]

From @kdk:

Can you post a screenshot of how this will show up in the docs?

Because of Qiskit/qiskit_sphinx_theme#71, the current look is not the best.

[1ucian0]

On hold, since qiskit_sphinx_theme needs to be released with Qiskit/qiskit_sphinx_theme#71 in order to support this. And current qiskit_sphinx_theme req needs to be bump.

[1ucian0]

qiskit_sphinx_theme 1.9 released. removing on hold.

[1ucian0]

Can you post a screenshot of how this will show up in the docs?

For deprecate_function:

For deprecate_argument:

[1ucian0]

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.

[1ucian0]

Closing this in favor of #9616