[issue31036] building the python docs requires the blurb module

[Larry Hastings]

Larry Hastings added the comment:

What you're missing is that Misc/NEWS.d is removed from tarballs.  We ship Misc/NEWS in tarballs but *not* Misc/NEWS.d.

If you start with a CPython tarball (e.g. 3.5.4rc1), and then apply vendor-specific patches on top of that, and those patches include news entries in Misc/NEWS.d, and you want to ship a unified Misc/NEWS file that contains those entries, then you'll have to use "blurb split" to repopulate Misc/NEWS.d from Misc/NEWS followed by "blurb merge" to reconstitute Misc/NEWS from Misc/NEWS.d.

FWIW, right now any entries under "Misc/NEWS.d/next" would appear in Misc/NEWS under the heading "What's new in Python next?", rather than e.g. "What's new in Python 3.5.4 release candidate 1?".  This would be a little curious.  blurb is only set up to understand "next" and CPython version numbers there; convincing it to put something else there would be a non-trivial amount of work.

On a related subject, I should mention something about blurb aggregated version files, e.g. "Misc/NEWS.d/3.5.4rc1.rst".  blurb doesn't know how to append / prepend to those, nor does it know how to combine two of them together.  It just isn't a feature I needed for CPython.  My guess is adding support for this wouldn't be too bad, and it may yet be helpful for doko's use case.  Something to keep in mind.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31036>
_______________________________________