← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/ctioga2/oneiric

« back to all changes in this revision

Viewing changes to lib/ctioga2/commands/doc/html.rb

  • Committer: Bazaar Package Importer
  • Author(s): Vincent Fourmond
  • Date: 2011-01-24 21:36:06 UTC
  • Revision ID: james.westby@ubuntu.com-20110124213606-9ettx0ugl83z0bzp
Tags: upstream-0.1
Import upstream version 0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ctioga2/commands/doc/html.rb
 
1
# html.rb: html output for internal documentation
 
2
# copyright (c) 2009 by Vincent Fourmond
 
3
  
 
4
# This program is free software; you can redistribute it and/or modify
 
5
# it under the terms of the GNU General Public License as published by
 
6
# the Free Software Foundation; either version 2 of the License, or
 
7
# (at your option) any later version.
 
8
  
 
9
# This program is distributed in the hope that it will be useful, but
 
10
# WITHOUT ANY WARRANTY; without even the implied warranty of
 
11
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
12
# General Public License for more details (in the COPYING file).
 
13
 
 
14
require 'ctioga2/utils'
 
15
require 'ctioga2/commands/commands'
 
16
 
 
17
module CTioga2
 
18
 
 
19
  Version::register_svn_info('$Revision: 216 $', '$Date: 2010-12-31 16:18:17 +0100 (Fri, 31 Dec 2010) $')
 
20
 
 
21
  module Commands
 
22
 
 
23
    module Documentation
 
24
 
 
25
      # Generation of XHTML snippets (not full pages) that document
 
26
      # the commands/groups and types known to CTioga2.
 
27
      class HTML
 
28
        
 
29
        # The Doc object the HTML class should document
 
30
        attr_accessor :doc
 
31
 
 
32
        # The base URL for the file where the types are documented.
 
33
        attr_accessor :types_url
 
34
 
 
35
        # The base URL for the file where the backends are documented.
 
36
        #
 
37
        # \todo maybe this should be turned into a directory, and each
 
38
        # file would document a backend on its own ? That would make
 
39
        # sense, but that would be rather difficult, I have to admit.
 
40
        attr_accessor :backends_url
 
41
 
 
42
        # The base URL for file where commands and groups are
 
43
        # documented.
 
44
        attr_accessor :commands_url
 
45
 
 
46
        def initialize(doc)
 
47
          @doc = doc
 
48
          @types_url = "types.html"
 
49
          @commands_url = "commands.html"
 
50
          @backends_url = "backends.html"
 
51
        end
 
52
 
 
53
        # Ouputs HTML code to document all groups and commands 
 
54
        def write_commands(out = STDOUT)
 
55
          cmds, groups = @doc.documented_commands
 
56
 
 
57
          out.puts "<div class='quick-jump'>"
 
58
          out.puts "Quick jump to a specific group of commands:\n"
 
59
          out.puts "<ul>\n"
 
60
          for g in groups
 
61
            out.puts "<li><a href='#group-#{g.id}'>#{g.name}</a></li>\n"
 
62
          end
 
63
          out.puts "</ul>\n"
 
64
          out.puts "</div>"
 
65
          
 
66
          for g in groups
 
67
            out.puts 
 
68
            out.puts "<h3 class='group' id='group-#{g.id}'>#{g.name}</h3>"
 
69
            out.puts markup_to_html(g.description)
 
70
 
 
71
            commands = cmds[g].sort {|a,b|
 
72
              a.name <=> b.name
 
73
            }
 
74
            
 
75
            out.puts "<p>"
 
76
            out.puts "<span class='bold'>Available commands:</span>\n"
 
77
            out.puts commands.map {|c|
 
78
              "<a href='#command-#{c.name}'><code>#{c.name}</code></a>"
 
79
            }.join(' ')
 
80
            out.puts "</p>"
 
81
 
 
82
            for cmd in commands
 
83
              out.puts
 
84
              out.puts command_documentation(cmd)
 
85
            end
 
86
          end
 
87
        end
 
88
 
 
89
        # Write a HTML table documenting all command-line options.
 
90
        def write_command_line_options(out = STDOUT)
 
91
          cmds, groups = @doc.documented_commands
 
