Another idea that I was going to do, but backed down from it,
Was the following:
https://review.openstack.org/#/c/155988/
Basically when a function would be marked with a debtcollector
decorator/deprecation stuff it would also mutate the docstring and add
on the rst section u just stated below.
Perhaps I should revive that?
Then this would avoid duplicating information that the decorator already
knows about (and it can construct it in a well-formed and standard manner).
For example with that patch.
>>> @removals.remove(version="1.8", removal_version="2.0", message="I
am broken")
... def old_busted():
... pass
...
>>> print(old_busted.__doc__)
.. deprecated:: 1.8
Using function/method old_busted is deprecated in version '1.8' and
will be removed in version '2.0': I am broken
>>> exit()
Do people think that is useful?
-Josh
Clint Byrum wrote:
Excerpts from Victor Stinner's message of 2015-07-07 08:22:26 -0700:
Hi,
Oslo libraries become more and more stable, cool :-) Sometimes, we have
to modify APIs, to fix bugs, to deprecate functions, to add new function
parameters, etc. It would be cool to _document_ these changes. Sphinx
provides nice markups to document API changes:
http://sphinx-doc.org/markup/para.html
We can try to ensure that API changes are documented in reviews, or
maybe also document old changes.
Examples:
.. versionadded:: 2.5
The *spam* parameter.
.. versionadded:: 2.6
The function now returns an integer.
.. deprecated:: 3.1
Use :func:`spam` instead.
I noticed that the deprecated markup is already used in oslo.utils doc:
http://docs.openstack.org/developer/oslo.utils/api/timeutils.html#oslo_utils.timeutils.isotime
This is great information, thank you.
Any time we have versions appearing in code or docs, I cringe, because
versions and releasing are separate from coding and documenting.
If I'm adding a parameter today in the latest commit after 1.0.0, I
really don't know if the next version released will be 1.1.0 or 2.0.0
(I do know it won't be 1.0.1 because I have changed the API!).
Or do we just make a rule that you _do_ get to choose the version bump
in the commit that changes the API, and if you say 1.1.0, and it becomes
2.0.0 before release, thats ok because the versionadded is still accurate
even if 1.1.0 didn't release?
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
