[doc][cmake] Convert read-me for the common CMake utils to reST

@phosek mentioned others might want it reST for consistency. As I
personally do not like Markdown at all and just did the "usual GitHub
read-me thing" out of habit, I am more than happy to oblige.

Also fix the typos found in the original.

Reviewed By: phosek, lebedev.ri

Differential Revision: https://reviews.llvm.org/D116524

diff --git a/cmake/README.md b/cmake/README.md
deleted file mode 100644 (file)
index e7bd143..0000000
--- a/cmake/README.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# LLVM Common CMake Utils
-
-## What goes here
-
-These are CMake modules to be shared between LLVM projects strictly at build
-time. In other words, they must not be included from an installed CMake module,
-such as the `Add*.cmake` ones. Modules that are reachable from installed
-modules should instead go in `${project}/cmake/modules` of the most upstream
-project that use them.
-
-The advantage of not putting these modules in an existing location like
-`llvm/cmake/modules` is two-fold:
-
-- Since they are not installed, we don't have to worry about any out-of-tree
-  downstream usage, and thus there is no need for stability.
-
-- Since they are available as part of the source at build-time, we don't have
-  to do the usual stand-alone vs combined-build dances, avoiding much
-  complexity.
-
-## How to use
-
-For tools, please do:
-
-```cmake
-if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
-  set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
-endif()
-
-# Add path for custom modules.
-list(INSERT CMAKE_MODULE_PATH 0
-  # project-specific module dirs first
-  "${LLVM_COMMON_CMAKE_UTILS}/Modules"
-  )
-```
-
-- The `if(NOT DEFINED ...)` guard is there because in combined builds, LLVM
-  will set this variable.  This is useful for legacy builds where projects are
-  found in `llvm/tools` instead.
-
-- `INSERT ... 0` ensures these new entries are prepended to the front of the
-  module path, so nothing might shadow them by mistake.
-
-If runtime libs, we skip the `if(NOT DEFINED` part:
-
-```cmake
-set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
-
-... # same as before
-```
-
-If `llvm/tools` legacy-style combined builds are deprecated, we should then
-skip it everywhere, bringing the tools and runtimes boilerplate back in line.

diff --git a/cmake/README.rst b/cmake/README.rst
new file mode 100644 (file)
index 0000000..e28409a
--- /dev/null
+++ b/cmake/README.rst
@@ -0,0 +1,59 @@
+=======================
+LLVM Common CMake Utils
+=======================
+
+What goes here
+--------------
+
+These are CMake modules to be shared between LLVM projects strictly at build
+time. In other words, they must not be included from an installed CMake module,
+such as the ``Add*.cmake`` ones. Modules that are reachable from installed
+modules should instead go in ``${project}/cmake/modules`` of the most upstream
+project that uses them.
+
+The advantage of not putting these modules in an existing location like
+``llvm/cmake/modules`` is two-fold:
+
+- Since they are not installed, we don't have to worry about any out-of-tree
+  downstream usage, and thus there is no need for stability.
+
+- Since they are available as part of the source at build-time, we don't have
+  to do the usual stand-alone vs combined-build dances, avoiding much
+  complexity.
+
+How to use
+----------
+
+For tools, please do:
+
+.. code-block:: cmake
+
+  if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
+    set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
+  endif()
+
+  # Add path for custom modules.
+  list(INSERT CMAKE_MODULE_PATH 0
+    # project-specific module dirs first
+    "${LLVM_COMMON_CMAKE_UTILS}/Modules"
+    )
+
+Notes:
+
+- The ``if(NOT DEFINED ...)`` guard is there because in combined builds, LLVM
+  will set this variable.  This is useful for legacy builds where projects are
+  found in ``llvm/tools`` instead.
+
+- ``INSERT ... 0`` ensures these new entries are prepended to the front of the
+  module path, so nothing might shadow them by mistake.
+
+For runtime libs, we skip the ``if(NOT DEFINED`` part:
+
+.. code-block:: cmake
+
+  set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake)
+
+  ... # same as before
+
+If ``llvm/tools`` legacy-style combined builds are deprecated, we should then
+skip it everywhere, bringing the tools and runtimes boilerplate back in line.