92
 
 
93
          out.puts "<table>"
 
94
          for g in groups
 
95
            out.puts "<tr><th colspan='3'>#{g.name}</th></tr>"
 
96
            commands = cmds[g].sort {|a,b|
 
97
              a.long_option <=> b.long_option
 
98
            }
 
99
            for cmd in commands
 
100
              opts = cmd.option_strings
 
101
              link = "<a href='#{@commands_url}#command-#{cmd.name}'>"
 
102
              out.puts "<tr><td><code>#{link}#{opts[0]}</a></code></td>"
 
103
              out.puts "<td><code>#{link}#{opts[1]}</a></code></td>"
 
104
              out.puts "<td>#{opts[2]}</td></tr>"
 
105
            end
 
106
          end
 
107
          out.puts "</table>"
 
108
 
 
109
        end
 
110
 
 
111
 
 
112
        # Ouputs HTML code to document all types
 
113
        def write_types(out = STDOUT)
 
114
          types = @doc.types.sort.map { |d| d[1]}
 
115
 
 
116
 
 
117
          out.puts "<div class='quick-jump'>"
 
118
          out.puts "Quick jump to a specific type:\n"
 
119
          out.puts "<ul>\n"
 
120
          for t in types
 
121
            out.puts "<li><a href='#type-#{t.name}'>#{t.name}</a></li>\n"
 
122
          end
 
123
          out.puts "</ul>\n"
 
124
          out.puts "</div>"
 
125
 
 
126
          for t in types
 
127
            out.puts
 
128
            out.puts "<h4 id='type-#{t.name}' class='type'>#{t.name}</h4>\n"
 
129
            out.puts markup_to_html(t.description)
 
130
            out.puts            # There is no need to wrap the markup
 
131
            # in a paragraph.
 
132
          end
 
133
        end
 
134
        
 
135
 
 
136
        # Ouputs HTML code to all backends
 
137
        def write_backends(out = STDOUT)
 
138
          backends = @doc.backends.sort.map { |d| d[1]}
 
139
 
 
140
 
 
141
          out.puts "<div class='quick-jump'>"
 
142
          out.puts "Quick jump to a specific backend:\n"
 
143
          out.puts "<ul>\n"
 
144
          for b in backends
 
145
            out.puts "<li><a href='#backend-#{b.name}'>#{b.name}</a></li>\n"
 
146
          end
 
147
          out.puts "</ul>\n"
 
148
          out.puts "</div>"
 
149
 
 
150
          for b in backends
 
151
            out.puts
 
152
            out.puts "<h3 id='backend-#{b.name}' class='backend'><code>#{b.name}</code>: #{b.long_name}</h3>\n"
 
153
            out.puts markup_to_html(b.description)
 
154
            out.puts
 
155
            for param in b.param_list
 
156
              out.puts "<h4 id='backend-#{b.name}-#{param.name}'>Parameter: #{param.name}</h4>"
 
157
              out.puts "<p><code>/#{param.name}=<a href='#{@types_url}#type-#{param.type.name}'>#{param.type.name}</a></p>"
 
158
              out.puts markup_to_html(param.description)
 
159
            end
 
160
          end
 
161
        end
 
162
        
 
163
 
 
164
        protected
 
165
 
 
166
        # The string that represents a full command
 
167
        def command_documentation(cmd)
 
168
          str = "<h4 class='command' id='command-#{cmd.name}'>Command: <code>#{cmd.name}</code></h4>\n"
 
169
          str << "<p class='synopsis'>\n<span class='bold'>Synopsis (file)</span>\n"
 
170
 
 
171
          str << "</p>\n<pre class='examples-cmdfile'>"
 
172
          str << "<span class='cmd'>#{cmd.name}("
 
173
          str << cmd.arguments.map { |arg|
 
174
            "<a class='argument' href='#{@types_url}#type-#{arg.type.name}'>#{arg.displayed_name}</a>"
 
175
          }.join(',')
 
176
          if cmd.has_options?
 
177
            if(cmd.arguments.size > 0)
 
178
              str << ", "
 
179
            end
 
180
            str << "option=..."
 
181
          end
 
182
          str << ")</span>\n"
 
