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
This commit is contained in:
Brad King 2013-10-24 09:51:44 -04:00 committed by CMake Topic Stage
commit c10e981fd0
18 changed files with 147 additions and 45 deletions

View File

@ -230,30 +230,46 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files.
Module Documentation Module Documentation
-------------------- --------------------
To add a module to the CMake documentation, follow these steps: To document CMake module ``Modules/<module-name>.cmake``, modify
``Help/manual/cmake-modules.7.rst`` to reference the module in the
1. Add file ``Help/module/<module-name>.rst`` containing just the line:: ``toctree`` directive, in sorted order, as::
.. cmake-module:: ../../Modules/<module-name>.cmake
2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
toctree directive as::
/module/<module-name> /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: #.rst:
# <module-name> # <module-name>
# ------------- # -------------
# #
# ...reStructuredText documentation of module... # <reStructuredText documentation of module>
Comment blocks starting with the line ``#.rst:`` may appear anywhere or a bracket-comment of the form:
in the file. The ``cmake-module`` directive used above will scan the
file to extract reStructuredText markup from such comments. .. 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: For example, a ``Modules/Findxxx.cmake`` module may contain:
@ -275,12 +291,13 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
<code> <code>
#.rst: #[========================================[.rst:
# .. command:: xxx_do_something .. command:: xxx_do_something
#
# This command does something for Xxx:: This command does something for Xxx::
#
# xxx_do_something(some arguments) xxx_do_something(some arguments)
#]========================================]
macro(xxx_do_something) macro(xxx_do_something)
<code> <code>
endmacro() endmacro()

View File

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

View File

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

View File

@ -34,6 +34,7 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot):
ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"), ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"),
IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"), IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"),
TocTreeDirective("^.. toctree::[ \t]*(.*)$"), TocTreeDirective("^.. toctree::[ \t]*(.*)$"),
ModuleRST("^#\\[(=*)\\[\\.rst:$"),
CMakeRole("(:cmake)?:(" CMakeRole("(:cmake)?:("
"command|generator|variable|module|policy|" "command|generator|variable|module|policy|"
"prop_cache|prop_dir|prop_gbl|prop_sf|prop_test|prop_tgt|" "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; std::string rst;
while(cmSystemTools::GetLineFromStream(is, line)) 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(rst == "#")
{ {
if(line == "#") if(line == "#")
@ -108,6 +131,11 @@ void cmRST::ProcessModule(std::istream& is)
{ {
rst = "#"; rst = "#";
} }
else if(this->ModuleRST.find(line))
{
rst = "]" + this->ModuleRST.match(1) + "]";
}
}
} }
if(rst == "#") if(rst == "#")
{ {

View File

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

View File

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

View File

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

View File

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

View File

@ -0,0 +1 @@
1

View File

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

View File

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

View File

@ -0,0 +1 @@
1

View File

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

View File

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

View File

@ -0,0 +1 @@
1

View File

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

View File

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

View File

@ -31,7 +31,6 @@ class CMakeModule(Directive):
def __init__(self, *args, **keys): def __init__(self, *args, **keys):
self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$') self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$')
self.re_end = re.compile(r'^#?\](?P<eq>=*)\]$')
Directive.__init__(self, *args, **keys) Directive.__init__(self, *args, **keys)
def run(self): def run(self):
@ -61,7 +60,22 @@ class CMakeModule(Directive):
rst = None rst = None
lines = [] lines = []
for line in raw_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 = '#' rst = '#'
line = '' line = ''
elif rst == '#': elif rst == '#':
@ -70,9 +84,12 @@ class CMakeModule(Directive):
else: else:
rst = None rst = None
line = '' line = ''
else: elif rst is None:
line = '' line = ''
lines.append(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) self.state_machine.insert_input(lines, path)
return [] return []