doc: Document rc.lua

This meta-lua script takes the "raw" awesomerc.lua and turn it
into the final file and generate a documentation page from its
parsed content. It support

 * Turn {{{ into markdown categories
 * Turn top level comments into documentation
 * Add custom documentation sections
 * Parse the code to add links for each API calls

This helps generate a good entry point for new users wanting to
understand the content of rc.lua without searching the API by
hand.

Over time, this will also become the basis of the documentation.

If `rc.lua` is separated into several files, this will be easy to fix
this script. It could even do the separation itself from a monolitic
file using the already implemented {{{ parser.

CMakeLists.txt

@@ -277,6 +277,7 @@ if(GENERATE_DOC)
         COMMAND ${LDOC_EXECUTABLE} . 3>&1 1>&2 2>&3 | awk "{ fail=1 \; print } END { exit fail }"
         WORKING_DIRECTORY ${AWE_DOC_DIR}
         DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/06-appearance.md
+        ${BUILD_DIR}/docs/05-awesomerc.md
     )
 
 endif()

awesomeConfig.cmake

@@ -329,7 +329,6 @@ set(AWESOME_CONFIGURE_FILES
     ${awesome_lua_configure_files}
     config.h
     docs/config.ld
-    awesomerc.lua
     awesome-version-internal.h)
 
 foreach(file ${AWESOME_CONFIGURE_FILES})
@@ -347,6 +346,15 @@ add_custom_command(
         ${BUILD_DIR}/docs/06-appearance.md
 )
 
+add_custom_command(
+        OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md
+        COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua
+        ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua
+        ${BUILD_DIR}/awesomerc.lua
+)
+
+#}}}
+
 # {{{ Copy additional files
 file(GLOB awesome_md_docs RELATIVE ${SOURCE_DIR}
     ${SOURCE_DIR}/docs/*.md)

awesomerc.lua

@@ -1,3 +1,4 @@
+-- @DOC_REQUIRE_SECTION@
 -- Standard awesome library
 local gears = require("gears")
 local awful = require("awful")
@@ -12,6 +13,7 @@ local menubar = require("menubar")
 local hotkeys_popup = require("awful.hotkeys_popup").widget
 
 -- {{{ Error handling
+-- @DOC_ERROR_HANDLING@
 -- Check if awesome encountered an error during startup and fell back to
 -- another config (This code will only ever execute for the fallback config)
 if awesome.startup_errors then
@@ -37,9 +39,11 @@ end
 -- }}}
 
 -- {{{ Variable definitions
+-- @DOC_LOAD_THEME@
 -- Themes define colours, icons, font and wallpapers.
 beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua")
 
+-- @DOC_DEFAULT_APPLICATIONS@
 -- This is used later as the default terminal and editor to run.
 terminal = "xterm"
 editor = os.getenv("EDITOR") or "nano"
@@ -52,6 +56,7 @@ editor_cmd = terminal .. " -e " .. editor
 -- However, you can use another modifier like Mod1, but it may interact with others.
 modkey = "Mod4"
 
+-- @DOC_LAYOUT@
 -- Table of layouts to cover with awful.layout.inc, order matters.
 awful.layout.layouts = {
     awful.layout.suit.floating,
@@ -89,6 +94,7 @@ end
 -- }}}
 
 -- {{{ Menu
+-- @DOC_MENU@
 -- Create a launcher widget and a main menu
 myawesomemenu = {
    { "hotkeys", function() return false, hotkeys_popup.show_help end},
@@ -113,7 +119,7 @@ menubar.utils.terminal = terminal -- Set the terminal for applications that requ
 -- Keyboard map indicator and switcher
 mykeyboardlayout = awful.widget.keyboardlayout()
 
--- {{{ Wibox
+-- {{{ Wibar
 -- Create a textclock widget
 mytextclock = wibox.widget.textclock()
 
@@ -122,6 +128,7 @@ mywibox = {}
 mypromptbox = {}
 mylayoutbox = {}
 mytaglist = {}
+-- @TAGLIST_BUTTON@
 mytaglist.buttons = awful.util.table.join(
                     awful.button({ }, 1, function(t) t:view_only() end),
                     awful.button({ modkey }, 1, function(t)
@@ -140,6 +147,7 @@ mytaglist.buttons = awful.util.table.join(
                 )
 
 mytasklist = {}
+-- @TASKLIST_BUTTON@
 mytasklist.buttons = awful.util.table.join(
                      awful.button({ }, 1, function (c)
                                               if c == client.focus then
@@ -165,7 +173,9 @@ mytasklist.buttons = awful.util.table.join(
                                               awful.client.focus.byidx(-1)
                                           end))
 
+-- @DOC_WALLPAPER@
 local function set_wallpaper(s)
+    -- Wallpaper
     if beautiful.wallpaper then
         local wallpaper = beautiful.wallpaper
         -- If wallpaper is a function, call it with the screen
@@ -179,6 +189,7 @@ end
 -- Re-set wallpaper when a screen's geometry changes (e.g. different resolution)
 screen.connect_signal("property::geometry", set_wallpaper)
 
+-- @DOC_FOR_EACH_SCREEN@
 awful.screen.connect_for_each_screen(function(s)
     -- Wallpaper
     set_wallpaper(s)
@@ -202,9 +213,11 @@ awful.screen.connect_for_each_screen(function(s)
     -- Create a tasklist widget
     mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons)
 
+    -- @DOC_WIBAR@
     -- Create the wibox
     mywibox[s] = awful.wibar({ position = "top", screen = s })
 
+    -- @DOC_SETUP_WIDGETS@
     -- Add widgets to the wibox
     mywibox[s]:setup {
         layout = wibox.layout.align.horizontal,
@@ -227,6 +240,7 @@ end)
 -- }}}
 
 -- {{{ Mouse bindings
+-- @DOC_ROOT_BUTTONS@
 root.buttons(awful.util.table.join(
     awful.button({ }, 3, function () mymainmenu:toggle() end),
     awful.button({ }, 4, awful.tag.viewnext),
@@ -235,6 +249,7 @@ root.buttons(awful.util.table.join(
 -- }}}
 
 -- {{{ Key bindings
+-- @DOC_GLOBAL_KEYBINDINGS@
 globalkeys = awful.util.table.join(
     awful.key({ modkey,           }, "s",      hotkeys_popup.show_help,
               {description="show help", group="awesome"}),
@@ -333,6 +348,7 @@ globalkeys = awful.util.table.join(
               {description = "show the menubar", group = "launcher"})
 )
 
+-- @DOC_CLIENT_KEYBINDINGS@
 clientkeys = awful.util.table.join(
     awful.key({ modkey,           }, "f",
         function (c)
@@ -365,6 +381,7 @@ clientkeys = awful.util.table.join(
         {description = "maximize", group = "client"})
 )
 
+-- @DOC_NUMBER_KEYBINDINGS@
 -- Bind all key numbers to tags.
 -- Be careful: we use keycodes to make it works on any keyboard layout.
 -- This should map on the top row of your keyboard, usually 1 to 9.
@@ -415,6 +432,7 @@ for i = 1, 9 do
     )
 end
 
+-- @DOC_CLIENT_BUTTONS@
 clientbuttons = awful.util.table.join(
     awful.button({ }, 1, function (c) client.focus = c; c:raise() end),
     awful.button({ modkey }, 1, awful.mouse.client.move),
@@ -426,7 +444,9 @@ root.keys(globalkeys)
 
 -- {{{ Rules
 -- Rules to apply to new clients (through the "manage" signal).
+-- @DOC_RULES@
 awful.rules.rules = {
+    -- @DOC_GLOBAL_RULE@
     -- All clients will match this rule.
     { rule = { },
       properties = { border_width = beautiful.border_width,
@@ -440,6 +460,7 @@ awful.rules.rules = {
      }
     },
 
+    -- @DOC_FLOATING_RULE@
     -- Floating clients.
     { rule_any = {
         instance = {
@@ -466,6 +487,7 @@ awful.rules.rules = {
         }
       }, properties = { floating = true }},
 
+    -- @DOC_DIALOG_RULE@
     -- Add titlebars to normal clients and dialogs
     { rule_any = {type = { "normal", "dialog" }
       }, properties = { titlebars_enabled = true }
@@ -479,6 +501,7 @@ awful.rules.rules = {
 
 -- {{{ Signals
 -- Signal function to execute when a new client appears.
+-- @DOC_MANAGE_HOOK@
 client.connect_signal("manage", function (c)
     -- Set the windows at the slave,
     -- i.e. put it at the end of others instead of setting it master.
@@ -492,6 +515,7 @@ client.connect_signal("manage", function (c)
     end
 end)
 
+-- @DOC_TITLEBARS@
 -- Add a titlebar if titlebars_enabled is set to true in the rules.
 client.connect_signal("request::titlebars", function(c)
     -- buttons for the titlebar
@@ -542,6 +566,7 @@ client.connect_signal("mouse::enter", function(c)
     end
 end)
 
+-- @DOC_BORDER@
 client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end)
 client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end)
 -- }}}

docs/05-awesomerc.md.lua

@@ -0,0 +1,241 @@
+local filename, rcfile, new_rcfile = ...
+
+local f = io.open(filename, "w")
+
+f:write[[# Default configuration file documentation
+
+This document explain the default `rc.lua` file provided by Awesome.
+
+]]
+
+-- Document sections of the file to guide new users to the right doc pages
+
+local sections = {}
+
+sections.DOC_REQUIRE_SECTION = [[
+Awesome API is distributed across many libraries (also called modules).
+
+Here is the modules being imported:
+
+<table class='widget_list' border=1>
+  <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
+  <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
+  <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
+  <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
+  <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
+</table>
+
+]]
+
+sections.DOC_ERROR_HANDLING = [[
+Awesome is a window managing framework. It allows its users great (ultimate?)
+flexibility. However, it also allows the user to write invalid code. There is
+multiple "levels" of problems:
+
+ * Syntax: There is an `awesome -k` option available in the command line to
+   check this. Awesome cannot start with an invalid `rc.lua`
+ * Invalid APIs and type errors: Lua is a dynamic language. It doesn't have much
+   support for static/compile time checks. There is the `luacheck` utility to
+   help find some categories of errors. Those errors will cause Awesome to
+   "drop" the current call stack and start over. Note that if the config cannot
+   reach the end of the `rc.lua` without errors, it will fallback to the
+   original file.
+ * Invalid logic: It is possible to write fully valid code that will leave
+   Awesome unusable (like an infinite loop or blocking commands). In that case,
+   the best way to debug this is either using `print()` or using `gdb`. For
+   this, see the [Debugging tips Readme section](../documentation/01-readme.md.html)
+ * Deprecated APIs: Awesome API is not frozen for eternity. While after a
+   decade and recent changes to enforce consistency, it doesn't change as much,
+   it will likely be changed in the future. When possible, changes wont cause
+   errors but will instead print a deprecation message in Awesome logs. Those
+   logs are placed in various places depending on the distribution. By default,
+   Awesome will print this on stderr and stdout.
+
+
+]]
+
+
+sections.DOC_LOAD_THEME = [[
+To create custom themes, the easiest way is to copy the `default` theme folder
+from `/usr/share/awesome/themes/` into `~/.config/awesome` and modify it.
+
+Awesome currently doesn't behave well without a theme containing all the "basic"
+variables such as `bg_normal`. To get a list of all official variables, see
+the [appearance guide](../documentation/06-appearance.md.html).
+]]
+
+
+sections.DOC_DEFAULT_APPLICATIONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_LAYOUT = [[
+ &nbsp;
+]]
+
+
+sections.DOC_MENU = [[
+ &nbsp;
+]]
+
+
+sections.TAGLIST_BUTTON = [[
+ &nbsp;
+]]
+
+
+sections.TASKLIST_BUTTON = [[
+ &nbsp;
+]]
+
+
+sections.DOC_FOR_EACH_SCREEN = [[
+ &nbsp;
+]]
+
+
+sections.DOC_WIBAR = [[
+ &nbsp;
+]]
+
+
+sections.DOC_SETUP_WIDGETS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_ROOT_BUTTONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_GLOBAL_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_CLIENT_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_NUMBER_KEYBINDINGS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_CLIENT_BUTTONS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_RULES = [[
+ &nbsp;
+]]
+
+
+sections.DOC_GLOBAL_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_FLOATING_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_DIALOG_RULE = [[
+ &nbsp;
+]]
+
+
+sections.DOC_MANAGE_HOOK = [[
+ &nbsp;
+]]
+
+
+sections.DOC_TITLEBARS = [[
+ &nbsp;
+]]
+
+
+sections.DOC_BORDER = [[
+ &nbsp;
+]]
+
+-- Ask 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.."\n"
+end
+
+-- Parse the default awesomerc.lua
+
+local rc = io.open(rcfile)
+
+local doc_block = false
+
+local output = {}
+
+for line in rc:lines() do
+    local tag = line:match("@([^@]+)@")
+
+    if not tag then
+        local section = line:match("--[ ]*{{{[ ]*(.*)")
+        if line == "-- }}}" or line == "-- {{{" then
+            -- Hide some noise
+        elseif section then
+            -- Turn Vim sections into markdown sections
+            if doc_block then
+                f:write("\n")
+                doc_block = false
+            end
+            f:write("## "..section.."\n")
+        elseif line:sub(1,2) == "--" then
+            -- Display "top level" comments are normal text.
+            if doc_block then
+                f:write("\n")
+                doc_block = false
+            end
+            f:write(line:sub(3).."\n")
+        else
+            -- Write the code in <code> sections
+            if not doc_block then
+                f:write("\n")
+                doc_block = true
+            end
+            f:write(add_links(line))
+        end
+        table.insert(output, line)
+    else
+        -- Take the documentation found in this file and append it
+        if doc_block then
+            f:write("\n")
+            doc_block = false
+        end
+
+        if sections[tag] then
+            f:write(sections[tag])
+        else
+            f:write(" \n\n")
+        end
+    end
+end
+
+f:write("\n")
+
+f:close()
+
+local rc_lua = io.open(new_rcfile, "w")
+rc_lua:write(table.concat(output, "\n"))
+rc_lua:close()

docs/config.ld

@@ -21,6 +21,7 @@ topics={
     '02-contributing.md',
     '03-declarative-layout.md',
     '04-new-widgets.md',
+    '05-awesomerc.md',
     '06-appearance.md',
     '16-using-cairo.md',
     '90-FAQ.md',