[llvm][docs] Convert LLVM release notes to Markdown #109107
Merged
+283
−257
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
✅ With the latest revision this PR passed the Python code formatter. |
DavidSpickett
force-pushed
the
md-docs
branch
from
ca76f00 to
fdfb179
Compare
DavidSpickett
force-pushed
the
md-docs
branch
3 times, most recently
from
0dcf6e6 to
91ec8b4
Compare
* 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 4c72deb. 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.
DavidSpickett
force-pushed
the
md-docs
branch
from
91ec8b4 to
e164fda
Compare
|
If you are here wondering why you now have a merge conflict, to convert your release note to Markdown you probably just need to replace the link and plain text syntax: This can be previewed on GitHub to check you have done this correctly ("Display Rich Diff" in the code review section). |
Sterling-Augustine
pushed a commit
to Sterling-Augustine/llvm-project
that referenced
this pull request
Sep 27, 2024
* 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 4c72deb. 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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 4c72deb. 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.