Adding UML sequence diagrams and embedded images into the generated HTML

change.txt

@@ -0,0 +1,175 @@
+diff --git a/ldoc/parse.lua b/ldoc/parse.lua
+index 5bebc3a..28102f1 100644
+--- a/ldoc/parse.lua
++++ b/ldoc/parse.lua
+@@ -6,6 +6,21 @@ local tools = require 'ldoc.tools'
+ local doc = require 'ldoc.doc'
+ local Item,File = doc.Item,doc.File
+
++-- This functionality is only needed for UML support.
++-- If this does not load it will only trigger a failure
++-- if the UML syntax was detected.
++local bOk, http   = pcall( require, "socket.http")
++local mime        = nil
++if bOk == false then
++   http = nil
++else
++   bOk, mime   = pcall( require, "mime")
++   if bOk == false then
++      mime = nil
++   end
++end
++
++
+ ------ Parsing the Source --------------
+ -- This uses the lexer from PL, but it should be possible to use Peter Odding's
+ -- excellent Lpeg based lexer instead.
+@@ -46,6 +61,138 @@ function parse_tags(text)
+    return preamble,tag_items
+ end
+
++-- Used to preprocess the tag text prior to extracting
++-- tags.  This allows us to replace tags with other text.
++-- For example, we embed images into the document.
++local function preprocess_tag_strings( s )
++
++   local function create_embedded_image( filename, fileType )
++
++      local html = ""
++
++      if mime == nil then
++         local errStr = "LDoc error, Lua socket/mime module needed for UML"
++         -- Just log the error in the doc
++         html = "<b><u>"..errStr.."</u></b>"
++         print(errStr)
++         return html
++      end
++
++      if fileType == nil then
++         fileType = "png"
++      end
++
++      -- Now open the new image file and embed it
++      -- into the text as an HTML image
++      local fp = io.open( filename, "r" )
++      if fp then
++         -- This could be more efficient instead of
++         -- reading all since the definitions are
++         -- typically small this will work for now
++         local img = fp:read("*all")
++         fp:close()
++
++         html = string.format( '<img src="data:image/%s;base64,%s" />', fileType, mime.b64( img ) )
++      else
++         local errStr = string.format("LDoc error opening %s image file: %q", fileType, filename)
++         -- Just log the error in the doc
++         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
++         print(errStr)
++      end
++
++      return html
++   end
++
++   ----------------------------------------------------------
++   -- Embedded UML
++   ------------------
++   local epos
++   local execPath = "plantuml %s"
++   local spos     = string.find(s, "@startuml")
++   if spos then
++      _, epos = string.find(s, "@enduml")
++   end
++
++   if spos and epos then
++
++      local filename = os.tmpname()
++      local sUml     = string.sub(s,spos,epos) -- UML definition text
++
++      -- Grab the text before and after the UML definition
++      local preStr   = string.match(s, "(.*)@startuml")
++      local postStr  = string.match(s, "@enduml(.*)")
++      local fileType = "png"
++      local fp       = io.open( filename, "w" )
++      local html     = ""
++
++      --Add support for optional formatting in a json format
++      if string.sub( sUml, 10,10 ) == "{" then
++         local sFmt = string.match( sUml, ".*{(.*)}" )
++
++         -- Remove the formatter
++         sUml = string.gsub( sUml, ".*}", "@startuml" )
++
++         -- To avoid adding the dependency of JSON we will
++         -- parse what we need.
++
++         -- "exec":"path"
++         -- This allows you to alter the UML generation engine and path for execution
++         execPath = string.match(sFmt, '.-"exec"%s-:%s-"(.*)".-') or execPath
++
++         -- "removeTags":true
++         -- if true, the @startuml and @enduml are removed, this
++         -- makes it possible to support other UML parsers.
++         sRemoveTags = string.match(sFmt, '.-"removeTags"%s-:%s-(%a*).-')
++         if sRemoveTags == "true" then
++            sUml = string.gsub( sUml, "^%s*@startuml", "" )
++            sUml = string.gsub( sUml, "@enduml%s*$", "" )
++         end
++
++         -- "fileType":"gif"
++         -- This defines a different file type that is generated by
++         -- the UML parsers.
++         fileType = string.match(sFmt, '.-"fileType"%s-:%s-"(.*)".-') or fileType
++      end
++
++      if fp then
++         -- write the UML text to a file
++         fp:write( sUml )
++         fp:close()
++
++         -- create the diagram, overwrites the existing file
++         os.execute( string.format(execPath, filename ) )
++
++         -- create the embedded text for the image
++         html = create_embedded_image( filename, fileType )
++
++         os.remove( filename ) -- this is the PNG from plantUml
++      else
++         local errStr = "LDoc error creating UML temp file"
++         -- Just log the error in the doc
++         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
++         print(errStr)
++      end
++      s = preStr..html..postStr
++
++   end -- embed UML
++
++   ----------------------------------------------------------
++   -- Embedded Image
++   ------------------
++   local fileType, filename = string.match(s, '@embed_(.*){"(.*)"}')
++   if fileType and filename then
++
++      -- create the embedded text for the image
++      html = create_embedded_image( filename, fileType )
++
++      s = string.gsub(s, "@embed_.*{.*}", html)
++
++   end -- embedded image
++
++   return s
++
++end -- preprocess_tag_strings
++
+ -- This takes the collected comment block, and uses the docstyle to
+ -- extract tags and values.  Assume that the summary ends in a period or a question
+ -- mark, and everything else in the preamble is the description.
+@@ -53,6 +200,9 @@ end
+ -- Alias substitution and @TYPE NAME shortcutting is handled by Item.check_tag
+ local function extract_tags (s)
+    if s:match '^%s*$' then return {} end
++
++   s = preprocess_tag_strings( s )
++
+    local preamble,tag_items = parse_tags(s)
+    local strip = tools.strip
+    local summary, description = preamble:match('^(.-[%.?])(%s.+)')

