[all-commits] [llvm/llvm-project] b9f09a: [llvm][docs] Convert LLVM release notes to Markdow...

[David Spickett via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: b9f09a43b4437b9a1773d45d9fb5a699886a3e12
      https://github.com/llvm/llvm-project/commit/b9f09a43b4437b9a1773d45d9fb5a699886a3e12
  Author: David Spickett <david.spickett at linaro.org>
  Date:   2024-09-26 (Thu, 26 Sep 2024)

  Changed paths:
    A llvm/docs/ReleaseNotes.md
    R llvm/docs/ReleaseNotes.rst
    M llvm/docs/conf.py

  Log Message:
  -----------
  [llvm][docs] Convert LLVM release notes to Markdown (#109107)

* Markdown is the most common format on GitHub and most contributors are
more familiar with it than RST.
* This leads to mistakes in the RST syntax and/or folks just using
Markdown syntax and assuming it works.
* The release notes have a high number of edits and a high number of
views, we should optimise for making the common path easy. That is,
adding a bullet point and a link.
* Though GitHub can render RST and Markdown, its support for Markdown is
more complete (and neither handle the Sphinx directives well).
* We already have some Markdown docs in the llvm docs.

To keep the original formatting we do need some Sphinx directives still,
and those are provided by MyST which is already enabled.

https://myst-parser.readthedocs.io/en/latest/

I did have to enable an extension so we can substitute in the release
version.


https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2

Needing to use MyST means there is some special knowledge needed if you
want to do advanced things, but at least the basics remain Markdown.
Even in RST form, you still had to look up Sphinx syntax.

I also make use of a nested directive

https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#nesting-directives
to implement the prerelease warning.

The note about sections referred to another note that got removed in
4c72deb613d9d8838785b431facb3eb480fb2f51. I presume accidentally, so I
have restored that.

I also removed the "Update on required toolchains to build LLVM" header
because the section is now empty.

The other difference is that the table of contents now has a heading
"Contents". This is the default and I could not find a way to remove
that name. Otherwise it's the same table as you'd get from the RST
document.



To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications