Merge topic 'cmake-syntax-updates'

2945814 cmRST: Teach cmake-module directive to scan bracket comments
8bb2ee9 cmake-developer.7: Improve flow of module documentation instructions
efcf318 Add \-continuation to CMake language quoted arguments

Help/manual/cmake-developer.7.rst

@@ -230,30 +230,46 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files.
 Module Documentation
 --------------------
 
-To add a module to the CMake documentation, follow these steps:
-
-1. Add file ``Help/module/<module-name>.rst`` containing just the line::
-
-    .. cmake-module:: ../../Modules/<module-name>.cmake
-
-2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
-   toctree directive as::
+To document CMake module ``Modules/<module-name>.cmake``, modify
+``Help/manual/cmake-modules.7.rst`` to reference the module in the
+``toctree`` directive, in sorted order, as::
 
  /module/<module-name>
 
-   Keep the toctree in sorted order!
+Then add the module document file ``Help/module/<module-name>.rst``
+containing just the line::
 
-3. Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form::
+ .. cmake-module:: ../../Modules/<module-name>.cmake
+
+The ``cmake-module`` directive will scan the module file to extract
+reStructuredText markup from comment blocks that start in ``.rst:``.
+Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:
+
+.. code-block:: cmake
 
  #.rst:
  # <module-name>
  # -------------
  #
-    # ...reStructuredText documentation of module...
+ # <reStructuredText documentation of module>
 
-   Comment blocks starting with the line ``#.rst:`` may appear anywhere
-   in the file.  The ``cmake-module`` directive used above will scan the
-   file to extract reStructuredText markup from such comments.
+or a bracket-comment of the form:
+
+.. code-block:: cmake
+
+ #[[.rst:
+ <module-name>
+ -------------
+
+ <reStructuredText documentation of module>
+ #]]
+
+Any number of ``=`` may be used in the opening and closing brackets
+as long as they match.  Content on the line containing the closing
+bracket is excluded if and only if the line starts in ``#``.
+
+Additional such ``.rst:`` comments may appear anywhere in the module file.
+All such comments must start with ``#`` in the first column.
 
 For example, a ``Modules/Findxxx.cmake`` module may contain:
 
@@ -275,12 +291,13 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
 
  <code>
 
- #.rst:
- # .. command:: xxx_do_something
- #
- #  This command does something for Xxx::
- #
- #   xxx_do_something(some arguments)
+ #[========================================[.rst:
+ .. command:: xxx_do_something
+
+  This command does something for Xxx::
+
+   xxx_do_something(some arguments)
+ #]========================================]
  macro(xxx_do_something)
    <code>
  endmacro()

Source/cmListFileLexer.c

@@ -1127,7 +1127,7 @@ case 17:
 YY_RULE_SETUP
 #line 224 "cmListFileLexer.in.l"
 {
-  cmListFileLexerAppend(lexer, yytext, yyleng);
+  /* Continuation: text is not part of string */
   ++lexer->line;
   lexer->column = 1;
 }

Source/cmListFileLexer.in.l

@@ -222,7 +222,7 @@ LEGACY {MAKEVAR}|{UNQUOTED}|\"({MAKEVAR}|{UNQUOTED}|[ \t[=])*\"
 }
 
 <STRING>\\\n {
-  cmListFileLexerAppend(lexer, yytext, yyleng);
+  /* Continuation: text is not part of string */
   ++lexer->line;
   lexer->column = 1;
 }

Source/cmRST.cxx

@@ -34,6 +34,7 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot):
   ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"),
   IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"),
   TocTreeDirective("^.. toctree::[ \t]*(.*)$"),
