Issues numbers added after rst preformatted blocks breaks rendering

[SmileyChris]

From #608:

An interesting aside: without some text after the pre-formatted block, it breaks the rendering of the issue number towncrier adds when building because it's considered part of the block.

For example, a file newsfragments/608.feature.rst:

Something was fixed. Now this is a thing::

    def code_block():
        ...

will produce:

- Something was fixed. Now this is a thing::

      def code_block():
          ... (`#608 <https://github.com/twisted/towncrier/issues/608>`_)

Which renders as:

The solution is probably to Prepend \n\n to the issue number in this case (a single newline will result in (WARNING/2) Literal block ends without a blank line; unexpected unindent.)

Maybe it's easier always putting the issue number in a separate paragraph if any new lines exist in the fragment content?

[adiroiban]

Are the release notes supposed to contain multi-line / block markup ?

The list item is automatically prefixed to the content and the content of the next fragment is processed by towncrier.

---

Would it work if the extra newlines are added to the issue_format configuration ?

[jakkdl]

I just hit this as well in https://github.com/python-trio/trio/pull/3010 One minimal solution would be to add newlines before appending the issue number if the last line in the newsfragment is indented.

[adiroiban]

I think that content of the news fragment from this PR https://github.com/python-trio/trio/pull/3010 is abusing the release notes format.

The release notes should not be used as documentation and should not include examples.

They can contain links to API documentation or the a separate documentation page that contain example.

The newsfragment are not news articles. They are release notes items.

They are just some notes / mentions about the high-level changes.

---

I am not saying that this should not be fixed. It's just that I feel that this is an missuse / abuse of the purpose of a release notes.

I can understand that someone might want to have "rich-format" release notes.

But I think that in that use case we should add something like verbatim = True configuration option.

With that option, towncrier only passes the newsfragment content to Jinja2

[adiroiban]

As long as it doesn't break backward compatibility and it continues to make simple things, simple, any fix for this issue should be ok.

[jakkdl]

Yeah I'm not gonna defend that changelog entry as being a pinnacle of greatness, and is not unlikely I'll change it before it gets merged. But unless towncrier wants to explicitly be opinionated about multi-line entries I agree that we can introduce a small & simple fix that quietly gets out of the way of breaking rendering.

[adiroiban]

But unless towncrier wants to explicitly be opinionated about multi-line entries I agree that we can introduce a small & simple fix that quietly gets out of the way of breaking rendering.

I don't want towncrier to be opinionated. It's a tool designed to help developers manage the release notes regardless of the content of the release notes.

Happy to review and merge a fix for this.

Thanks