From 27bc4456648c3db688e1363bc32b3adbd82f56ee Mon Sep 17 00:00:00 2001 From: Michael Gehring Date: Mon, 23 Jun 2008 18:19:39 +0200 Subject: [PATCH] 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. --- CMakeLists.txt | 117 ++++++++++--------- awesomeConfig.cmake | 1 + build-utils/{gendoc.lua => fake-lua-src.lua} | 31 ++--- 3 files changed, 81 insertions(+), 68 deletions(-) rename build-utils/{gendoc.lua => fake-lua-src.lua} (69%) diff --git a/CMakeLists.txt b/CMakeLists.txt index c6eca49e5..7d729ff01 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -169,52 +169,6 @@ endif() # {{{ 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}) string(REGEX REPLACE ".txt\$" ".xml" xmlfile ${txtfile}) string(REPLACE ${SOURCE_DIR} @@ -222,14 +176,12 @@ if(GENERATE_MANPAGES) string(REGEX REPLACE ".xml\$" ".gz" gzfile ${xmlfile}) 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( COMMAND ${CAT_EXECUTABLE} ${txtfile} | ${ASCIIDOC_EXECUTABLE} -d manpage -b docbook -o ${xmlfile} - WORKING_DIRECTORY ${BUILD_DIR} OUTPUT ${xmlfile} - DEPENDS ${txtfile} ${LUADOC_FILE} + DEPENDS ${txtfile} VERBATIM) add_custom_command( COMMAND ${XMLTO_EXECUTABLE} man ${xmlfile} @@ -264,17 +216,72 @@ endif() # {{{ Lua API Documentation 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 - set(luadoc_srcs "") - foreach(file ${AWE_LUA_FILES}) - string(REPLACE ${SOURCE_DIR}/ "" file ${file}) - set(luadoc_srcs ${luadoc_srcs} ${file}) + foreach(filename ${AWE_LUA_FILES} ${capi_lua}) + get_filename_component(filename ${filename} NAME) + set(luadoc_srcs ${luadoc_srcs} ${filename}) endforeach() add_custom_target(luadoc ALL COMMAND ${LUADOC_EXECUTABLE} ${luadoc_srcs} -d ${BUILD_DIR}/luadoc - WORKING_DIRECTORY ${SOURCE_DIR} - DEPENDS ${AWE_LUA_FILES}) + WORKING_DIRECTORY ${BUILD_DIR}/lib + DEPENDS ${AWE_LUA_FILES} ${capi_lua}) endif() # }}} diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index ef93b2e08..ba09c770c 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -26,6 +26,7 @@ add_definitions(-std=gnu99 -ggdb3 -fno-strict-aliasing -Wall -Wextra # {{{ Find external utilities find_program(CAT_EXECUTABLE cat) +find_program(LN_EXECUTABLE ln) find_program(GREP_EXECUTABLE grep) find_program(GIT_EXECUTABLE git) find_program(GPERF_EXECUTABLE gperf) diff --git a/build-utils/gendoc.lua b/build-utils/fake-lua-src.lua similarity index 69% rename from build-utils/gendoc.lua rename to build-utils/fake-lua-src.lua index 52f5ba831..38a332229 100755 --- a/build-utils/gendoc.lua +++ b/build-utils/fake-lua-src.lua @@ -1,14 +1,19 @@ #!/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 -function string.comment_clean(str) - local s = str:gsub("/%*%* ", " ") - s = s:gsub(" %*", "") - s = s:gsub("\\luastack", "") - s = s:gsub("\\lparam", "\n\n Parameter:") - s = s:gsub("\\lreturn", "\n\n Return:") - return s +function string.comment_translate(s) + local lua_comment = ""; + for line in s:gmatch("[^\r\n]+") do + line = line:gsub("/%*%*", "---") + line = line:gsub("^.*%*", "--") + line = line:gsub("\\lvalue", "@param") + line = line:gsub("\\lparam", "@param") + line = line:gsub("\\lreturn", "@return") + lua_comment = lua_comment .. line .. "\n" + end + return lua_comment end -- Read all the files in lines @@ -37,8 +42,8 @@ for i, line in ipairs(ilines) do end comment = nil elseif comment_start then - if not line:find("\\param") and not line:find("\\return") and not line:find("\\lvalue") then - comment = comment .. line + if not line:find("\\param") and not line:find("\\return") and not line:find("\\luastack") then + comment = comment .. "\n" .. line end end end @@ -57,10 +62,10 @@ for i, line in ipairs(ilines) do local fctname, fctdef _, _, fctname, fctdef = line:find("\"(.+)\", (.+) },") if fctname and not fctname:find("^__") then - if libtype == "meta" then sep = ":" else sep = "." end - print("*" .. libname .. sep .. fctname .. "*::") if function_doc[fctdef] then - print(function_doc[fctdef]:comment_clean()) + print(function_doc[fctdef]:comment_translate()) + print("function " .. libname .. "." .. fctname .. "()") + print("end"); else print("This function is not yet documented.") end