doc: Add the default rc.lua to the API documentation

Enable the `Sample files` section provided by ldoc but unused
until now.

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,9 +401,11 @@ 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

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',