Merge pull request #1603 from Elv13/doc_add_script_section

Add rc.lua and theme.lua to ldoc

awesomeConfig.cmake

@@ -389,6 +389,9 @@ endif()
 #}}}
 
 # {{{ Generate some aggregated documentation from lua script
+
+file(MAKE_DIRECTORY ${BUILD_DIR}/script_files/)
+
 add_custom_command(
         OUTPUT ${BUILD_DIR}/docs/06-appearance.md
         COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua
@@ -398,13 +401,30 @@ add_custom_command(
 
 add_custom_command(
         OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md
+            ${BUILD_DIR}/script_files/rc.lua
         COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua
         ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua
         ${BUILD_DIR}/awesomerc.lua
+        ${BUILD_DIR}/script_files/rc.lua
 )
 
-# Create a target for the auto-generated awesomerc.lua
+add_custom_command(
-add_custom_target(generate_awesomerc DEPENDS ${BUILD_DIR}/awesomerc.lua)
+        OUTPUT ${BUILD_DIR}/script_files/theme.lua
+        COMMAND lua ${SOURCE_DIR}/docs/sample_theme.lua ${BUILD_DIR}/script_files/
+)
+
+# Create a target for the auto-generated awesomerc.lua and other files
+add_custom_target(generate_awesomerc DEPENDS
+    ${BUILD_DIR}/awesomerc.lua
+    ${BUILD_DIR}/script_files/theme.lua
+    ${BUILD_DIR}/script_files/rc.lua
+    ${SOURCE_DIR}/awesomerc.lua
+    ${BUILD_DIR}/docs/06-appearance.md
+    ${SOURCE_DIR}/docs/05-awesomerc.md.lua
+    ${SOURCE_DIR}/docs/sample_theme.lua
+    ${SOURCE_DIR}/docs/sample_files.lua
+    ${SOURCE_DIR}/awesomerc.lua
+)
 
 
 #}}}

docs/05-awesomerc.md.lua

@@ -1,4 +1,4 @@
-local filename, rcfile, new_rcfile = ...
+local filename, rcfile, new_rcfile, rc_script = ...
 
 local f = assert(io.open(filename, "w"))
 
@@ -242,7 +242,16 @@ local rc = assert(io.open(rcfile))
 
 local doc_block = false
 
-local output = {}
+local output, output_script = {}, {[[
+---------------------------------------------------------------------------
+--- The default rc.lua file.
+--
+-- A copy of this file is usually installed in `/etc/xdg/awesome/`.
+--
+-- See [The declarative layout system](../documentation/05-awesomerc.md.html)
+-- for a version with additional comments.
+--
+--]]}
 
 for line in rc:lines() do
     local tag = line:match("@([^@]+)@")
@@ -274,6 +283,7 @@ for line in rc:lines() do
             f:write(add_links(line))
         end
         table.insert(output, line)
+        table.insert(output_script, "--    "..line)
     else
         -- Take the documentation found in this file and append it
         if doc_block then
@@ -296,3 +306,10 @@ f:close()
 local rc_lua = assert(io.open(new_rcfile, "w"))
 rc_lua:write(table.concat(output, "\n"))
 rc_lua:close()
+
+
+table.insert(output_script, "-- @script rc.lua")
+
+rc_script = assert(io.open(rc_script, "w"))
+rc_script:write(table.concat(output_script, "\n"))
+rc_script:close()

docs/config.ld

@@ -68,7 +68,7 @@ new_type("clientlayout", "Client layouts", false, "param")
 new_type("callback", "Callback functions prototype", false, "Parameters")
 
 -- More fitting section names
-kind_names={topic='Documentation', module='Libraries'}
+kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 
 -- Sort modules alphabetically
 sort_modules=true
@@ -88,6 +88,8 @@ file = {
     '../objects/',
     -- LUA libraries
     '../lib/',
+    -- Auto generated scripts
+    '../script_files/',
     -- Old APIs the user should not longer use directly
     '../docs/aliases/awful_client.lua',
     '../docs/aliases/awful_screen.lua',

docs/sample_files.lua

@@ -0,0 +1,32 @@
+-- Take a Lua file and add it to the documentation sample files.
+-- Also add \` to generate all links
+
+-- Tell ldoc to generate links
+    local function add_links(line)
+        for _, module in ipairs {
+            "awful", "wibox", "gears", "naughty", "menubar", "beautiful"
+        } do
+            if line:match(module.."%.") then
+                line = line:gsub("("..module.."[.a-zA-Z]+)", "`%1`")
+            end
+        end
+
+        return "--    "..line
+    end
+
+return function(name, input_path, output_path, header)
+    local input = assert(io.open(input_path))
+    local output_script = {header}
+
+    -- Escape all lines
+    for line in input:lines() do
+        table.insert(output_script, add_links(line))
+    end
+
+    -- Add the script name
+    table.insert(output_script, "-- @script "..name)
+
+    output_path = assert(io.open(output_path, "w"))
+    output_path:write(table.concat(output_script, "\n"))
+    output_path:close()
+end

docs/sample_theme.lua

@@ -0,0 +1,29 @@
+--- Take the default theme and add it to ldoc as a sample file.
+local output_path = ...
+
+local path = debug.getinfo(1,"S").source:gsub("sample_theme.*",""):gsub("@","")
+package.path = path .. '?.lua;' .. package.path
+
+require("sample_files")(
+    "theme.lua",
+    path.."../themes/default/theme.lua",
+    output_path.."/theme.lua",
+[[---------------------------------------------------------------------------
+--- The default theme file.
+--
+-- If you wish to create a custom theme, copy this file to
+-- `~/.config/awesome/mytheme.lua`
+-- and replace:
+--
+--    beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua")
+--
+-- with
+--
+--    beautiful.init(awful.util.getdir("config") .. "mytheme.lua")
+--
+-- in your `rc.lua`.
+--
+-- Here is the default theme content:
+--
+--]]
+)