Merge topic 'builtin-help-versionadded'

054754359a cmRST: support `versionadded` and `versionchanged` directives

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !6667

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

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

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;

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.

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