cmRST: support `versionadded` and `versionchanged` directives

This makes `versionadded` and `versionchanged` directives show up in
`cmake --help-*` output instead of disappearing (and potentially making
empty sections).

Fixes: #22808

5 files changed, 23 insertions, 0 deletions

diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index 29fc880..4a2a5d9 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -92,6 +92,11 @@ literal block after ``::``
  the referenced documents inline as part of the referencing
  document.
 
+``versionadded``, ``versionchanged`` directives
+ Specify that something was added or changed by a named CMake version.
+ The command-line help processor prints the block content as if the lines
+ were normal paragraph text with interpretation.
+
 Inline markup constructs not listed above are printed literally in the
 command-line help output.  We prefer to use inline markup constructs that
 look correct in source form, so avoid use of \\-escapes in favor of inline
diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx
index fce6e80..1e4dedd 100644
--- a/Source/cmRST.cxx
+++ b/Source/cmRST.cxx
@@ -35,6 +35,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot)
   , TocTreeDirective("^.. toctree::[ \t]*(.*)$")
   , ProductionListDirective("^.. productionlist::[ \t]*(.*)$")
   , NoteDirective("^.. note::[ \t]*(.*)$")
+  , VersionDirective("^.. version(added|changed)::[ \t]*(.*)$")
   , ModuleRST(R"(^#\[(=*)\[\.rst:$)")
   , CMakeRole("(:cmake)?:("
               "command|cpack_gen|generator|genex|"
@@ -209,6 +210,10 @@ void cmRST::ProcessLine(std::string const& line)
     } else if (this->NoteDirective.find(line)) {
       // Output note directives and their content normally.
       this->NormalLine(line);
+    } else if (this->VersionDirective.find(line)) {
+      // Output versionadded and versionchanged directives and their content
+      // normally.
+      this->NormalLine(line);
     }
   }
   // An explicit markup start followed nothing but whitespace and a
diff --git a/Source/cmRST.h b/Source/cmRST.h
index 17cdfe8..156b20a 100644
--- a/Source/cmRST.h
+++ b/Source/cmRST.h
@@ -83,6 +83,7 @@ private:
   cmsys::RegularExpression TocTreeDirective;
   cmsys::RegularExpression ProductionListDirective;
   cmsys::RegularExpression NoteDirective;
+  cmsys::RegularExpression VersionDirective;
   cmsys::RegularExpression ModuleRST;
   cmsys::RegularExpression CMakeRole;
   cmsys::RegularExpression InlineLink;
diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect
index 4870f65..5e3cdb1 100644
--- a/Tests/CMakeLib/testRST.expect
+++ b/Tests/CMakeLib/testRST.expect
@@ -116,6 +116,12 @@ A literal block can be empty::
 .. note::
  Notes are called out.
 
+.. versionadded:: 1.2
+ Version blocks are preserved.
+
+.. versionchanged:: 2.3
+ Version blocks are preserved.
+
 substituted text with multiple lines becomes one line
 
 End of first include.
diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst
index 44931a7..4139801 100644
--- a/Tests/CMakeLib/testRST.rst
+++ b/Tests/CMakeLib/testRST.rst
@@ -123,6 +123,12 @@ A literal block can be empty::
 .. note::
  Notes are called out.
 
+.. versionadded:: 1.2
+ Version blocks are preserved.
+
+.. versionchanged:: 2.3
+ Version blocks are preserved.
+
 .. |substitution| replace::
    |nested substitution|
    with multiple lines becomes one line