ctioga2 0.0

data/lib/ctioga2/commands/doc/doc.rb

@@ -0,0 +1,118 @@
+# doc.rb: a class holding all informations
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/commands/commands'
+require 'ctioga2/commands/doc/markup'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 61 $', '$Date: 2009-05-29 01:00:56 +0200 (Fri, 29 May 2009) $')
+
+  module Commands
+
+    # The base of the 'self-documentation' of CTioga2
+    module Documentation
+
+      # The base class for all documentation.
+      #
+      # TODO: create a class that would parse a description from a
+      # group/command/type and understand some 'markup': lists, links
+      # to other commands/groups/types, and maybe bold or things of
+      # this kind. Then the various outputs should have a means to
+      # parse this.
+      class Doc
+        
+        # The hash containing all the commands, as returned
+        # by Interpreter::commands.
+        attr_accessor :commands
+
+        # The hash containing all the groups, as returned
+        # by Interpreter::commands.
+        attr_accessor :groups
+
+        # The hash containing all the types, as returned
+        # by Interpreter::commands.
+        attr_accessor :types
+
+        # Wether or not to ignore blacklisted commands
+        attr_accessor :ignore_blacklisted
+
+        # The CommandLineHelp object in charge of displaying
+        # information about command-line
+        attr_accessor :command_line_help
+
+
+        # Create a Doc object caring about the current state of
+        # registered commands and such.
+        def initialize
+          @commands = Interpreter::commands
+          @groups = Interpreter::groups
+          @types = Interpreter::types
+
+          @ignore_blacklisted = ! (ENV.key?("CT2_DEV") && 
+                                   ! ENV["CT2_DEV"].empty?)
+
+          @command_line_help = CommandLineHelp.new
+        end
+
+        # Returns a [ cmds, groups ] hash containing the list of
+        # commands, and the groups to be documented.
+        def documented_commands
+          cmds = group_commands
+
+          groups = cmds.keys.sort do |a,b|
+            if ! a
+              1
+            elsif ! b
+              -1
+            else
+              a.priority <=> b.priority
+            end
+          end
+          if @ignore_blacklisted
+            groups.delete_if {|g| g && g.blacklisted }
+          end
+          return [cmds, groups]
+        end
+
+        # Display command-line help.
+        def display_command_line_help
+          @command_line_help.
+            print_commandline_options(*self.documented_commands)
+        end
+
+        protected 
+
+
+        # Groups Command by CommandGroup, _nil_ being a proper value,
+        # and return the corresponding hash.
+        def group_commands
+          ret_val = {}
+          for name, cmd in @commands
+            group = cmd.group
+            if ret_val.key?(group)
+              ret_val[group] << cmd
+            else
+              ret_val[group] = [cmd]
+            end
+          end
+          
+          return ret_val
+        end
+
+      end
+    end
+  end
+end
+

data/lib/ctioga2/commands/doc/documentation-commands.rb

@@ -0,0 +1,119 @@
+# doc.rb: a class holding all informations
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/commands/commands'
+require 'ctioga2/commands/doc/help'
+require 'ctioga2/commands/doc/man'
+require 'ctioga2/commands/doc/html'
+require 'ctioga2/commands/doc/markup'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 77 $', '$Date: 2009-06-05 00:20:49 +0200 (Fri, 05 Jun 2009) $')
+
+  module Commands
+
+    # The base of the 'self-documentation' of CTioga2
+    module Documentation
+
+
+      # Documentation generation
+      DocumentationGenerationGroup = 
+        CmdGroup.new('doc', "Documentation generation",
+                     "Automatic documentation generation.", 
+                     1000, true)
+      
+      
+      # Display help on the command-line
+      WriteManualPage = 
+        Cmd.new("write-manual-page", nil, "--write-man", 
+                [ 
+                 CmdArg.new('text', 'version'),
+                 CmdArg.new('file'),
+                ]) do |plotmaker, version, file|
+        m = Man.new(plotmaker.interpreter.doc)
+        m.write_manual_page(version, file)
+      end
+      
+      WriteManualPage.describe("Writes a manual page based on a template",
+                               <<EOH, DocumentationGenerationGroup)
+Writes a manual page based on a template
+EOH
+
+
+      WriteHTMLCommands = 
+        Cmd.new("write-html-commands", nil, "--write-html-commands", 
+                []) do |plotmaker|
+        html = HTML.new(plotmaker.interpreter.doc)
+        html.write_commands()
+      end
+      
+      WriteHTMLCommands.describe("HTML documentation for group and commands",
+                                 <<EOH, DocumentationGenerationGroup)
+Prints the HTML documentation for group and commands to standard output.
+EOH
+
+      WriteHTMLTypes = 
+        Cmd.new("write-html-types", nil, "--write-html-types", 
+                []) do |plotmaker|
+        html = HTML.new(plotmaker.interpreter.doc)
+        html.write_types()
+      end
+      
+      WriteHTMLTypes.describe("HTML documentation for types",
+                              <<EOH, DocumentationGenerationGroup)
+Prints the HTML documentation for all types.
+EOH
+
+      WriteHTMLCommandLineOptions = 
+        Cmd.new("write-html-commandline", nil, "--write-html-commandline", 
+                []) do |plotmaker|
+        html = HTML.new(plotmaker.interpreter.doc)
+        html.write_command_line_options()
+      end
+      
+      WriteHTMLCommandLineOptions.describe("HTML documentation for types",
+                                           <<EOH, DocumentationGenerationGroup)
+Prints a table summary of command-line options.
+EOH
+
+      DumpCommandMarkup = 
+        Cmd.new("dump-command-markup", nil, "--dump-command-markup", 
+                []) do |plotmaker|
+        markup = Markup.new(plotmaker.interpreter.doc)
+        markup.write_commands()
+      end
+      
+      DumpCommandMarkup.describe("Dump markup for commands and groups",
+                                 <<EOH, DocumentationGenerationGroup)
+Dumps the parsed markup for commands and groups. Used for debugging
+purposes.
+EOH
+
+      DumpTypesMarkup = 
+        Cmd.new("dump-types-markup", nil, "--dump-types-markup", 
+                []) do |plotmaker|
+        markup = Markup.new(plotmaker.interpreter.doc)
+        markup.write_types()
+      end
+      
+      DumpTypesMarkup.describe("Dump markup for types and groups",
+                               <<EOH, DocumentationGenerationGroup)
+Dumps the parsed markup for types and groups. Used for debugging
+purposes.
+EOH
+
+    end
+  end
+end

