Add option to show a project icon (Issue #307, PR #315)

doc/doc.md

@@ -1199,6 +1199,7 @@ template. In `config.ld` they may also be `true`, meaning use the same directory
 configuration file.
   - `merge` allow documentation from different files to be merged into modules without
 explicit **@submodule** tag
+  - `icon` an image that will be displayed under the project name on all pages
 
 _These only appear in the configuration file:_
 

ldoc.lua

@@ -74,6 +74,7 @@ ldoc, a documentation generator for Lua, v]]..version..[[
     --tags		(default none) show all references to given tags, comma-separated
     --fatalwarnings	non-zero exit status on any warning
     --testing		reproducible build; no date or version on output
+    --icon		(default none) an image that will be displayed under the project name on all pages
 
   <file> (string) source file or directory containing source
 
@@ -241,7 +242,7 @@ end
 
 local ldoc_contents = {
    'alias','add_language_extension','custom_tags','new_type','add_section', 'tparam_alias',
-   'file','project','title','package','format','output','dir','ext', 'topics',
+   'file','project','title','package', 'icon','format','output','dir','ext', 'topics',
    'one','style','template','description','examples', 'pretty', 'charset', 'plain',
    'readme','all','manual_url', 'ignore', 'colon', 'sort', 'module_file','vars',
    'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape','merge_error_groups',
@@ -818,12 +819,16 @@ if builtin_style or builtin_template then
    end
 end
 
+-- default icon to nil
+if args.icon == 'none' then args.icon = nil end
+
 ldoc.log = print
 ldoc.kinds = project
 ldoc.modules = module_list
 ldoc.title = ldoc.title or args.title
 ldoc.project = ldoc.project or args.project
 ldoc.package = args.package:match '%a+' and args.package or nil
+ldoc.icon = ldoc.icon or args.icon
 
 local source_date_epoch = os.getenv("SOURCE_DATE_EPOCH")
 if args.testing then

ldoc/html.lua

@@ -323,6 +323,18 @@ function ldoc.source_ref (fun)
 
    check_directory(args.dir) -- make sure output directory is ok
 
+   -- project icon
+   if ldoc.icon then
+      local dir_data = args.dir .. '/data'
+      if not path.isdir(dir_data) then
+          -- luacheck: push ignore lfs
+          lfs.mkdir(dir_data)
+          -- luacheck: pop
+      end
+      local file = require 'pl.file'
+      file.copy(ldoc.icon, dir_data)
+   end
+
    args.dir = args.dir .. path.sep
 
    if css then -- has CSS been copied?

ldoc/html/ldoc_ltp.lua

@@ -36,6 +36,14 @@ return [==[
 <br/>
 <h1>$(ldoc.project)</h1>
 
+# if ldoc.icon then
+#   if module then
+<img src="../data/$(ldoc.icon)" />
+#   else
+<img src="data/$(ldoc.icon)" />
+#   end
+# end
+
 # if not ldoc.single and module then -- reference back to project index
 <ul>
   <li><a href="../$(ldoc.output).html">Index</a></li>