[Openmp-commits] [llvm] [openmp] [docs] Rewrite SphinxQuickstartTemplate.md in MyST Markdown (PR #198896)
Reid Kleckner via Openmp-commits
openmp-commits at lists.llvm.org
Wed May 20 13:46:14 PDT 2026
https://github.com/rnk created https://github.com/llvm/llvm-project/pull/198896
Converts SphinxQuickstartTemplate.md from reStructuredText syntax to MyST Markdown. Updates the overview to mention that MyST is now preferred for new LLVM documentation, modernizes the authoring guidelines, and replaces all RST markup constructs with their Markdown equivalents.
Stacked on top of #198895 (the rename). After that lands, this PR's diff will show only the content rewrite.
>From 0ef7c796f0057e5920a46839b690c11b2e1b7d02 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <reid.kleckner at gmail.com>
Date: Tue, 19 May 2026 16:44:26 -0700
Subject: [PATCH 1/2] [docs] Rename SphinxQuickstartTemplate.{rst|md} for blame
While the new file will not be valid markdown, this is done as an
isolated commit so that the rewrite is easier to review and blame is
more accurate.
I updated the references to the rst file in this change so that the docs
target should build with warnings.
---
llvm/docs/MarkdownQuickstartTemplate.md | 2 +-
llvm/docs/README.txt | 2 +-
...SphinxQuickstartTemplate.rst => SphinxQuickstartTemplate.md} | 2 +-
openmp/docs/README.txt | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
rename llvm/docs/{SphinxQuickstartTemplate.rst => SphinxQuickstartTemplate.md} (96%)
diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md
index 8b03b4e26d419..7513ed7cc215d 100644
--- a/llvm/docs/MarkdownQuickstartTemplate.md
+++ b/llvm/docs/MarkdownQuickstartTemplate.md
@@ -158,4 +158,4 @@ integration documentation can be found in the [myst-parser docs].
## Generating the documentation
-see [Sphinx Quickstart Template](project:SphinxQuickstartTemplate.rst#Generating the documentation)
+see [Sphinx Quickstart Template](project:SphinxQuickstartTemplate.md#Generating the documentation)
diff --git a/llvm/docs/README.txt b/llvm/docs/README.txt
index 074606c7bd36e..53bd064bc2aaa 100644
--- a/llvm/docs/README.txt
+++ b/llvm/docs/README.txt
@@ -20,7 +20,7 @@ The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.
If you are interested in writing new documentation, you will want to read
-`SphinxQuickstartTemplate.rst` which will get you writing documentation
+`SphinxQuickstartTemplate.md` which will get you writing documentation
very fast and includes examples of the most important reStructuredText
markup syntax.
diff --git a/llvm/docs/SphinxQuickstartTemplate.rst b/llvm/docs/SphinxQuickstartTemplate.md
similarity index 96%
rename from llvm/docs/SphinxQuickstartTemplate.rst
rename to llvm/docs/SphinxQuickstartTemplate.md
index 8d21b43c050d7..61fbfdd64fe6f 100644
--- a/llvm/docs/SphinxQuickstartTemplate.rst
+++ b/llvm/docs/SphinxQuickstartTemplate.md
@@ -18,7 +18,7 @@ LLVM documentation is written in `reStructuredText`_, a markup syntax similar to
How to use this template
========================
-This article is located in ``docs/SphinxQuickstartTemplate.rst``. To use it as a template, make a copy and open it in a text editor. You can then write your docs, and then send the new article to llvm-commits for review.
+This article is located in ``docs/SphinxQuickstartTemplate.md``. To use it as a template, make a copy and open it in a text editor. You can then write your docs, and then send the new article to llvm-commits for review.
To view the restructuredText source file for this article, click **Show Source** on the right sidebar.
diff --git a/openmp/docs/README.txt b/openmp/docs/README.txt
index 4ec2f429174dd..fe53bcec03ba4 100644
--- a/openmp/docs/README.txt
+++ b/openmp/docs/README.txt
@@ -21,7 +21,7 @@ The mapping between reStructuredText files and generated documentation is
`https://openmp.llvm.org/docs/Foo.html`.
If you are interested in writing new documentation, you will want to read
-`llvm/docs/SphinxQuickstartTemplate.rst` which will get you writing
+`llvm/docs/SphinxQuickstartTemplate.md` which will get you writing
documentation very fast and includes examples of the most important
reStructuredText markup syntax.
>From c6fb627be3142812b046d98ecc2b5be7c0dd7e83 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <reid.kleckner at gmail.com>
Date: Wed, 20 May 2026 12:51:57 -0700
Subject: [PATCH 2/2] [docs] Rewrite SphinxQuickstartTemplate.md in MyST
Markdown
Convert from reStructuredText syntax to MyST Markdown, update references
to reflect that MyST is now preferred for new LLVM documentation, and
modernize the authoring guidelines accordingly.
---
llvm/docs/SphinxQuickstartTemplate.md | 191 +++++++++++++-------------
1 file changed, 93 insertions(+), 98 deletions(-)
diff --git a/llvm/docs/SphinxQuickstartTemplate.md b/llvm/docs/SphinxQuickstartTemplate.md
index 61fbfdd64fe6f..7a1cc33d8a823 100644
--- a/llvm/docs/SphinxQuickstartTemplate.md
+++ b/llvm/docs/SphinxQuickstartTemplate.md
@@ -1,104 +1,101 @@
-==========================
-Sphinx Quickstart Template
-==========================
+# Sphinx Quickstart Template
This article is intended to take someone in the state of “I want to write documentation and get it added to LLVM’s docs” and help them start writing documentation as fast as possible and with as little nonsense as possible.
-.. contents::
- :local:
+```{contents}
+:local:
+```
-Overview
-========
+## Overview
-LLVM documentation is written in `reStructuredText`_, a markup syntax similar to markdown (but much more powerful). The LLVM documentation site itself uses `Sphinx`_, a documentation generator originally written for Python documentation.
+LLVM documentation is written in [Markedly Structured Text (MyST)][myst] and [reStructuredText (reST)][reStructuredText].
+MyST is a Markdown flavor that adds Sphinx documentation extensions.
+MyST is preferred for new docs, and migrating old docs from reST to MyST is an open, ongoing project.
+[Sphinx], a documentation generator originally written for Python documentation, generates the LLVM HTML documentation from MyST and reST.
-.. _`reStructuredText`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _`Sphinx`: http://www.sphinx-doc.org
+[myst]: https://myst-parser.readthedocs.io/en/latest/
+[reStructuredText]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+[Sphinx]: http://www.sphinx-doc.org
-How to use this template
-========================
+## How to use this template
-This article is located in ``docs/SphinxQuickstartTemplate.md``. To use it as a template, make a copy and open it in a text editor. You can then write your docs, and then send the new article to llvm-commits for review.
+This article is located in `docs/SphinxQuickstartTemplate.md`.
+To use it as a template, make a copy and open it in a text editor.
+You can then write your docs, and open a [GitHub PR](project:GitHub.rst) to request a review.
-To view the restructuredText source file for this article, click **Show Source** on the right sidebar.
+To view the Markdown source file for this article, click **Show Source** on the right sidebar.
-Authoring Guidelines
-====================
+## Authoring Guidelines
-Focus on *content*. It is easy to fix the Sphinx (reStructuredText) syntax
-later if necessary, although reStructuredText tries to imitate common
-plain-text conventions so it should be quite natural. A basic knowledge of
-reStructuredText syntax is useful when writing the document, so the last
-~half of this document (starting with `Example Section`_) gives examples
-which should cover 99% of use cases.
+Focus on *content*. It is easy to fix the Markdown syntax later if necessary,
+and Markdown intentionally imitates common plain-text conventions so it should
+be quite natural. A basic knowledge of Markdown syntax is useful when writing
+the document, so the last ~half of this document (starting with
+[Example Section](#example-section)) gives examples which should cover 99% of
+use cases.
-Let me say that again: focus on *content*. But if you really need to verify
-Sphinx's output, see ``docs/README.txt`` for information. Once you have finished with the content, please send the ``.rst`` file to
-llvm-commits for review.
+Let me say that again: focus on *content*.
+But if you really need to verify Sphinx's output, see `docs/README.txt` for information on how to build it.
-Creating New Articles
----------------------
+### Creating New Articles
Before creating a new article, consider the following questions:
-#. Why would I want to read this document?
+1. Why would I want to read this document?
-#. What should I know to be able to follow along with this document?
+1. What should I know to be able to follow along with this document?
-#. What will I have learned by the end of this document?
+1. What will I have learned by the end of this document?
A standard best practice is to make your articles task-oriented. You generally should not be writing documentation that isn't based around "how to" do something
unless there's already an existing "how to" article for the topic you're documenting. The reason for this is that without a "how to" article to read first, it might be difficult for
someone unfamiliar with the topic to understand a more advanced, conceptual article.
-When creating a task-oriented article, follow existing LLVM articles by giving it a filename that starts with ``HowTo*.rst``. This format is usually the easiest for another person to understand and also the most useful.
+When creating a task-oriented article, follow existing LLVM articles by giving it a filename that starts with `HowTo*.md`. This format is usually the easiest for another person to understand and also the most useful.
Focus on content (yes, I had to say it again).
-The rest of this document shows example reStructuredText markup constructs
+The rest of this document shows example Markdown and MyST markup constructs
that are meant to be read by you in your text editor after you have copied
this file into a new file for the documentation you are about to write.
-Example Section
-===============
+## Example Section
-An article can contain one or more sections (i.e., headings). Sections (like ``Example Section`` above) help give your document its
-structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``)
-as are used in this document. The adornment must be the same length as the
-text above it. For Vim users, variations of ``yypVr=`` might be handy.
+An article can contain one or more sections (i.e., headings). Sections (like
+`Example Section` above) help give your document its structure. Use `#` for the
+document title, `##` for top-level sections, `###` for subsections, and so on.
+Leave a blank line before and after each heading.
-Example Nested Subsection
--------------------------
+### Example Nested Subsection
-Subsections can also be nested beneath other subsections. For more information on sections, see Sphinx's `reStructuredText Primer`_.
+Subsections can also be nested beneath other subsections. For more information
+on Markdown syntax, see the [CommonMark spec] and the [MyST syntax guide].
-.. _`reStructuredText Primer`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+[CommonMark spec]: https://spec.commonmark.org/
+[MyST syntax guide]: https://myst-parser.readthedocs.io/en/latest/syntax/typography.html
-Text Formatting
-===============
+## Text Formatting
-Text can be *emphasized*, **bold**, or ``monospace``.
+Text can be *emphasized*, **bold**, or `monospace`.
To create a new paragraph, simply insert a blank line.
-Links
-=====
+## Links
-You can format a link `like this <https://llvm.org/>`_. A more `sophisticated syntax`_ allows you to place the ``.. _`link text`: <URL>`` block
+You can format a link [like this](https://llvm.org/). A more [sophisticated syntax] allows you to place the `[link text]: <URL>` block
pretty much anywhere else in the document. This is useful when linking to especially long URLs.
-.. _`sophisticated syntax`: http://en.wikipedia.org/wiki/LLVM
+[sophisticated syntax]: http://en.wikipedia.org/wiki/LLVM
-Lists
-=====
+## Lists
-restructuredText allows you to create ordered lists...
+Markdown allows you to create ordered lists...
-#. A list starting with ``#.`` will be automatically numbered.
+1. A list starting with `1.` will be automatically numbered.
-#. This is a second list element.
+1. This is a second list element.
- #. Use indentation to create nested lists.
+ 1. Use indentation to create nested lists.
...as well as unordered lists:
@@ -108,46 +105,44 @@ restructuredText allows you to create ordered lists...
* More stuff.
-Code Blocks
-===========
+## Code Blocks
You can make blocks of code like this:
-.. code-block:: c++
+```cpp
+int main() {
+ return 0;
+}
+```
- int main() {
- return 0;
- }
+For a shell session, use a `console` code block (some existing docs use
+`bash`):
-For a shell session, use a ``console`` code block (some existing docs use
-``bash``):
+```console
+$ echo "Goodbye cruel world!"
+$ rm -rf /
+```
-.. code-block:: console
+If you need to show LLVM IR, use the `llvm` code block.
- $ echo "Goodbye cruel world!"
- $ rm -rf /
+```llvm
+define i32 @test1() {
+entry:
+ ret i32 0
+}
+```
-If you need to show LLVM IR use the ``llvm`` code block.
+Some other common code blocks you might need are `c`, `objc`, `make`,
+and `cmake`. If you need something beyond that, you can look at the [full
+list] of supported code blocks.
-.. code-block:: llvm
-
- define i32 @test1() {
- entry:
- ret i32 0
- }
-
-Some other common code blocks you might need are ``c``, ``objc``, ``make``,
-and ``cmake``. If you need something beyond that, you can look at the `full
-list`_ of supported code blocks.
-
-.. _`full list`: http://pygments.org/docs/lexers/
+[full list]: http://pygments.org/docs/lexers/
However, don't waste time fiddling with syntax highlighting when you could
be adding meaningful content. When in doubt, show preformatted text
without any syntax highlighting like this:
-::
-
+```
.
+:.
..:: ::
@@ -163,32 +158,32 @@ without any syntax highlighting like this:
...+. .: .
.++:..
...
+```
-Generating the documentation
-============================
+## Generating the documentation
You can generate the HTML documentation from the sources locally if you want to
see what they would look like. In addition to the normal
-`build tools <GettingStarted.html>`_
-you need to install `Sphinx`_ and the necessary extensions
-using the following command inside the ``llvm-project`` checkout:
-
-.. code-block:: console
-
- pip install --user -r ./llvm/docs/requirements.txt
+[build tools](project:GettingStarted.rst)
+you need to install [Sphinx] and the necessary extensions
+using the following command inside the `llvm-project` checkout:
-Then run cmake to build the documentation inside the ``llvm-project`` checkout:
+```console
+pip install --user -r ./llvm/docs/requirements.txt
+```
-.. code-block:: console
+Then run cmake to build the documentation inside the `llvm-project` checkout:
- mkdir build
- cd build
- cmake -DLLVM_ENABLE_SPHINX=On ../llvm
- cmake --build . --target docs-llvm-html
+```console
+mkdir build
+cd build
+cmake -DLLVM_ENABLE_SPHINX=On ../llvm
+cmake --build . --target docs-llvm-html
+```
In case you already have the Cmake build set up and want to reuse that,
-just set the CMake variable ``LLVM_ENABLE_SPHINX=On``.
+just set the CMake variable `LLVM_ENABLE_SPHINX=On`.
-After that you find the generated documentation in ``build/docs/html``
+After that you find the generated documentation in `build/docs/html`
folder.
More information about the Openmp-commits
mailing list