[openstack-dev] [oslo] Document API changes using Sphinx markups

Joshua Harlow harlowja at outlook.com
Tue Jul 7 18:39:04 UTC 2015

Another idea that I was going to do, but backed down from it,

Was the following:


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?


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: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list