revamping docs; kind sort order in documents

docs/doc.md

@@ -2,7 +2,7 @@
 
 LDoc is a second-generation documentation tool that can be used as a replacement for [LuaDoc](http://keplerproject.github.com/luadoc/). It arose out of my need to document my own projects and only depends on the [Penlight](https://github.com/stevedonovan/Penlight) libraries.
 
-It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed. For instance, it is not so married to the idea that Lua modules should be defined using the `module()` function; this is not only a matter of taste since `module` is deprecated in Lua 5.2.
+It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed. For instance, it is not so married to the idea that Lua modules should be defined using the `module` function; this is not only a matter of taste since this has been deprecated in Lua 5.2.
 
 Otherwise, the output is very similar, which is no accident since the HTML templates are based directly on LuaDoc. You can ship your own customized templates and style sheets with your project, however. You have an option to use Markdown to process the documentation, which means no ugly HTML is needed in doc comments.  C/C++ extension modules may be documented in a similar way, although naturally less can be inferred from the code itself.
 

ldoc/html.lua

@@ -128,29 +128,38 @@ function html.generate_output(ldoc, args, project)
    -- write out the module index
    writefile(args.dir..args.output..args.ext,out)
 
-   -- write out the per-module documentation
    -- in single mode, we exclude any modules since the module has been done;
    -- this step is then only for putting out any examples or topics
-   ldoc.css = '../'..css
+   local mods = List()
    for kind, modules in project() do
-      kind = kind:lower()
-      if not ldoc.single or ldoc.single and kind ~= 'modules' then
-         check_directory(args.dir..kind)
-         for m in modules() do
-            ldoc.module = m
-            ldoc.body = m.body
-            if ldoc.body and m.postprocess then
-               ldoc.body = m.postprocess(ldoc.body)
-            end
-            out,err = template.substitute(module_template,{
-               module=m,
-               ldoc = ldoc
-            })
-            if not out then
-               quit('template failed for '..m.name..': '..err)
-            else
-               writefile(args.dir..kind..'/'..m.name..args.ext,out)
-            end
+      local lkind = kind:lower()
+      if not ldoc.single or ldoc.single and lkind ~= 'modules' then
+         mods:append {kind, lkind, modules}
+      end
+   end
+
+   -- write out the per-module documentation
+   -- note that we reset the internal ordering of the 'kinds' so that
+   -- e.g. when reading a topic the other Topics will be listed first.
+   ldoc.css = '../'..css
+   for m in mods:iter() do
+      local kind, lkind, modules = unpack(m)
+      check_directory(args.dir..lkind)
+      project:put_kind_first(kind)
+      for m in modules() do
+         ldoc.module = m
+         ldoc.body = m.body
+         if ldoc.body and m.postprocess then
+            ldoc.body = m.postprocess(ldoc.body)
+         end
+         out,err = template.substitute(module_template,{
+            module=m,
+            ldoc = ldoc
+         })
+         if not out then
+            quit('template failed for '..m.name..': '..err)
+         else
+            writefile(args.dir..lkind..'/'..m.name..args.ext,out)
          end
       end
    end
@@ -158,3 +167,4 @@ function html.generate_output(ldoc, args, project)
 end
 
 return html
+