iownbey-rdoc 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. data/History.txt +13 -0
  2. data/Manifest.txt +61 -0
  3. data/README.txt +34 -0
  4. data/bin/rdoc +22 -0
  5. data/bin/ri +6 -0
  6. data/lib/rdoc.rb +277 -0
  7. data/lib/rdoc/code_objects.rb +776 -0
  8. data/lib/rdoc/diagram.rb +338 -0
  9. data/lib/rdoc/dot.rb +249 -0
  10. data/lib/rdoc/generator.rb +1050 -0
  11. data/lib/rdoc/generator/chm.rb +113 -0
  12. data/lib/rdoc/generator/chm/chm.rb +98 -0
  13. data/lib/rdoc/generator/html.rb +370 -0
  14. data/lib/rdoc/generator/html/hefss.rb +414 -0
  15. data/lib/rdoc/generator/html/html.rb +704 -0
  16. data/lib/rdoc/generator/html/kilmer.rb +418 -0
  17. data/lib/rdoc/generator/html/one_page_html.rb +121 -0
  18. data/lib/rdoc/generator/ri.rb +229 -0
  19. data/lib/rdoc/generator/texinfo.rb +84 -0
  20. data/lib/rdoc/generator/texinfo/class.texinfo.erb +44 -0
  21. data/lib/rdoc/generator/texinfo/file.texinfo.erb +6 -0
  22. data/lib/rdoc/generator/texinfo/method.texinfo.erb +6 -0
  23. data/lib/rdoc/generator/texinfo/texinfo.erb +28 -0
  24. data/lib/rdoc/generator/xml.rb +120 -0
  25. data/lib/rdoc/generator/xml/rdf.rb +113 -0
  26. data/lib/rdoc/generator/xml/xml.rb +111 -0
  27. data/lib/rdoc/markup.rb +473 -0
  28. data/lib/rdoc/markup/attribute_manager.rb +274 -0
  29. data/lib/rdoc/markup/formatter.rb +14 -0
  30. data/lib/rdoc/markup/fragments.rb +337 -0
  31. data/lib/rdoc/markup/inline.rb +101 -0
  32. data/lib/rdoc/markup/lines.rb +152 -0
  33. data/lib/rdoc/markup/preprocess.rb +71 -0
  34. data/lib/rdoc/markup/to_flow.rb +185 -0
  35. data/lib/rdoc/markup/to_html.rb +354 -0
  36. data/lib/rdoc/markup/to_html_crossref.rb +86 -0
  37. data/lib/rdoc/markup/to_latex.rb +328 -0
  38. data/lib/rdoc/markup/to_test.rb +50 -0
  39. data/lib/rdoc/markup/to_texinfo.rb +69 -0
  40. data/lib/rdoc/options.rb +621 -0
  41. data/lib/rdoc/parsers/parse_c.rb +775 -0
  42. data/lib/rdoc/parsers/parse_f95.rb +1841 -0
  43. data/lib/rdoc/parsers/parse_rb.rb +2584 -0
  44. data/lib/rdoc/parsers/parse_simple.rb +40 -0
  45. data/lib/rdoc/parsers/parserfactory.rb +99 -0
  46. data/lib/rdoc/rdoc.rb +277 -0
  47. data/lib/rdoc/ri.rb +4 -0
  48. data/lib/rdoc/ri/cache.rb +188 -0
  49. data/lib/rdoc/ri/descriptions.rb +150 -0
  50. data/lib/rdoc/ri/display.rb +274 -0
  51. data/lib/rdoc/ri/driver.rb +452 -0
  52. data/lib/rdoc/ri/formatter.rb +616 -0
  53. data/lib/rdoc/ri/paths.rb +102 -0
  54. data/lib/rdoc/ri/reader.rb +106 -0
  55. data/lib/rdoc/ri/util.rb +81 -0
  56. data/lib/rdoc/ri/writer.rb +68 -0
  57. data/lib/rdoc/stats.rb +25 -0
  58. data/lib/rdoc/template.rb +64 -0
  59. data/lib/rdoc/tokenstream.rb +33 -0
  60. data/test/test_rdoc_c_parser.rb +261 -0
  61. data/test/test_rdoc_info_formatting.rb +179 -0
  62. data/test/test_rdoc_info_sections.rb +93 -0
  63. data/test/test_rdoc_markup.rb +613 -0
  64. data/test/test_rdoc_markup_attribute_manager.rb +224 -0
  65. data/test/test_rdoc_ri_attribute_formatter.rb +42 -0
  66. data/test/test_rdoc_ri_default_display.rb +295 -0
  67. data/test/test_rdoc_ri_formatter.rb +318 -0
  68. data/test/test_rdoc_ri_overstrike_formatter.rb +69 -0
  69. metadata +142 -0
