cmake: use luadoc for functions exported from C

Documenting half of the Lua API in the awesomerc manpage and the other
half with luadoc, doesn't make much sense. I modified the output of
gendoc.lua to something that looks like lua with luadoc markup. That
file can then be processed by luadoc and we have all Lua documentation in
one place.

And yes, we're now pulling custom doxygen tags out of C source code to
generate annotated lua source code we never use, which is then mangled
again by luadoc to spit out a set of html files.
This commit is contained in:
Michael Gehring 2008-06-23 18:19:39 +02:00 committed by Julien Danjou
parent c3272d19a3
commit 27bc445664
3 changed files with 81 additions and 68 deletions

View File

@ -169,52 +169,6 @@ endif()
# {{{ Manpages. # {{{ Manpages.
if(GENERATE_MANPAGES) if(GENERATE_MANPAGES)
# {{{ Lua API documentation.
set(LUADOC_FILE ${BUILD_DIR}/apidocgen.txt)
macro(a_file_match infile regex result_var)
if(CMAKE_MAJOR_VERSION EQUAL 2 AND CMAKE_MINOR_VERSION LESS 6)
# cmake < 2.6 doesn't know FILE(STRINGS ...)
execute_process(
COMMAND ${GREP_EXECUTABLE} -l ${regex} ${infile}
RESULT_VARIABLE exit_code
OUTPUT_QUIET)
if(exit_code EQUAL 0)
set(${result_var} TRUE)
else()
set(${result_var} FALSE)
endif()
else()
file(STRINGS ${infile} match REGEX ${regex} LIMIT_COUNT 1)
if(match)
set(${result_var} TRUE)
else()
set(${result_var} FALSE)
endif()
endif()
endmacro()
# find .c files exporting lua functions
foreach(cfile ${AWE_SRCS})
a_file_match(${cfile} "const struct luaL_reg" result)
if(result)
set(LUA_APIDOC_SRCS ${LUA_APIDOC_SRCS} ${cfile})
endif()
endforeach()
# luadoc target
add_custom_command(
COMMAND ${CAT_EXECUTABLE} ${LUA_APIDOC_SRCS}
| ${LUA_EXECUTABLE} ${SOURCE_DIR}/build-utils/gendoc.lua
> ${LUADOC_FILE}
OUTPUT ${LUADOC_FILE}
WORKING_DIRECTORY ${SOURCE_DIR}
DEPENDS ${LUA_APIDOC_SRCS}
COMMENT "Generating Lua API documentation."
VERBATIM)
# }}}
foreach(txtfile ${AWE_MAN_SRCS}) foreach(txtfile ${AWE_MAN_SRCS})
string(REGEX REPLACE ".txt\$" ".xml" xmlfile ${txtfile}) string(REGEX REPLACE ".txt\$" ".xml" xmlfile ${txtfile})
string(REPLACE ${SOURCE_DIR} string(REPLACE ${SOURCE_DIR}
@ -222,14 +176,12 @@ if(GENERATE_MANPAGES)
string(REGEX REPLACE ".xml\$" ".gz" gzfile ${xmlfile}) string(REGEX REPLACE ".xml\$" ".gz" gzfile ${xmlfile})
string(REGEX REPLACE ".gz\$" "" manfile ${gzfile}) string(REGEX REPLACE ".gz\$" "" manfile ${gzfile})
# TODO: This is still not 100% right. Actually only
# awesomerc.5.xml should depend on ${LUADOC_FILE}.
add_custom_command( add_custom_command(
COMMAND ${CAT_EXECUTABLE} ${txtfile} COMMAND ${CAT_EXECUTABLE} ${txtfile}
| ${ASCIIDOC_EXECUTABLE} -d manpage -b docbook -o ${xmlfile} - | ${ASCIIDOC_EXECUTABLE} -d manpage -b docbook -o ${xmlfile} -
WORKING_DIRECTORY ${BUILD_DIR} WORKING_DIRECTORY ${BUILD_DIR}
OUTPUT ${xmlfile} OUTPUT ${xmlfile}
DEPENDS ${txtfile} ${LUADOC_FILE} DEPENDS ${txtfile}
VERBATIM) VERBATIM)
add_custom_command( add_custom_command(
COMMAND ${XMLTO_EXECUTABLE} man ${xmlfile} COMMAND ${XMLTO_EXECUTABLE} man ${xmlfile}
@ -264,17 +216,72 @@ endif()
# {{{ Lua API Documentation # {{{ Lua API Documentation
if(LUADOC_EXECUTABLE) if(LUADOC_EXECUTABLE)
set(capi_lua ${BUILD_DIR}/lib/capi.lua)
if(NOT BUILD_DIR STREQUAL SOURCE_DIR)
file(MAKE_DIRECTORY ${BUILD_DIR}/lib)
# setup symlink so everything is in one directory
foreach(lua_file ${AWE_LUA_FILES})
execute_process(COMMAND ${LN_EXECUTABLE} -s ${lua_file}
WORKING_DIRECTORY ${BUILD_DIR}/lib)
endforeach()
endif()
# {{{ setup a command for ${capi_lua}
macro(a_file_match infile regex result_var)
if(CMAKE_MAJOR_VERSION EQUAL 2 AND CMAKE_MINOR_VERSION LESS 6)
# cmake < 2.6 doesn't know FILE(STRINGS ...)
execute_process(
COMMAND ${GREP_EXECUTABLE} -l ${regex} ${infile}
RESULT_VARIABLE exit_code
OUTPUT_QUIET)
if(exit_code EQUAL 0)
set(${result_var} TRUE)
else()
set(${result_var} FALSE)
endif()
else()
file(STRINGS ${infile} match REGEX ${regex} LIMIT_COUNT 1)
if(match)
set(${result_var} TRUE)
else()
set(${result_var} FALSE)
endif()
endif()
endmacro()
set(luadoc_c_srcs "")
# find .c files exporting lua functions
foreach(cfile ${AWE_SRCS})
a_file_match(${cfile} "const struct luaL_reg" result)
if(result)
set(luadoc_c_srcs ${luadoc_c_srcs} ${cfile})
endif()
endforeach()
# create fake lua source file to process by luadoc
add_custom_command(
COMMAND ${CAT_EXECUTABLE} ${luadoc_c_srcs}
| ${LUA_EXECUTABLE} ${SOURCE_DIR}/build-utils/fake-lua-src.lua
> ${capi_lua}
OUTPUT ${capi_lua}
DEPENDS ${luadoc_c_srcs}
COMMENT "Generating fake lua source."
VERBATIM)
# }}}
# dont include full path names in documentation # dont include full path names in documentation
set(luadoc_srcs "") foreach(filename ${AWE_LUA_FILES} ${capi_lua})
foreach(file ${AWE_LUA_FILES}) get_filename_component(filename ${filename} NAME)
string(REPLACE ${SOURCE_DIR}/ "" file ${file}) set(luadoc_srcs ${luadoc_srcs} ${filename})
set(luadoc_srcs ${luadoc_srcs} ${file})
endforeach() endforeach()
add_custom_target(luadoc ALL add_custom_target(luadoc ALL
COMMAND ${LUADOC_EXECUTABLE} ${luadoc_srcs} -d ${BUILD_DIR}/luadoc COMMAND ${LUADOC_EXECUTABLE} ${luadoc_srcs} -d ${BUILD_DIR}/luadoc
WORKING_DIRECTORY ${SOURCE_DIR} WORKING_DIRECTORY ${BUILD_DIR}/lib
DEPENDS ${AWE_LUA_FILES}) DEPENDS ${AWE_LUA_FILES} ${capi_lua})
endif() endif()
# }}} # }}}

View File

@ -26,6 +26,7 @@ add_definitions(-std=gnu99 -ggdb3 -fno-strict-aliasing -Wall -Wextra
# {{{ Find external utilities # {{{ Find external utilities
find_program(CAT_EXECUTABLE cat) find_program(CAT_EXECUTABLE cat)
find_program(LN_EXECUTABLE ln)
find_program(GREP_EXECUTABLE grep) find_program(GREP_EXECUTABLE grep)
find_program(GIT_EXECUTABLE git) find_program(GIT_EXECUTABLE git)
find_program(GPERF_EXECUTABLE gperf) find_program(GPERF_EXECUTABLE gperf)

View File

@ -1,14 +1,19 @@
#!/usr/bin/lua #!/usr/bin/lua
-- Generate documentation for awesome Lua functions -- Translate the custom doxygen tags in c-source to a
-- dummy lua source file that can be processed by luadoc.
-- Take a .c file in stdin -- Take a .c file in stdin
function string.comment_clean(str) function string.comment_translate(s)
local s = str:gsub("/%*%* ", " ") local lua_comment = "";
s = s:gsub(" %*", "") for line in s:gmatch("[^\r\n]+") do
s = s:gsub("\\luastack", "") line = line:gsub("/%*%*", "---")
s = s:gsub("\\lparam", "\n\n Parameter:") line = line:gsub("^.*%*", "--")
s = s:gsub("\\lreturn", "\n\n Return:") line = line:gsub("\\lvalue", "@param")
return s line = line:gsub("\\lparam", "@param")
line = line:gsub("\\lreturn", "@return")
lua_comment = lua_comment .. line .. "\n"
end
return lua_comment
end end
-- Read all the files in lines -- Read all the files in lines
@ -37,8 +42,8 @@ for i, line in ipairs(ilines) do
end end
comment = nil comment = nil
elseif comment_start then elseif comment_start then
if not line:find("\\param") and not line:find("\\return") and not line:find("\\lvalue") then if not line:find("\\param") and not line:find("\\return") and not line:find("\\luastack") then
comment = comment .. line comment = comment .. "\n" .. line
end end
end end
end end
@ -57,10 +62,10 @@ for i, line in ipairs(ilines) do
local fctname, fctdef local fctname, fctdef
_, _, fctname, fctdef = line:find("\"(.+)\", (.+) },") _, _, fctname, fctdef = line:find("\"(.+)\", (.+) },")
if fctname and not fctname:find("^__") then if fctname and not fctname:find("^__") then
if libtype == "meta" then sep = ":" else sep = "." end
print("*" .. libname .. sep .. fctname .. "*::")
if function_doc[fctdef] then if function_doc[fctdef] then
print(function_doc[fctdef]:comment_clean()) print(function_doc[fctdef]:comment_translate())
print("function " .. libname .. "." .. fctname .. "()")
print("end");
else else
print("This function is not yet documented.") print("This function is not yet documented.")
end end