Open Stack

Excerpts from Akihiro Motoki's message of 2015-12-04 01:03:40 +0900:
> Hi,
> 
> python-neutronclient recently added reno support and
> I added the reno directive " . release-notes::" to the neutronclient
> documentation.
> As a result, this prevents users from building the documentation from
> released tarballs
> using 'python setup.py build_sphinx' because the reno module expects a
> git tree [1].
> 
> What is the recommended way now?
> 
> The easiest way we can do now seems not to include our release notes
> (release-notes directive) in our documentation and instead point the
> url http://docs.openstack.org/releasenotes/<project> instead.

We've gone back and forth a few times about the approach for release
notes in clients and other libraries. My earlier email [1] describes
our most current proposed approach, which is to use reno separately
from the regular documentation build for notes targeted at deployers,
and manual or pbr-based ChangeLog notes in the developer documentation
for a developer audience.

Doug

[1] http://lists.openstack.org/pipermail/openstack-dev/2015-November/080694.html

> Of course, reno (or other tool chains) can be improved to generate release notes
> during "python setup.py sdist" or similar process so that the
> documentation which
> contains 'releasenotes' sphinx directive can be generated even out of git tree.
> 
> [1] https://bugs.launchpad.net/python-neutronclient/+bug/1520096
> 
> Akihiro