class CTioga2::Commands::Documentation::HTML
Generation of XHTML snippets (not full pages) that document the commands/groups and types known to CTioga2
.
Attributes
The base URL for the file where the backends are documented.
todo maybe this should be turned into a directory, and each file would document a backend on its own ? That would make sense, but that would be rather difficult, I have to admit.
The base URL for file where commands and groups are documented.
The base URL for the file where the types are documented.
Public Class Methods
# File lib/ctioga2/commands/doc/html.rb, line 44 def initialize(doc) @doc = doc @types_url = "types.html" @commands_url = "commands.html" @backends_url = "backends.html" @functions_url = "functions.html" end
Public Instance Methods
Ouputs HTML
code to all backends
# File lib/ctioga2/commands/doc/html.rb, line 207 def write_backends(opts, out = STDOUT) backends = @doc.backends.sort.map { |d| d[1]} write_page_menu(opts, out) do |out| out.puts "<div class='quick-jump'>" out.puts "<h3>Quick jump</h3>" out.puts "<ul>\n" for b in backends out.puts "<li><a href='#backend-#{b.name}'>#{b.name}</a></li>\n" end out.puts "</ul>\n" out.puts "</div>" end write_page(opts, out) do |out| for b in backends out.puts out.puts "<h3 id='backend-#{b.name}' class='backend'><code>#{b.name}</code>: #{b.long_name}</h3>\n" out.puts markup_to_html(b.description) out.puts for param in b.param_list out.puts "<h4 id='backend-#{b.name}-#{param.name}'>Parameter: #{param.name}</h4>" out.puts "<p><code>/#{param.name}=<a href='#{@types_url}#type-#{param.type.name}'>#{param.type.name}</a></code></p>" out.puts markup_to_html(param.description) end end end end
# File lib/ctioga2/commands/doc/html.rb, line 284 def write_color_list(colors, opts, out = STDOUT, color_names = nil) columns = opts["columns"] || 5 cls = opts["class"] || "color-list" div_cls = opts["div-class"] rw = opts["rect-width"] || 80 rh = opts["rect-height"] || 40 div_common = (div_cls ? "class='#{div_cls}' style='" : "style='width:#{rw};height:#{rh};") out.puts "<table class='#{cls}'>" idx = 0 for color in colors if idx % columns == 0 if idx > 0 out.puts "</tr>" end out.puts "<tr>" end if color cls = "##{Utils::color_to_html(color)}" if color_names c = color_names[idx] else c = Utils::color_name_by_value(color) end cb = if c "#{c}<br/>" else "" end out.puts "<td><div #{div_common}background-color: #{cls};color: #{cls};'>#{cb}</div>#{cb}#{cls}</td>" else out.puts "<td>no color</td>" end idx += 1 end out.puts "</tr></table>" end
# File lib/ctioga2/commands/doc/html.rb, line 346 def write_color_sets(opts, out = STDOUT) sets = Graphics::Styles::CurveStyleFactory::parameters['color'].sets set_names = sets.keys.sort if opts['include'] set_names = set_names.select do |x| x =~ opts['include'] end elsif opts['exclude'] set_names = set_names.select do |x| x !~ opts['exclude'] end end set_names = sets.keys.sort for s in set_names out.puts "<h5>Color set: <code>#{s}</code></h5>" colors = sets[s] write_color_list(colors, opts, out) end end
Writes out a list
@todo Split that to just write an ordered list of colors (get their names ?)
# File lib/ctioga2/commands/doc/html.rb, line 334 def write_colors(opts, out = STDOUT) clrs = Tioga::ColorConstants::constants.sort colors = clrs.map do |c| Tioga::ColorConstants::const_get(c) end color_names = clrs.map do |c| c.to_s end write_color_list(colors, opts, out, color_names) end
Write a HTML
table documenting all command-line options.
# File lib/ctioga2/commands/doc/html.rb, line 156 def write_command_line_options(opts, out = STDOUT) cmds, groups = @doc.documented_commands out.puts "<table>" for g in groups out.puts "<tr><th colspan='3'>#{g.name}</th></tr>" commands = cmds[g].sort {|a,b| a.long_option <=> b.long_option } for cmd in commands opts = cmd.option_strings link = "<a href='#{@commands_url}#command-#{cmd.name}'>" out.puts "<tr><td><code>#{link}#{opts[0]}</a></code></td>" out.puts "<td><code>#{link}#{opts[1]}</a></code></td>" out.puts "<td>#{opts[2]}</td></tr>" end end out.puts "</table>" end
Ouputs HTML
code to document all groups and commands
# File lib/ctioga2/commands/doc/html.rb, line 89 def write_commands(opts, out = STDOUT) cmds, groups = @doc.documented_commands if opts['snippets'] require 'yaml' snippets = begin YAML.load(IO.readlines(opts['snippets']).join()) rescue Exception => e Log::error { "Failed to load snippets file '#{opts['snippets']}'\n => #{e.inspect}" } {} end end write_page_menu(opts, out) do |out| out.puts "<div class='quick-jump'>" out.puts "<h3>Quick jump</h3>" out.puts "<ul>\n" for g in groups out.puts "<li><a href='#group-#{g.id}'>#{g.name}</a></li>\n" end out.puts "</ul>\n" out.puts "</div>" end write_page(opts, out) do |out| for g in groups out.puts out.puts "<h3 class='group' id='group-#{g.id}'>#{g.name}</h3>" out.puts markup_to_html(g.description) commands = cmds[g].sort {|a,b| a.name <=> b.name } out.puts "<p>" out.puts "<span class='bold'>Available commands:</span>\n" out.puts commands.map {|c| "<a href='#command-#{c.name}'><code>#{c.name}</code></a>" }.join(' ') out.puts "</p>" for cmd in commands out.puts out.puts command_documentation(cmd) if snippets snpts = snippets[cmd.name] if snpts str = "" for k in snpts.keys.sort s = snpts[k] ln = s[:line].chomp # if ln[-1] == '\\' # ln = ln[0..-2] # end # Strip links from the line ln.gsub!(/<a[^>]+>(.*?)<\/a>/) { || $1 } str += "<pre class='#{s[:cls]}'><a href='#{k}'>#{ln}</a></pre>\n" end out.puts "<h5 id='snippets-h5-#{cmd.name}' onclick='toggleExamples(this);'>Examples...</h5>\n<div id='snippets-#{cmd.name}' class='snippets'>#{str}</div>" end end end end end end
# File lib/ctioga2/commands/doc/html.rb, line 64 def write_functions(opts, out = STDOUT) funcs = @doc.functions names = funcs.keys.sort write_page_menu(opts, out) do |out| out.puts "<div class='quick-jump'>" out.puts "<h3>Quick jump</h3>" out.puts "<ul>\n" for n in names out.puts "<li><a href='#func-#{n}'>#{n}</a></li>\n" end out.puts "</ul>\n" out.puts "</div>" end write_page(opts, out) do |out| for n in names f = funcs[n] out.puts out.puts "<h3 class='function' id='func-#{n}'>#{n} - #{f.short_description}</h3>" out.puts markup_to_html(f.description) end end end
# File lib/ctioga2/commands/doc/html.rb, line 58 def write_page(opts, out) if !opts['page-menu'] or opts['page-menu'] =~ /page|full/i yield out end end
Write a summary list of all style items
# File lib/ctioga2/commands/doc/html.rb, line 238 def write_styles(opts, out = STDOUT) styles = Graphics::Elements::TiogaElement::styled_classes names = styles.keys.sort write_page_menu(opts, out) do |out| out.puts "<div class='quick-jump'>" out.puts "<h3>Quick jump</h3>" out.puts "<ul>\n" for k in names out.puts "<li><a href='#style-#{k}'>#{k}</a></li>\n" end out.puts "</ul>\n" out.puts "</div>" end write_page(opts, out) do |out| for n in names out.puts "<h3 id='style-#{n}' class='style'><code>#{n}</code></h3>\n" cls = styles[n].style_class if cls aliases = cls.defined_aliases out.puts "<ul>\n" opts = cls.options_hash op_names = opts.keys.sort for k in op_names type = opts[k].type extra = if aliases.key? k " (alias for <code>#{cls.normalize_out(aliases[k])}</code>)" else "" end puts "<li><code>#{cls.normalize_out(k)}</code>#{extra}: <a href='#{@types_url}#type-#{type.name}'>#{type.name}</a></li>\n" end out.puts "</ul>\n" else out.puts "No specific style information" end end end end
Ouputs HTML
code to document all types
# File lib/ctioga2/commands/doc/html.rb, line 179 def write_types(opts, out = STDOUT) types = @doc.types.sort.map { |d| d[1]} write_page_menu(opts, out) do |out| out.puts "<div class='quick-jump'>" out.puts "<h3>Quick jump</h3>" out.puts "<ul>\n" for t in types out.puts "<li><a href='#type-#{t.name}'>#{t.name}</a></li>\n" end out.puts "</ul>\n" out.puts "</div>" end write_page(opts, out) do |out| for t in types out.puts out.puts "<h4 id='type-#{t.name}' class='type'>#{t.name}</h4>\n" out.puts markup_to_html(t.description) out.puts # There is no need to wrap the markup # in a paragraph. end end end
Protected Instance Methods
The string that represents a full command
# File lib/ctioga2/commands/doc/html.rb, line 373 def command_documentation(cmd) str = "<h4 class='command' id='command-#{cmd.name}'>Command: <code>#{cmd.name}</code></h4>\n" str << "<p class='synopsis'>\n<span class='bold'>Synopsis (file)</span>\n" str << "</p>\n<pre class='examples-cmdfile'>" str << "<span class='cmd'>#{cmd.name} " str << cmd.arguments.map { |arg| "<a class='argument' href='#{@types_url}#type-#{arg.type.name}'>#{arg.displayed_name}</a>" }.join(' ') if cmd.has_options? if(cmd.arguments.size > 0) str << " " end str << "/option=..." end str << "</span>\n" str << "</pre>\n" # Command-line file synopsis str << "<p class='synopsis'>\n<span class='bold'>Synopsis (command-line)</span>\n" args = cmd.arguments.map { |arg| "<a class='argument' href='#{@types_url}#type-#{arg.type.name}'>#{arg.displayed_name}</a>" }.join(' ') if cmd.has_options? args << " /option=..." end str << "</p>\n<pre class='examples-cmdline'>" if cmd.short_option str << "<span class='cmdline'>-#{cmd.short_option} " str << args str << "</span>\n" end str << "<span class='cmdline'>--#{cmd.long_option} " str << args str << "</span>\n" str << "</pre>" if cmd.has_options? str << "<p class='synopsis'><span class='bold'>Available options</span>:\n" opts = cmd.optional_arguments.sort.map do |k,arg| "<a href='#{@types_url}#type-#{arg.type.name}'><code>#{cmd.normalize_option_name(k)}</code></a>\n" end str << opts.join(' ') str << "</p>" end # Now, the description: str << markup_to_html(cmd.long_description) return str end
Takes up an array of MarkupItem objects and returns its equivalent in HTML
format. Alternativelely, it can take a String
and feed it to MarkedUpText
.
todo escape correctly the produced HTML
codeā¦
# File lib/ctioga2/commands/doc/html.rb, line 428 def markup_to_html(items) if items.is_a? String mup = MarkedUpText.new(@doc, items) return markup_to_html(mup.elements) end str = "" for it in items case it when MarkedUpText::MarkupText el = nil case it.kind when :code el = "code" end if el prefix = "<#{el}>" suffix = "</#{el}>" else prefix = "" suffix = "" end str << "#{prefix}#{it.to_s}#{suffix}" when MarkedUpText::MarkupLink case it.target when Command link = "#{@commands_url}#command-#{it.target.name}" when Function link = "#{@functions_url}#func-#{it.target.name}" when CommandGroup link = "#{@commands_url}#group-#{it.target.id}" when CommandType link = "#{@types_url}#type-#{it.target.name}" when Data::Backends::BackendDescription link = "#{@backends_url}#backend-#{it.target.name}" when String # plain URL target link = "#{it.target}" else raise "The link target should be either a group, a command or a type, but is a #{it.target.class} (#{it.dbg.inspect})" end str << "<a href='#{link}'>#{it.to_s}</a>" when MarkedUpText::MarkupItemize str << "<ul>\n" for x in it.items str << "<li>#{markup_to_html(x)}</li>\n" end str << "</ul>\n" when MarkedUpText::MarkupParagraph str << "<p>\n#{markup_to_html(it.elements)}\n</p>\n" when MarkedUpText::MarkupVerbatim str << "<pre class='#{it.cls}'>#{it.text}</pre>\n" else raise "Markup #{it.class} isn't implemented yet for HTML" end end return str end