doc/doc.md

@@ -451,6 +451,57 @@ a current limitation is that the master module must be processed before the subm
 
 See the `tests/submodule` example for how this works in practice.
 
+## Embedding Images in the Document
+
+LDoc supports the ability of embedding various images within the generated document--not just a simple reference.  Within a LDoc section use the following syntax:
+
+`@embed{"filename"}`
+
+
+NOTE: The filename must contain the a file extension that matches the file type.  For example, ".png" for a PNG file format.
+
+
+## Embed UML Diagrams in the Document
+
+LDoc supports the ability to define UML diagrams using a textual format and create graphical UML files that can be cached or embedded in the generated document itself.  The current LDoc mainly supports the [plantUML](http://plantuml.sourceforge.net/) textual format.  The syntax is however flexible enough to support other UML textual formats/generation.  The syntax is:
+
+    --- a simple example.
+    -- @startuml
+    -- a->b : sample request
+    -- a<-b : sample response
+    -- @enduml
+
+The `@startuml` also supports various parameters that allow you to customize where and how the UML is generated.  The parameters follow the `@startuml` in a JSON format.  The supported options are:
+
+### "exec":"path/filename"
+This allows you to alter the UML generation engine and path for execution. You can specify a different path/executable and options for the UML parser. For example,
+
+`"exec":"/usr/bin/msvc %s"`
+
+NOTE: The "%s" is where the temp [file] UML text will be placed. The default is "plantuml %s".
+
+### "removeTags":true
+If true (no quotes), the @startuml and @enduml are removed prior to sending to the parser.  This option makes it possible to support other UML parsers that do not use these tags. The default is false.
+
+### "fileType":"gif"
+This defines a different file type that is generated by the UML parsers. This does not alter what if generated, but it tells LDoc what to expect out of the parser.  The default is "png", but you can specify a "gif" (for example) if the UML parser generates a gif.
+
+### "cacheFile":"path/filename"
+This allows you to define a location where you want to cache a local copy of the image.  This results in the file being created at this location and by default it is NOT embedded in the generated diagram.  You can still keep a cached copy and embed the image by using "forceEmbed".
+
+### "forceEmbed":true
+If true this overrides the cacheFile options default for not embedding the image.  This means that when using "cacheFile" and "forceEmbed" a file is cached AND embedded.
+
+    --- Cache the file AND embed the file in the generated document.
+    -- @startuml{"cacheFile":"/path/to/cachedFile.png","forceEmbed":true}
+    -- a1->b1:test request
+    -- a1<-b1:test response
+    -- @enduml
+
+### "showSyntax":"left"|"right"|"above"|"below"|"none"[default] 
+By using this option you can specify that you also want the syntax to be shown: "left"|"right"|"above"|"below".  "none" is the same as not specifying this option.
+
+
 ## Differences from LuaDoc
 
 LDoc only does 'module' documentation, so the idea of 'files' is redundant.

ldoc/html/ldoc_ltp.lua

@@ -265,7 +265,6 @@ return [==[
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.0</a></i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>