data/lib/ctioga2/commands/doc/help.rb

@@ -0,0 +1,95 @@
+# help.rb: displaying the documentation of commands
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/commands/commands'
+require 'ctioga2/commands/parsers/command-line'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 34 $', '$Date: 2009-05-03 20:22:29 +0200 (Sun, 03 May 2009) $')
+
+  module Commands
+
+    module Documentation
+
+      # Displays help about command-line options and such.
+      class CommandLineHelp
+
+        # How much space to leave for the options ?
+        attr_accessor :options_column_width
+
+        def initialize
+          @options_column_width = 20
+        end
+
+        # Prints short help text suitable for a --help option about
+        # available commands, by groups (ungrouped last). It takes a
+        # list of all commands (_cmds_) and the list of _groups_ to
+        # display.
+        #
+        # TODO: word splitting.
+        #
+        # TODO: why not try color, too ;-) ???
+        def print_commandline_options(cmds, groups)
+          for group in groups
+            puts unless group == groups[0]
+            name = (group && group.name) || "Ungrouped commands"
+            if group && group.blacklisted 
+              name << " (blacklisted)"
+            end
+            puts name
+            for cmd in cmds[group].sort {|a,b|
+                a.long_option <=> b.long_option
+              }
+
+              strings = cmd.option_strings
+              puts "#{leading_spaces}%2s%1s %-#{@options_column_width}s%s" % 
+                [ 
+                 strings[0], (strings[0] ? "," : " "),
+                 strings[1],
+                 if strings[1].size >= @options_column_width
+                   "\n#{total_leading_spaces}#{strings[2]}"
+                 else
+                   strings[2]
+                 end
+                ]
+              if cmd.has_options?
+                puts "#{total_leading_spaces}  options: %s" %
+                  cmd.optional_arguments.keys.sort.map {|x| "/#{x}"}.join(' ')
+              end
+            end
+          end
+
+        end
+
+        protected
+
+        # Leading spaces to align a string with the other option texts
+        def total_leading_spaces
+          return "#{leading_spaces}#{" " *(@options_column_width + 4)}"
+          # 4: '-o, '
+        end
+
+        # Spaces before any 'short' option appears
+        def leading_spaces
+          return "    "
+        end
+        
+      end
+
+    end
+
+  end
+
+end

data/lib/ctioga2/commands/doc/html.rb

@@ -0,0 +1,230 @@
+# html.rb: html output for internal documentation
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/commands/commands'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 77 $', '$Date: 2009-06-05 00:20:49 +0200 (Fri, 05 Jun 2009) $')
+
+  module Commands
+
+    module Documentation
+
+      # Generation of XHTML snippets (not full pages) that document
+      # the commands/groups and types known to CTioga2.
+      class HTML
+        
+        # The Doc object the HTML class should document
+        attr_accessor :doc
+
+        # The base URL for file where types are documented.
+        attr_accessor :types_url
+
+        # The base URL for file where commands and groups are
+        # documented.
+        attr_accessor :commands_url
+
+        def initialize(doc)
+          @doc = doc
+          @types_url = "types.html"
+          @commands_url = "commands.html"
+        end
+
+        # Ouputs HTML code to document all groups and commands 
+        def write_commands(out = STDOUT)
+          cmds, groups = @doc.documented_commands
+
+          out.puts "<div class='quick-jump'>"
+          out.puts "Quick jump to a specific group of commands:\n"
+          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>"
+          
+          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)
+            end
+          end
+        end
+
+        # Write a HTML table documenting all command-line options.
+        def write_command_line_options(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 types
+        def write_types(out = STDOUT)
+          types = @doc.types.sort.map { |d| d[1]}
+
+
+          out.puts "<div class='quick-jump'>"
+          out.puts "Quick jump to a specific type:\n"
+          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>"
+ 
+          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
+        
+
+        protected
+
+        # The string that represents a full command
+        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.upcase}</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>#{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...
+        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
+              str << it.to_s
+            when MarkedUpText::MarkupLink
+              case it.target
+              when Command
+                link = "#{@commands_url}#command-#{it.target.name}"
+              when CommandGroup
+                link = "#{@commands_url}#group-#{it.target.id}"
+              when CommandType
+                link = "#{@types_url}#type-#{it.target.name}"
+              else
+                raise "The link target should be either a group, a command or a type, but is a #{it.target.class}"
+              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
+
+        
+      end
+
+    end
+  end
+end