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

@@ -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()
 # }}}
 

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)

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