183
          str << "</pre>\n"
 
184
 
 
185
          # Command-line file synopsis
 
186
          str << "<p class='synopsis'>\n<span class='bold'>Synopsis  (command-line)</span>\n"
 
187
          args = cmd.arguments.map { |arg|
 
188
            "<a class='argument' href='#{@types_url}#type-#{arg.type.name}'>#{arg.displayed_name.upcase}</a>"
 
189
          }.join(' ')
 
190
          if cmd.has_options?
 
191
            args << " /option=..."
 
192
          end
 
193
          str << "</p>\n<pre class='examples-cmdline'>"
 
194
          if cmd.short_option
 
195
            str << "<span class='cmdline'>-#{cmd.short_option} "
 
196
            str << args
 
197
            str << "</span>\n"
 
198
          end
 
199
          str << "<span class='cmdline'>--#{cmd.long_option} "
 
200
          str << args
 
201
          str << "</span>\n"
 
202
          str << "</pre>"
 
203
          
 
204
          if cmd.has_options?
 
205
            str << "<p class='synopsis'><span class='bold'>Available options</span>:\n"
 
206
            opts = cmd.optional_arguments.sort.map do |k,arg|
 
207
              "<a href='#{@types_url}#type-#{arg.type.name}'><code>#{k}</code></a>\n"
 
208
            end
 
209
            str << opts.join(' ')
 
210
            str << "</p>"
 
211
          end
 
212
          # Now, the description:
 
213
          str << markup_to_html(cmd.long_description)
 
214
          return str
 
215
        end
 
216
 
 
217
        # Takes up an array of MarkupItem objects and returns its
 
218
        # equivalent in HTML format. Alternativelely, it can take a
 
219
        # String and feed it to MarkedUpText.
 
220
        #
 
221
        # \todo escape correctly the produced HTML code...
 
222
        def markup_to_html(items)
 
223
          if items.is_a? String 
 
224
            mup = MarkedUpText.new(@doc, items)
 
225
            return markup_to_html(mup.elements)
 
226
          end
 
227
          str = ""
 
228
          for it in items
 
229
            case it
 
230
            when MarkedUpText::MarkupText
 
231
              el = nil
 
232
              case it.kind
 
233
              when :code
 
234
                el = "code"
 
235
              end
 
236
              if el
 
237
                prefix = "<#{el}>"
 
238
                suffix = "</#{el}>"
 
239
              else
 
240
                prefix = ""
 
241
                suffix = ""
 
242
              end
 
243
              str << "#{prefix}#{it.to_s}#{suffix}"
 
244
            when MarkedUpText::MarkupLink
 
245
              case it.target
 
246
              when Command
 
247
                link = "#{@commands_url}#command-#{it.target.name}"
 
248
              when CommandGroup
 
249
                link = "#{@commands_url}#group-#{it.target.id}"
 
250
              when CommandType
 
251
                link = "#{@types_url}#type-#{it.target.name}"
 
252
              when Data::Backends::BackendDescription
 
253
                link = "#{@backends_url}#backend-#{it.target.name}"
 
254
              when String       # plain URL target
 
255
                link = "#{it.target}"
 
256
              else
 
257
                raise "The link target should be either a group, a command or a type, but is a #{it.target.class}"
 
258
              end
 
259
              str << "<a href='#{link}'>#{it.to_s}</a>"
 
260
            when MarkedUpText::MarkupItemize
 
261
              str << "<ul>\n"
 
262
              for x in it.items
 
263
                str << "<li>#{markup_to_html(x)}</li>\n"
 
264
              end
 
265
              str << "</ul>\n"
 
266
            when MarkedUpText::MarkupParagraph
 
267
              str << "<p>\n#{markup_to_html(it.elements)}\n</p>\n"
 
268
            when MarkedUpText::MarkupVerbatim
 
269
              str << "<pre class='#{it.cls}'>#{it.text}</pre>\n"
 
270
            else
 
271
              raise "Markup #{it.class} isn't implemented yet for HTML"
 
272
            end
 
273
          end
 
274
          return str
 
275
        end
 
276
 
 
277
        
 
278
      end
 
279
 
 
280
    end
 
281
  end
 
282
end