Add class cmRST to do basic reStructuredText processing

Create a cmRST class to perform just enough reStructuredText processing
to support display of Help documents in human-readable text format.
This will be used to implement --help-* command-line options.

Support directives "include", "replace", "parsed-literal", "toctree"
(Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
modules).  Support inline CMake Sphinx Domain roles to convert
cross-references to corresponding title text.  Support inline
substitutions defined by the "replace" directive, but keep it simple by
requiring replacements to be defined before use.

Add a CMakeLib "testRST" case to cover processing of supported
constructs and compare results against expected output.

1 files changed, 72 insertions, 0 deletions

diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst
new file mode 100644
index 0000000..f7059cf
--- /dev/null
+++ b/Tests/CMakeLib/testRST.rst
@@ -0,0 +1,72 @@
+.. index::
+   single: directive ignored
+
+title_text
+----------
+
+.. comment ignored
+..
+   comment ignored
+
+Command :cmake:command:`some_cmd` explicit cmake domain.
+Command :command:`some_cmd` without target.
+Command :command:`some_cmd <some_cmd>` with target.
+Command :command:`some_cmd_<cmd>` placeholder without target.
+Command :command:`some_cmd_<cmd> <some_cmd>` placholder with target.
+Command :command:`some_cmd()` with parens.
+Command :command:`some_cmd(SUB)` with subcommand.
+Command :command:`some_cmd(SUB) <some_cmd>` with subcommand and target.
+Command :command:`some_cmd (SUB) <some_cmd>` with space and subcommand and target.
+Command :command:`some command <some_cmd>` with space and target.
+Variable :variable:`some variable <some_var>` space and target.
+Variable :variable:`<PLACEHOLDER>_VARIABLE` with leading placeholder.
+Variable :variable:`VARIABLE_<PLACEHOLDER>` with trailing placeholder.
+Variable :variable:`<PLACEHOLDER>_VARIABLE <target>` with leading placeholder and target.
+Variable :variable:`VARIABLE_<PLACEHOLDER> <target>` with trailing placeholder and target.
+Generator :generator:`Some Generator` with space.
+
+.. |not replaced| replace:: not replaced through toctree
+
+.. toctree::
+   :maxdepth: 2
+
+   testRSTtoc1
+   /testRSTtoc2
+
+.. cmake-module:: testRSTmod.cmake
+
+.. cmake:command:: some_cmd
+
+   Command some_cmd description.
+
+.. command:: other_cmd
+
+   Command other_cmd description.
+
+.. cmake:variable:: some_var
+
+   Variable some_var description.
+
+.. variable:: other_var
+
+   Variable other_var description.
+
+.. parsed-literal::
+
+    Parsed-literal included without directive.
+   Common Indentation Removed
+
+.. code-block:: cmake
+
+   # Sample CMake code block
+   if(condition)
+     message(indented)
+   endif()
+
+.. |substitution| replace::
+   |nested substitution|
+   with multiple lines becomes one line
+.. |nested substitution| replace:: substituted text
+
+.. include:: testRSTinclude1.rst
+.. include:: /testRSTinclude2.rst