Docs: Don't wrap the markdown for GitHub releases

[hugovk]

Thanks for submitting a PR, your contribution is really appreciated!

Here is a quick checklist that should be present in PRs.

• Target the master branch for bug fixes, documentation updates and trivial changes.
• Target the features branch for new features, improvements, and removals/deprecations.
• [n/a] Include documentation when adding new features.
• [n/a] Include new tests or update existing tests when applicable.

Unless your change is trivial or a small documentation fix (e.g., a typo or reword of a small section) please:

• [n/a?] Create a new changelog file in the changelog folder, with a name like <ISSUE NUMBER>.<TYPE>.rst. See changelog/README.rst for details.

  Write sentences in the past or present tense, examples:

  • Improved verbose diff output with sequences.
  • Terminal summary statistics now use multiple colors.

  Also make sure to end the sentence with a ..

• Add yourself to AUTHORS in alphabetical order.

---

What happens

Releases on GitHub look like this, with oddly-wrapped text (eg. https://github.com/pytest-dev/pytest/releases/tag/5.3.5):

In edit mode, it wraps like this, but of course a lot of that link markdown isn't visible to the end user, and GitHub is respecting the newlines here:

https://github.com/pytest-dev/pytest/releases/edit/5.3.5

---

Why

I understand scripts/publish-gh-release-notes.py is run to convert reStructuredText into Markdown, and post it in the GitHub release. It takes RST from the changelog:

pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

- `#6517 <https://github.com/pytest-dev/pytest/issues/6517>`_: Fix regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong assertion.

https://github.com/pytest-dev/pytest/blob/master/doc/en/changelog.rst#pytest-535-2020-01-29

Here there's no newlines, in the plain RST, nor the rendered output.

The conversion is made using pypandoc:

def convert_rst_to_md(text):
    return pypandoc.convert_text(text, "md", format="rst")

---

The fix

pypandoc.convert_text doesn't have any explicit line wrapping arguments, but you can use extra_args to pass to the underlying pandoc tool:

--wrap=auto|none|preserve

Determine how text is wrapped in the output (the source code, not the rendered version). With auto (the default), pandoc will attempt to wrap lines to the column width specified by --columns (default 72). With none, pandoc will not wrap lines at all. With preserve, pandoc will attempt to preserve the wrapping from the source document (that is, where there are nonsemantic newlines in the source, there will be nonsemantic newlines in the output as well).

https://pandoc.org/MANUAL.html

And so:

 def convert_rst_to_md(text):
-    return pypandoc.convert_text(text, "md", format="rst")
+    return pypandoc.convert_text(text, "md", format="rst", extra_args=["--wrap=none"])

---

Demo

I've not tested this using scripts/publish-gh-release-notes.py and I don't think there's tests for these helper scripts, so here's a short demo:

import pypandoc


def convert_rst_to_md_before(text):
    return pypandoc.convert_text(text, "md", format="rst")


def convert_rst_to_md_after(text):
    return pypandoc.convert_text(text, "md", format="rst", extra_args=["--wrap=none"])


text = """
pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

- `#6517 <https://github.com/pytest-dev/pytest/issues/6517>`_: Fix regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong assertion.

"""

print("BEFORE")
print(convert_rst_to_md_before(text))
print("AFTER")
print(convert_rst_to_md_after(text))

Output:

BEFORE
pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

-   [\#6517](https://github.com/pytest-dev/pytest/issues/6517): Fix
    regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong
    assertion.

AFTER
pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

-   [\#6517](https://github.com/pytest-dev/pytest/issues/6517): Fix regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong assertion.

A preview of this unwrapped text:

[blueyed]

Thanks!

[nicoddemus]

Hi @hugovk,

I've tried with a more complex example and it looks good:

import pypandoc


def convert_rst_to_md_before(text):
    return pypandoc.convert_text(text, "md", format="rst")


def convert_rst_to_md_after(text):
    return pypandoc.convert_text(text, "md", format="rst", extra_args=["--wrap=preserve"])


text = """
pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

- `#6517 <https://github.com/pytest-dev/pytest/issues/6517>`_: Fix regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong assertion.

- `#6517 <https://github.com/pytest-dev/pytest/issues/6517>`_: Fix regression in pytest 5.3.4
  causing an INTERNALERROR due to a wrong assertion.

  This also checks something else.

  Also see this:

  .. code-block:: python

      def test():
          pass

  Another example.
"""

print("AFTER")
print(convert_rst_to_md_after(text))

"""

print("AFTER")
print(convert_rst_to_md_after(text))

AFTER
pytest 5.3.5 (2020-01-29)
=========================

Bug Fixes
---------

-   [\#6517](https://github.com/pytest-dev/pytest/issues/6517): Fix regression in pytest 5.3.4 causing an INTERNALERROR due to a wrong assertion.

-   [\#6517](https://github.com/pytest-dev/pytest/issues/6517): Fix regression in pytest 5.3.4
    causing an INTERNALERROR due to a wrong assertion.

    This also checks something else.

    Also see this:

    ``` {.python}
    def test():
        pass
    ```

    Another example.

Render: https://gist.github.com/nicoddemus/83a3ef2c6548f481a1d9fe7787be396c

So thanks a lot for looking into this. 👍

[blueyed]

@nicoddemus this was waiting for an update AFAICT.

[hugovk]

Sorry, I forgot to push that last change. I can do it tomorrow or it's a simple thing if you'd like to do it. Thanks!

[blueyed]

@hugovk doesn't matter that much/enough I guess.
Thanks again though.. :)

[nicoddemus]

@nicoddemus this was waiting for an update AFAICT.

Ouch my bad! 🤦‍♂

Will open a new PR.

[nicoddemus]

Done in #6624.