fwiw - openstackclient has been using .. versionadded:: in it's docs for a while: http://docs.openstack.org/developer/python-openstackclient/_sources/command-objects/user.txt Thanks, Steve Martinelli OpenStack Keystone Core From: Victor Stinner <vstinner at redhat.com> To: OpenStack List <openstack-dev at lists.openstack.org> Date: 2015/07/07 11:23 AM Subject: [openstack-dev] [oslo] Document API changes using Sphinx markups 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 Victor __________________________________________________________________________ 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 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150707/a78f61d6/attachment.html> -------------- next part -------------- A non-text attachment was scrubbed... Name: graycol.gif Type: image/gif Size: 105 bytes Desc: not available URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150707/a78f61d6/attachment.gif>
