[WIP] Warn in case news items contains multiple paragraphs.

[JulienPalard]

See https://bugs.python.org/issue32523, having multiple paragraphs in
a few news entry lead to inconsistent spacing while rendered in HTML.

Also NEWS entries should stay short, having multiple paragraphs is an
indicator the news entry is too long.

Currently, on cpython master, it yields around 60 warnings.

I'm also trying to fix them in python/cpython#8154

[terryjreedy]

While reviewing #8154, I noticed one case where I left a trailing blank line. This is a simple editing error. If blurb can fix this, it should do so. Otherwise, it should warn 'Trailing blank line(s)' rather than 'Multiple paragraphs'.

[JulienPalard]

Make sense I'll try to make the warning appropriate in this case.

[larryhastings]

I'm pretty sure blurb's aggressive paragraph reflowing will strip all trailing whitespace. See the last few lines of textwrap_body().

[larryhastings]

I think if blurb is going to have a non-fatal error, it should work like this: you edit your blurb, you save and exit. Blurb prints a warning, in this case saying "You have multiple paragraphs! News blurbs should only be a single paragraph. Are you sure? Type 'yes' to use this file, anything else to re-edit." And then it should raw_input() prompt the user. If they type "yes" we continue, otherwise we loop.

How does that sound?

[larryhastings]

Sorry, I should have put my comments here. Please see comment on the main PR. (Creating this just for scoring purposes for the CPython core dev PRs-reviewed leaderboard.)

[ericvsmith]

raw_input()? What year is this? :)

[JulienPalard]

I'm currently trying to enhance my PR to have the nice behavior with the

You have multiple paragraphs! News blurbs should only be a single paragraph. Are you sure? Type 'yes' to use this file, anything else to re-edit.

message. But I'm realizing that forbidding paragraphs probably leads to forbidding any formatted kind of things like bullet lists, which anyway cannot be "correctly" represented in the HTML documentation, it goes as a single line like:

bpo-27706: Restore deterministic behavior of random.Random().seed() for string seeds using seeding version 1. Allows sequences of calls to random() to exactly match those obtained in Python 2. Patch by Nofar Schnider.

So I'll probably remove all handling of multi-paragraph things (initially, it was what's causing rendering bugs in the lists), is that OK?

[JulienPalard]

Oh, a forgotten old PR, hello.

This is more subtle than that, in https://docs.python.org/3.10/whatsnew/changelog.html we have a blurb message like this:

Fix bugs in cleaning up classes and modules in :mod:`unittest`:

* Functions registered with :func:`~unittest.addModuleCleanup` were not called unless the user defines ``tearDownModule()`` in their test module.
* Functions registered with :meth:`~unittest.TestCase.addClassCleanup` were not called if ``tearDownClass`` is set to ``None``.
* Buffering in :class:`~unittest.TestResult` did not work with functions registered with ``addClassCleanup()`` and ``addModuleCleanup()``.
* Errors in functions registered with ``addClassCleanup()`` and ``addModuleCleanup()`` were not handled correctly in buffered and debug modes.
* Errors in ``setUpModule()`` and functions registered with ``addModuleCleanup()`` were reported in wrong order.
* And several lesser bugs.

and yet the sphinx rendering does not use a sparse list because it's a single line and a sub list, so it should be considered valid.

[JulienPalard]

I'm not convinced we should continue this way, some news should probably be shorter but some really need some multi-paragraph formatting, like:

bpo-43244: Remove the compiler and parser functions using struct _mod type, because the public AST C API was removed:

    PyAST_Compile()
    PyAST_CompileEx()
    PyAST_CompileObject()
    PyFuture_FromAST()
    PyFuture_FromASTObject()
    PyParser_ASTFromFile()
    PyParser_ASTFromFileObject()
    PyParser_ASTFromFilename()
    PyParser_ASTFromString()
    PyParser_ASTFromStringObject()

These functions were undocumented and excluded from the limited C API. Patch by Victor Stinner.

or

bpo-43244: Remove the symtable.h header file and the undocumented functions:

    PyST_GetScope()
    PySymtable_Build()
    PySymtable_BuildObject()
    PySymtable_Free()
    Py_SymtableString()
    Py_SymtableStringObject()

The Py_SymtableString() function was part the stable ABI by mistake but it could not be used, because the symtable.h header file was excluded from the limited C API.

The Python symtable module remains available and is unchanged.

Patch by Victor Stinner.

I'm closing this and add a comment on b.p.o.