@@ -0,0 +1,229 @@
1
+ require 'rdoc/generator'
2
+ require 'rdoc/markup/to_flow'
3
+
4
+ require 'rdoc/ri/cache'
5
+ require 'rdoc/ri/reader'
6
+ require 'rdoc/ri/writer'
7
+ require 'rdoc/ri/descriptions'
8
+
9
+ class RDoc::Generator::RI
10
+
11
+ ##
12
+ # Generator may need to return specific subclasses depending on the
13
+ # options they are passed. Because of this we create them using a factory
14
+
15
+ def self.for(options)
16
+ new(options)
17
+ end
18
+
19
+ class << self
20
+ protected :new
21
+ end
22
+
23
+ ##
24
+ # Set up a new RDoc::Generator::RI.
25
+
26
+ def initialize(options) #:not-new:
27
+ @options = options
28
+ @ri_writer = RDoc::RI::Writer.new "."
29
+ @markup = RDoc::Markup.new
30
+ @to_flow = RDoc::Markup::ToFlow.new
31
+
32
+ @generated = {}
33
+ end
34
+
35
+ ##
36
+ # Build the initial indices and output objects based on an array of
37
+ # TopLevel objects containing the extracted information.
38
+
39
+ def generate(toplevels)
40
+ RDoc::TopLevel.all_classes_and_modules.each do |cls|
41
+ process_class cls
42
+ end
43
+ end
44
+
45
+ def process_class(from_class)
46
+ generate_class_info(from_class)
47
+
48
+ # now recure into this classes constituent classess
49
+ from_class.each_classmodule do |mod|
50
+ process_class(mod)
51
+ end
52
+ end
53
+
54
+ def generate_class_info(cls)
55
+ if cls === RDoc::NormalModule
56
+ cls_desc = RDoc::RI::ModuleDescription.new
57
+ else
58
+ cls_desc = RDoc::RI::ClassDescription.new
59
+ cls_desc.superclass = cls.superclass
60
+ end
61
+
62
+ cls_desc.name = cls.name
63
+ cls_desc.full_name = cls.full_name
64
+ cls_desc.comment = markup(cls.comment)
65
+
66
+ cls_desc.attributes = cls.attributes.sort.map do |a|
67
+ RDoc::RI::Attribute.new(a.name, a.rw, markup(a.comment))
68
+ end
69
+
70
+ cls_desc.constants = cls.constants.map do |c|
71
+ RDoc::RI::Constant.new(c.name, c.value, markup(c.comment))
72
+ end
73
+
74
+ cls_desc.includes = cls.includes.map do |i|
75
+ RDoc::RI::IncludedModule.new(i.name)
76
+ end
77
+
78
+ class_methods, instance_methods = method_list(cls)
79
+
80
+ cls_desc.class_methods = class_methods.map do |m|
81
+ RDoc::RI::MethodSummary.new(m.name)
82
+ end
83
+
84
+ cls_desc.instance_methods = instance_methods.map do |m|
85
+ RDoc::RI::MethodSummary.new(m.name)
86
+ end
87
+
88
+ update_or_replace(cls_desc)
89
+
90
+ class_methods.each do |m|
91
+ generate_method_info(cls_desc, m)
92
+ end
93
+
94
+ instance_methods.each do |m|
95
+ generate_method_info(cls_desc, m)
96
+ end
97
+ end
98
+
99
+ def generate_method_info(cls_desc, method)
100
+ meth_desc = RDoc::RI::MethodDescription.new
101
+ meth_desc.name = method.name
102
+ meth_desc.full_name = cls_desc.full_name
103
+ if method.singleton
104
+ meth_desc.full_name += "::"
105
+ else
106
+ meth_desc.full_name += "#"
107
+ end
108
+ meth_desc.full_name << method.name
109
+
110
+ meth_desc.comment = markup(method.comment)
111
+ meth_desc.params = params_of(method)
112
+ meth_desc.visibility = method.visibility.to_s
113
+ meth_desc.is_singleton = method.singleton
114
+ meth_desc.block_params = method.block_params
115
+
116
+ meth_desc.aliases = method.aliases.map do |a|
117
+ RDoc::RI::AliasName.new(a.name)
118
+ end
119
+
120
+ @ri_writer.add_method(cls_desc, meth_desc)
121
+ end
122
+
123
+ private
124
+
125
+ ##
126
+ # Returns a list of class and instance methods that we'll be documenting
127
+
128
+ def method_list(cls)
129
+ list = cls.method_list
130
+ unless @options.show_all
131
+ list = list.find_all do |m|
132
+ m.visibility == :public || m.visibility == :protected || m.force_documentation
133
+ end
134
+ end
135
+
136
+ c = []
137
+ i = []
138
+ list.sort.each do |m|
139
+ if m.singleton
140
+ c << m
141
+ else
142
+ i << m
143
+ end
144
+ end
145
+ return c,i
146
+ end
147
+
148
+ def params_of(method)
149
+ if method.call_seq
150
+ method.call_seq
151
+ else
152
+ params = method.params || ""
153
+
154
+ p = params.gsub(/\s*\#.*/, '')
155
+ p = p.tr("\n", " ").squeeze(" ")
156
+ p = "(" + p + ")" unless p[0] == ?(
157
+
158
+ if (block = method.block_params)
159
+ block.gsub!(/\s*\#.*/, '')
160
+ block = block.tr("\n", " ").squeeze(" ")
161
+ if block[0] == ?(
162
+ block.sub!(/^\(/, '').sub!(/\)/, '')
163
+ end
164
+ p << " {|#{block.strip}| ...}"
165
+ end
166
+ p
167
+ end
168
+ end
169
+
170
+ def markup(comment)
171
+ return nil if !comment || comment.empty?
172
+
173
+ # Convert leading comment markers to spaces, but only
174
+ # if all non-blank lines have them
175
+
176
+ if comment =~ /^(?>\s*)[^\#]/
177
+ content = comment
178
+ else
179
+ content = comment.gsub(/^\s*(#+)/) { $1.tr('#',' ') }
180
+ end
181
+ @markup.convert(content, @to_flow)
182
+ end
183
+
184
+ ##
185
+ # By default we replace existing classes with the same name. If the
186
+ # --merge option was given, we instead merge this definition into an
187
+ # existing class. We add our methods, aliases, etc to that class, but do
188
+ # not change the class's description.
189
+
190
+ def update_or_replace(cls_desc)
191
+ old_cls = nil
192
+
193
+ if @options.merge
194
+ rdr = RDoc::RI::Reader.new RDoc::RI::Cache.new(@options.op_dir)
195
+
196
+ namespace = rdr.top_level_namespace
197
+ namespace = rdr.lookup_namespace_in(cls_desc.name, namespace)
198
+ if namespace.empty?
199
+ $stderr.puts "You asked me to merge this source into existing "
200
+ $stderr.puts "documentation. This file references a class or "
201
+ $stderr.puts "module called #{cls_desc.name} which I don't"
202
+ $stderr.puts "have existing documentation for."
203
+ $stderr.puts
204
+ $stderr.puts "Perhaps you need to generate its documentation first"
205
+ exit 1
206
+ else
207
+ old_cls = namespace[0]
208
+ end
209
+ end
210
+
211
+ prev_cls = @generated[cls_desc.full_name]
212
+
213
+ if old_cls and not prev_cls then
214
+ old_desc = rdr.get_class old_cls
215
+ cls_desc.merge_in old_desc
216
+ end
217
+
218
+ if prev_cls then
219
+ cls_desc.merge_in prev_cls
220
+ end
221
+
222
+ @generated[cls_desc.full_name] = cls_desc
223
+
224
+ @ri_writer.remove_class cls_desc
225
+ @ri_writer.add_class cls_desc
226
+ end
227
+
228
+ end
229
+
@@ -0,0 +1,84 @@
1
+ require 'rdoc/rdoc'
2
+ require 'rdoc/generator'
3
+ require 'rdoc/markup/to_texinfo'
4
+
5
+ module RDoc
6
+ RDoc::GENERATORS['texinfo'] = RDoc::Generator.new("rdoc/generator/texinfo",
7
+ :Texinfo,
8
+ 'texinfo')
9
+ module Generator
10
+ # This generates Texinfo files for viewing with GNU Info or Emacs
11
+ # from RDoc extracted from Ruby source files.
12
+ class Texinfo
13
+ # What should the .info file be named by default?
14
+ DEFAULT_INFO_FILENAME = 'rdoc.info'
15
+
16
+ include Generator::MarkUp
17
+
18
+ # Accept some options
19
+ def initialize(options)
20
+ @options = options
21
+ @options.inline_source = true
22
+ @options.op_name ||= 'rdoc.texinfo'
23
+ @options.formatter = ::RDoc::Markup::ToTexInfo.new
24
+ end
25
+
26
+ # Generate the +texinfo+ files
27
+ def generate(toplevels)
28
+ @toplevels = toplevels
29
+ @files, @classes = ::RDoc::Generator::Context.build_indicies(@toplevels,
30
+ @options)
31
+
32
+ (@files + @classes).each { |x| x.value_hash }
33
+
34
+ open(@options.op_name, 'w') do |f|
35
+ f.puts TexinfoTemplate.new('files' => @files,
36
+ 'classes' => @classes,
37
+ 'filename' => @options.op_name.gsub(/texinfo/, 'info'),
38
+ 'title' => @options.title).render
39
+ end
40
+ # TODO: create info files and install?
41
+ end
42
+
43
+ class << self
44
+ # Factory? We don't need no stinkin' factory!
45
+ alias_method :for, :new
46
+ end
47
+ end
48
+
49
+ # Basically just a wrapper around ERB.
50
+ # Should probably use RDoc::TemplatePage instead
51
+ class TexinfoTemplate
52
+ BASE_DIR = ::File.expand_path(::File.dirname(__FILE__)) # have to calculate this when the file's loaded.
53
+
54
+ def initialize(values, file = 'texinfo.erb')
55
+ @v, @file = [values, file]
56
+ end
57
+
58
+ def template
59
+ ::File.read(::File.join(BASE_DIR, 'texinfo', @file))
60
+ end
61
+
62
+ # Go!
63
+ def render
64
+ ERB.new(template).result binding
65
+ end
66
+
67
+ def href(location, text)
68
+ text # TODO: how does texinfo do hyperlinks?
69
+ end
70
+
71
+ def target(name, text)
72
+ text # TODO: how do hyperlink targets work?
73
+ end
74
+
75
+ # TODO: this is probably implemented elsewhere?
76
+ def method_prefix(section)
77
+ { 'Class' => '.',
78
+ 'Module' => '::',
79
+ 'Instance' => '#',
80
+ }[section['category']]
81
+ end
82
+ end
83
+ end
84
+ end
@@ -0,0 +1,44 @@
1
+ @node <%= @v['class']['full_name'].gsub(/::/, '-') %>
2
+ @chapter <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %>
3
+
4
+ <% if @v['class']["parent"] and @v['class']['par_url'] %>
5
+ Inherits <%= href @v['class']["par_url"], @v['class']["parent"] %><% end %>
6
+
7
+ <%= @v['class']["description"] %>
8
+
9
+ <% if @v['class']["includes"] %>
10
+ Includes
11
+ <% @v['class']["includes"].each do |include| %>
12
+ * <%= href include["aref"], include["name"] %>
13
+ <% end # @v['class']["includes"] %>
14
+ <% end %>
15
+
16
+ <% if @v['class']["sections"] %>
17
+ <% @v['class']["sections"].each do |section| %>
18
+ <% if section["attributes"] %>
19
+ Attributes
20
+ <% section["attributes"].each do |attributes| %>
21
+ * <%= attributes["name"] %> <%= attributes["rw"] %> <%= attributes["a_desc"] %>
22
+ <% end # section["attributes"] %>
23
+ <% end %>
24
+ <% end %>
25
+
26
+ <% @v['class']["sections"].each do |section| %>
27
+ <% if section["method_list"] %>
28
+ Methods
29
+ @menu
30
+ <% section["method_list"].each_with_index do |method_list, i| %>
31
+ <%= i %>
32
+ <% (method_list["methods"] || []).each do |method| %>
33
+ * <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix method_list %><%= method['name'] %>::<% end %>
34
+ <% end %>
35
+ @end menu
36
+
37
+ <% section["method_list"].each do |method_list| %>
38
+ <% (method_list["methods"] || []).uniq.each do |method| %>
39
+ <%= TexinfoTemplate.new(@v.merge({'method' => method, 'list' => method_list}),
40
+ 'method.texinfo.erb').render %><% end %>
41
+ <% end # section["method_list"] %>
42
+ <% end %>
43
+ <% end # @v['class']["sections"] %>
44
+ <% end %>
@@ -0,0 +1,6 @@
1
+ <% if false %>
2
+ <h2>File: <%= @v['file']["short_name"] %></h2>
3
+ Path: <%= @v['file']["full_path"] %>
4
+
5
+ <%= TexinfoTemplate.new(@v, 'content.texinfo.erb').render %>
6
+ <% end %>
@@ -0,0 +1,6 @@
1
+ @node <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
2
+ @section <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
3
+ <%= @v['method']["type"] %> <%= @v['method']["category"] %> method:
4
+ <%= target @v['method']["aref"], @v['method']['callseq'] ||
5
+ @v['method']["name"] + @v['method']["params"] %>
6
+ <%= @v['method']["m_desc"] %>
@@ -0,0 +1,28 @@
1
+ \input texinfo @c -*-texinfo-*-
2
+ @c %**start of header
3
+ @setfilename <%= @v['filename'] %>
4
+ @settitle <%= @v['title'] %>
5
+ @c %**end of header
6
+
7
+ @contents @c TODO: whitespace is a mess... =\
8
+
9
+ @ifnottex
10
+ @node Top
11
+
12
+ @top <%= @v['title'] %>
13
+ @end ifnottex
14
+
15
+ <% if @f = @v['files'].detect { |f| f.name =~ /Readme/i } %>
16
+ <%= @f.values['description'] %><% end %>
17
+
18
+ @menu
19
+ <% @v['classes'].each do |klass| %>
20
+ * <%= klass.name.gsub(/::/, '-') %>::<% end %>
21
+ @c TODO: add files
22
+ @end menu
23
+
24
+ <% (@v['classes'] || []).each_with_index do |klass, i| %>
25
+ <%= TexinfoTemplate.new(@v.merge('class' => klass.values),
26
+ 'class.texinfo.erb').render %><% end %>
27
+
28
+ @bye
@@ -0,0 +1,120 @@
1
+ require 'rdoc/generator/html'
2
+
3
+ ##
4
+ # Generate XML output as one big file
5
+
6
+ class RDoc::Generator::XML < RDoc::Generator::HTML
7
+
8
+ ##
9
+ # Standard generator factory
10
+
11
+ def self.for(options)
12
+ new(options)
13
+ end
14
+
15
+ def initialize(*args)
16
+ super
17
+ end
18
+
19
+ ##
20
+ # Build the initial indices and output objects
21
+ # based on an array of TopLevel objects containing
22
+ # the extracted information.
23
+
24
+ def generate(info)
25
+ @info = info
26
+ @files = []
27
+ @classes = []
28
+ @hyperlinks = {}
29
+
30
+ build_indices
31
+ generate_xml
32
+ end
33
+
34
+ ##
35
+ # Generate:
36
+ #
37
+ # * a list of HtmlFile objects for each TopLevel object.
38
+ # * a list of HtmlClass objects for each first level
39
+ # class or module in the TopLevel objects
40
+ # * a complete list of all hyperlinkable terms (file,
41
+ # class, module, and method names)
42
+
43
+ def build_indices
44
+ @info.each do |toplevel|
45
+ @files << RDoc::Generator::HtmlFile.new(toplevel, @options, RDoc::Generator::FILE_DIR)
46
+ end
47
+
48
+ RDoc::TopLevel.all_classes_and_modules.each do |cls|
49
+ build_class_list(cls, @files[0], RDoc::Generator::CLASS_DIR)
50
+ end
51
+ end
52
+
53
+ def build_class_list(from, html_file, class_dir)
54
+ @classes << RDoc::Generator::HtmlClass.new(from, html_file, class_dir, @options)
55
+ from.each_classmodule do |mod|
56
+ build_class_list(mod, html_file, class_dir)
57
+ end
58
+ end
59
+
60
+ ##
61
+ # Generate all the HTML. For the one-file case, we generate
62
+ # all the information in to one big hash
63
+
64
+ def generate_xml
65
+ values = {
66
+ 'charset' => @options.charset,
67
+ 'files' => gen_into(@files),
68
+ 'classes' => gen_into(@classes)
69
+ }
70
+
71
+ # this method is defined in the template file
72
+ write_extra_pages if defined? write_extra_pages
73
+
74
+ template = RDoc::TemplatePage.new @template::ONE_PAGE
75
+
76
+ if @options.op_name
77
+ opfile = File.open(@options.op_name, "w")
78
+ else
79
+ opfile = $stdout
80
+ end
81
+ template.write_html_on(opfile, values)
82
+ end
83
+
84
+ def gen_into(list)
85
+ res = []
86
+ list.each do |item|
87
+ res << item.value_hash
88
+ end
89
+ res
90
+ end
91
+
92
+ def gen_file_index
93
+ gen_an_index(@files, 'Files')
94
+ end
95
+
96
+ def gen_class_index
97
+ gen_an_index(@classes, 'Classes')
98
+ end
99
+
100
+ def gen_method_index
101
+ gen_an_index(RDoc::Generator::HtmlMethod.all_methods, 'Methods')
102
+ end
103
+
104
+ def gen_an_index(collection, title)
105
+ res = []
106
+ collection.sort.each do |f|
107
+ if f.document_self
108
+ res << { "href" => f.path, "name" => f.index_name }
109
+ end
110
+ end
111
+
112
+ return {
113
+ "entries" => res,
114
+ 'list_title' => title,
115
+ 'index_url' => main_url,
116
+ }
117
+ end
118
+
119
+ end
120
+