+  ModuleRST("^#\\[(=*)\\[\\.rst:$"),
   CMakeRole("(:cmake)?:("
             "command|generator|variable|module|policy|"
             "prop_cache|prop_dir|prop_gbl|prop_sf|prop_test|prop_tgt|"
@@ -85,6 +86,28 @@ void cmRST::ProcessModule(std::istream& is)
   std::string rst;
   while(cmSystemTools::GetLineFromStream(is, line))
     {
+    if(!rst.empty() && rst != "#")
+      {
+      // Bracket mode: check for end bracket
+      std::string::size_type pos = line.find(rst);
+      if(pos == line.npos)
+        {
+        this->ProcessLine(line);
+        }
+      else
+        {
+        if(line[0] != '#')
+          {
+          this->ProcessLine(line.substr(0, pos));
+          }
+        rst = "";
+        this->Reset();
+        this->OutputLinePending = true;
+        }
+      }
+    else
+      {
+      // Line mode: check for .rst start (bracket or line)
       if(rst == "#")
         {
         if(line == "#")
@@ -108,6 +131,11 @@ void cmRST::ProcessModule(std::istream& is)
         {
         rst = "#";
         }
+      else if(this->ModuleRST.find(line))
+        {
+        rst = "]" + this->ModuleRST.match(1) + "]";
+        }
+      }
     }
   if(rst == "#")
     {

Source/cmRST.h

@@ -84,6 +84,7 @@ private:
   cmsys::RegularExpression ReplaceDirective;
   cmsys::RegularExpression IncludeDirective;
   cmsys::RegularExpression TocTreeDirective;
+  cmsys::RegularExpression ModuleRST;
   cmsys::RegularExpression CMakeRole;
   cmsys::RegularExpression Substitution;
 

Tests/CMakeLib/testRST.expect

@@ -27,6 +27,12 @@ CMake Module Content
 
 More CMake Module Content
 
+Bracket Comment Content
+
+[
+Bracket Comment Content
+]
+
 .. cmake:command:: some_cmd
 
    Command some_cmd description.

Tests/CMakeLib/testRSTmod.cmake

@@ -2,3 +2,10 @@
 # CMake Module Content
 #.rst:
 # More CMake Module Content
+#[[.rst:
+Bracket Comment Content
+# not part of content]] # not part of content
+#[=[.rst:
+[
+Bracket Comment Content
+]]=] # not part of content

Tests/RunCMake/Syntax/RunCMakeTest.cmake

@@ -14,7 +14,10 @@ run_cmake(CommandError1)
 run_cmake(CommandError2)
 run_cmake(String0)
 run_cmake(String1)
+run_cmake(StringBackslash)
 run_cmake(StringCRLF)
+run_cmake(StringContinuation1)
+run_cmake(StringContinuation2)
 run_cmake(StringNoSpace)
 run_cmake(OneLetter)
 run_cmake(Unquoted0)

Tests/RunCMake/Syntax/StringBackslash-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringBackslash-stderr.txt

@@ -0,0 +1,6 @@
+CMake Error at StringBackslash.cmake:1 \(message\):
+  a\\
+
+  b
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringBackslash.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\
+b")

Tests/RunCMake/Syntax/StringContinuation1-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringContinuation1-stderr.txt

@@ -0,0 +1,4 @@
+CMake Error at StringContinuation1.cmake:1 \(message\):
+  ab
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringContinuation1.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\
+b")

Tests/RunCMake/Syntax/StringContinuation2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringContinuation2-stderr.txt

@@ -0,0 +1,4 @@
+CMake Error at StringContinuation2.cmake:1 \(message\):
+  a\\b
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringContinuation2.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\\
+b")

Utilities/Sphinx/cmake.py

@@ -31,7 +31,6 @@ class CMakeModule(Directive):
 
     def __init__(self, *args, **keys):
         self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$')
-        self.re_end = re.compile(r'^#?\](?P<eq>=*)\]$')
         Directive.__init__(self, *args, **keys)
 
     def run(self):
@@ -61,7 +60,22 @@ class CMakeModule(Directive):
         rst = None
         lines = []
         for line in raw_lines:
-            if line == '#.rst:':
+            if rst is not None and rst != '#':
+                # Bracket mode: check for end bracket
+                pos = line.find(rst)
+                if pos >= 0:
+                    if line[0] == '#':
+                        line = ''
+                    else:
+                        line = line[0:pos]
+                    rst = None
+            else:
+                # Line mode: check for .rst start (bracket or line)
+                m = self.re_start.match(line)
+                if m:
+                    rst = ']%s]' % m.group('eq')
+                    line = ''
+                elif line == '#.rst:':
                     rst = '#'
                     line = ''
                 elif rst == '#':
@@ -70,9 +84,12 @@ class CMakeModule(Directive):
                     else:
                         rst = None
                         line = ''
-            else:
+                elif rst is None:
                     line = ''
             lines.append(line)
+        if rst is not None and rst != '#':
+            raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' %
+                               (self.name, rst[1:-1], path))
         self.state_machine.insert_input(lines, path)
         return []