gitlab-rdoc 6.3.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/CONTRIBUTING.rdoc +220 -0
- data/CVE-2013-0256.rdoc +49 -0
- data/ExampleMarkdown.md +37 -0
- data/ExampleRDoc.rdoc +208 -0
- data/Gemfile +12 -0
- data/History.rdoc +1666 -0
- data/LEGAL.rdoc +50 -0
- data/LICENSE.rdoc +57 -0
- data/README.rdoc +133 -0
- data/RI.rdoc +57 -0
- data/Rakefile +101 -0
- data/TODO.rdoc +59 -0
- data/bin/console +7 -0
- data/bin/setup +6 -0
- data/exe/rdoc +44 -0
- data/exe/ri +12 -0
- data/lib/rdoc/alias.rb +112 -0
- data/lib/rdoc/anon_class.rb +11 -0
- data/lib/rdoc/any_method.rb +361 -0
- data/lib/rdoc/attr.rb +176 -0
- data/lib/rdoc/class_module.rb +802 -0
- data/lib/rdoc/code_object.rb +421 -0
- data/lib/rdoc/code_objects.rb +6 -0
- data/lib/rdoc/comment.rb +250 -0
- data/lib/rdoc/constant.rb +187 -0
- data/lib/rdoc/context/section.rb +232 -0
- data/lib/rdoc/context.rb +1266 -0
- data/lib/rdoc/cross_reference.rb +202 -0
- data/lib/rdoc/encoding.rb +136 -0
- data/lib/rdoc/erb_partial.rb +19 -0
- data/lib/rdoc/erbio.rb +42 -0
- data/lib/rdoc/extend.rb +10 -0
- data/lib/rdoc/generator/darkfish.rb +790 -0
- data/lib/rdoc/generator/json_index.rb +300 -0
- data/lib/rdoc/generator/markup.rb +160 -0
- data/lib/rdoc/generator/pot/message_extractor.rb +68 -0
- data/lib/rdoc/generator/pot/po.rb +84 -0
- data/lib/rdoc/generator/pot/po_entry.rb +141 -0
- data/lib/rdoc/generator/pot.rb +98 -0
- data/lib/rdoc/generator/ri.rb +31 -0
- data/lib/rdoc/generator/template/darkfish/.document +0 -0
- data/lib/rdoc/generator/template/darkfish/_footer.rhtml +5 -0
- data/lib/rdoc/generator/template/darkfish/_head.rhtml +22 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_VCS_info.rhtml +19 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_classes.rhtml +9 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml +9 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_includes.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_installed.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_methods.rhtml +12 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_pages.rhtml +12 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_parent.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_search.rhtml +14 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_sections.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/class.rhtml +172 -0
- data/lib/rdoc/generator/template/darkfish/css/fonts.css +167 -0
- data/lib/rdoc/generator/template/darkfish/css/rdoc.css +639 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-Light.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-LightItalic.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-Regular.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-RegularItalic.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/SourceCodePro-Bold.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/SourceCodePro-Regular.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/images/add.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/arrow_up.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/brick.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/brick_link.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bug.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_black.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_toggle_minus.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_toggle_plus.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/date.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/delete.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/find.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/loadingAnimation.gif +0 -0
- data/lib/rdoc/generator/template/darkfish/images/macFFBgHack.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/package.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_green.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_white_text.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_white_width.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/plugin.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/ruby.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/tag_blue.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/tag_green.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/transparent.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/wrench.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/wrench_orange.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/zoom.png +0 -0
- data/lib/rdoc/generator/template/darkfish/index.rhtml +22 -0
- data/lib/rdoc/generator/template/darkfish/js/darkfish.js +84 -0
- data/lib/rdoc/generator/template/darkfish/js/search.js +110 -0
- data/lib/rdoc/generator/template/darkfish/page.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/servlet_not_found.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/servlet_root.rhtml +62 -0
- data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml +58 -0
- data/lib/rdoc/generator/template/json_index/.document +1 -0
- data/lib/rdoc/generator/template/json_index/js/navigation.js +105 -0
- data/lib/rdoc/generator/template/json_index/js/searcher.js +229 -0
- data/lib/rdoc/generator.rb +51 -0
- data/lib/rdoc/ghost_method.rb +7 -0
- data/lib/rdoc/i18n/locale.rb +102 -0
- data/lib/rdoc/i18n/text.rb +126 -0
- data/lib/rdoc/i18n.rb +10 -0
- data/lib/rdoc/include.rb +10 -0
- data/lib/rdoc/known_classes.rb +73 -0
- data/lib/rdoc/markdown/entities.rb +2132 -0
- data/lib/rdoc/markdown/literals.kpeg +23 -0
- data/lib/rdoc/markdown/literals.rb +417 -0
- data/lib/rdoc/markdown.kpeg +1237 -0
- data/lib/rdoc/markdown.rb +16685 -0
- data/lib/rdoc/markup/attr_changer.rb +23 -0
- data/lib/rdoc/markup/attr_span.rb +36 -0
- data/lib/rdoc/markup/attribute_manager.rb +409 -0
- data/lib/rdoc/markup/attributes.rb +71 -0
- data/lib/rdoc/markup/blank_line.rb +28 -0
- data/lib/rdoc/markup/block_quote.rb +15 -0
- data/lib/rdoc/markup/document.rb +165 -0
- data/lib/rdoc/markup/formatter.rb +266 -0
- data/lib/rdoc/markup/hard_break.rb +32 -0
- data/lib/rdoc/markup/heading.rb +79 -0
- data/lib/rdoc/markup/include.rb +43 -0
- data/lib/rdoc/markup/indented_paragraph.rb +48 -0
- data/lib/rdoc/markup/list.rb +102 -0
- data/lib/rdoc/markup/list_item.rb +100 -0
- data/lib/rdoc/markup/paragraph.rb +29 -0
- data/lib/rdoc/markup/parser.rb +575 -0
- data/lib/rdoc/markup/pre_process.rb +296 -0
- data/lib/rdoc/markup/raw.rb +70 -0
- data/lib/rdoc/markup/regexp_handling.rb +41 -0
- data/lib/rdoc/markup/rule.rb +21 -0
- data/lib/rdoc/markup/table.rb +47 -0
- data/lib/rdoc/markup/to_ansi.rb +94 -0
- data/lib/rdoc/markup/to_bs.rb +77 -0
- data/lib/rdoc/markup/to_html.rb +444 -0
- data/lib/rdoc/markup/to_html_crossref.rb +176 -0
- data/lib/rdoc/markup/to_html_snippet.rb +285 -0
- data/lib/rdoc/markup/to_joined_paragraph.rb +47 -0
- data/lib/rdoc/markup/to_label.rb +75 -0
- data/lib/rdoc/markup/to_markdown.rb +192 -0
- data/lib/rdoc/markup/to_rdoc.rb +362 -0
- data/lib/rdoc/markup/to_table_of_contents.rb +89 -0
- data/lib/rdoc/markup/to_test.rb +70 -0
- data/lib/rdoc/markup/to_tt_only.rb +121 -0
- data/lib/rdoc/markup/verbatim.rb +84 -0
- data/lib/rdoc/markup.rb +867 -0
- data/lib/rdoc/meta_method.rb +7 -0
- data/lib/rdoc/method_attr.rb +419 -0
- data/lib/rdoc/mixin.rb +121 -0
- data/lib/rdoc/normal_class.rb +93 -0
- data/lib/rdoc/normal_module.rb +74 -0
- data/lib/rdoc/options.rb +1285 -0
- data/lib/rdoc/parser/c.rb +1225 -0
- data/lib/rdoc/parser/changelog.rb +335 -0
- data/lib/rdoc/parser/markdown.rb +24 -0
- data/lib/rdoc/parser/rd.rb +23 -0
- data/lib/rdoc/parser/ripper_state_lex.rb +590 -0
- data/lib/rdoc/parser/ruby.rb +2327 -0
- data/lib/rdoc/parser/ruby_tools.rb +167 -0
- data/lib/rdoc/parser/simple.rb +61 -0
- data/lib/rdoc/parser/text.rb +12 -0
- data/lib/rdoc/parser.rb +277 -0
- data/lib/rdoc/rd/block_parser.rb +1056 -0
- data/lib/rdoc/rd/block_parser.ry +639 -0
- data/lib/rdoc/rd/inline.rb +72 -0
- data/lib/rdoc/rd/inline_parser.rb +1208 -0
- data/lib/rdoc/rd/inline_parser.ry +593 -0
- data/lib/rdoc/rd.rb +100 -0
- data/lib/rdoc/rdoc.rb +579 -0
- data/lib/rdoc/require.rb +52 -0
- data/lib/rdoc/ri/driver.rb +1572 -0
- data/lib/rdoc/ri/formatter.rb +6 -0
- data/lib/rdoc/ri/paths.rb +171 -0
- data/lib/rdoc/ri/store.rb +7 -0
- data/lib/rdoc/ri/task.rb +71 -0
- data/lib/rdoc/ri.rb +21 -0
- data/lib/rdoc/rubygems_hook.rb +246 -0
- data/lib/rdoc/servlet.rb +451 -0
- data/lib/rdoc/single_class.rb +26 -0
- data/lib/rdoc/stats/normal.rb +58 -0
- data/lib/rdoc/stats/quiet.rb +60 -0
- data/lib/rdoc/stats/verbose.rb +46 -0
- data/lib/rdoc/stats.rb +462 -0
- data/lib/rdoc/store.rb +979 -0
- data/lib/rdoc/task.rb +329 -0
- data/lib/rdoc/text.rb +304 -0
- data/lib/rdoc/token_stream.rb +119 -0
- data/lib/rdoc/tom_doc.rb +263 -0
- data/lib/rdoc/top_level.rb +289 -0
- data/lib/rdoc/version.rb +8 -0
- data/lib/rdoc.rb +201 -0
- data/man/ri.1 +247 -0
- data/rdoc.gemspec +249 -0
- metadata +279 -0
data/lib/rdoc/rd.rb
ADDED
@@ -0,0 +1,100 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
##
|
3
|
+
# RDoc::RD implements the RD format from the rdtool gem.
|
4
|
+
#
|
5
|
+
# To choose RD as your only default format see
|
6
|
+
# RDoc::Options@Saved+Options for instructions on setting up a
|
7
|
+
# <code>.doc_options</code> file to store your project default.
|
8
|
+
#
|
9
|
+
# == LICENSE
|
10
|
+
#
|
11
|
+
# The grammar that produces RDoc::RD::BlockParser and RDoc::RD::InlineParser
|
12
|
+
# is included in RDoc under the Ruby License.
|
13
|
+
#
|
14
|
+
# You can find the original source for rdtool at
|
15
|
+
# https://github.com/uwabami/rdtool/
|
16
|
+
#
|
17
|
+
# You can use, re-distribute or change these files under Ruby's License or GPL.
|
18
|
+
#
|
19
|
+
# 1. You may make and give away verbatim copies of the source form of the
|
20
|
+
# software without restriction, provided that you duplicate all of the
|
21
|
+
# original copyright notices and associated disclaimers.
|
22
|
+
#
|
23
|
+
# 2. You may modify your copy of the software in any way, provided that
|
24
|
+
# you do at least ONE of the following:
|
25
|
+
#
|
26
|
+
# a. place your modifications in the Public Domain or otherwise
|
27
|
+
# make them Freely Available, such as by posting said
|
28
|
+
# modifications to Usenet or an equivalent medium, or by allowing
|
29
|
+
# the author to include your modifications in the software.
|
30
|
+
#
|
31
|
+
# b. use the modified software only within your corporation or
|
32
|
+
# organization.
|
33
|
+
#
|
34
|
+
# c. give non-standard binaries non-standard names, with
|
35
|
+
# instructions on where to get the original software distribution.
|
36
|
+
#
|
37
|
+
# d. make other distribution arrangements with the author.
|
38
|
+
#
|
39
|
+
# 3. You may distribute the software in object code or binary form,
|
40
|
+
# provided that you do at least ONE of the following:
|
41
|
+
#
|
42
|
+
# a. distribute the binaries and library files of the software,
|
43
|
+
# together with instructions (in the manual page or equivalent)
|
44
|
+
# on where to get the original distribution.
|
45
|
+
#
|
46
|
+
# b. accompany the distribution with the machine-readable source of
|
47
|
+
# the software.
|
48
|
+
#
|
49
|
+
# c. give non-standard binaries non-standard names, with
|
50
|
+
# instructions on where to get the original software distribution.
|
51
|
+
#
|
52
|
+
# d. make other distribution arrangements with the author.
|
53
|
+
#
|
54
|
+
# 4. You may modify and include the part of the software into any other
|
55
|
+
# software (possibly commercial). But some files in the distribution
|
56
|
+
# are not written by the author, so that they are not under these terms.
|
57
|
+
#
|
58
|
+
# For the list of those files and their copying conditions, see the
|
59
|
+
# file LEGAL.
|
60
|
+
#
|
61
|
+
# 5. The scripts and library files supplied as input to or produced as
|
62
|
+
# output from the software do not automatically fall under the
|
63
|
+
# copyright of the software, but belong to whomever generated them,
|
64
|
+
# and may be sold commercially, and may be aggregated with this
|
65
|
+
# software.
|
66
|
+
#
|
67
|
+
# 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
|
68
|
+
# IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
|
69
|
+
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
70
|
+
# PURPOSE.
|
71
|
+
|
72
|
+
class RDoc::RD
|
73
|
+
|
74
|
+
##
|
75
|
+
# Parses +rd+ source and returns an RDoc::Markup::Document. If the
|
76
|
+
# <tt>=begin</tt> or <tt>=end</tt> lines are missing they will be added.
|
77
|
+
|
78
|
+
def self.parse rd
|
79
|
+
rd = rd.lines.to_a
|
80
|
+
|
81
|
+
if rd.find { |i| /\S/ === i } and !rd.find{|i| /^=begin\b/ === i } then
|
82
|
+
rd.unshift("=begin\n").push("=end\n")
|
83
|
+
end
|
84
|
+
|
85
|
+
parser = RDoc::RD::BlockParser.new
|
86
|
+
document = parser.parse rd
|
87
|
+
|
88
|
+
# isn't this always true?
|
89
|
+
document.parts.shift if RDoc::Markup::BlankLine === document.parts.first
|
90
|
+
document.parts.pop if RDoc::Markup::BlankLine === document.parts.last
|
91
|
+
|
92
|
+
document
|
93
|
+
end
|
94
|
+
|
95
|
+
autoload :BlockParser, 'rdoc/rd/block_parser'
|
96
|
+
autoload :InlineParser, 'rdoc/rd/inline_parser'
|
97
|
+
autoload :Inline, 'rdoc/rd/inline'
|
98
|
+
|
99
|
+
end
|
100
|
+
|
data/lib/rdoc/rdoc.rb
ADDED
@@ -0,0 +1,579 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
require 'rdoc'
|
3
|
+
|
4
|
+
require 'find'
|
5
|
+
require 'fileutils'
|
6
|
+
require 'pathname'
|
7
|
+
require 'time'
|
8
|
+
|
9
|
+
##
|
10
|
+
# This is the driver for generating RDoc output. It handles file parsing and
|
11
|
+
# generation of output.
|
12
|
+
#
|
13
|
+
# To use this class to generate RDoc output via the API, the recommended way
|
14
|
+
# is:
|
15
|
+
#
|
16
|
+
# rdoc = RDoc::RDoc.new
|
17
|
+
# options = rdoc.load_options # returns an RDoc::Options instance
|
18
|
+
# # set extra options
|
19
|
+
# rdoc.document options
|
20
|
+
#
|
21
|
+
# You can also generate output like the +rdoc+ executable:
|
22
|
+
#
|
23
|
+
# rdoc = RDoc::RDoc.new
|
24
|
+
# rdoc.document argv
|
25
|
+
#
|
26
|
+
# Where +argv+ is an array of strings, each corresponding to an argument you'd
|
27
|
+
# give rdoc on the command line. See <tt>rdoc --help</tt> for details.
|
28
|
+
|
29
|
+
class RDoc::RDoc
|
30
|
+
|
31
|
+
@current = nil
|
32
|
+
|
33
|
+
##
|
34
|
+
# This is the list of supported output generators
|
35
|
+
|
36
|
+
GENERATORS = {}
|
37
|
+
|
38
|
+
##
|
39
|
+
# Generator instance used for creating output
|
40
|
+
|
41
|
+
attr_accessor :generator
|
42
|
+
|
43
|
+
##
|
44
|
+
# Hash of files and their last modified times.
|
45
|
+
|
46
|
+
attr_reader :last_modified
|
47
|
+
|
48
|
+
##
|
49
|
+
# RDoc options
|
50
|
+
|
51
|
+
attr_accessor :options
|
52
|
+
|
53
|
+
##
|
54
|
+
# Accessor for statistics. Available after each call to parse_files
|
55
|
+
|
56
|
+
attr_reader :stats
|
57
|
+
|
58
|
+
##
|
59
|
+
# The current documentation store
|
60
|
+
|
61
|
+
attr_reader :store
|
62
|
+
|
63
|
+
##
|
64
|
+
# Add +klass+ that can generate output after parsing
|
65
|
+
|
66
|
+
def self.add_generator(klass)
|
67
|
+
name = klass.name.sub(/^RDoc::Generator::/, '').downcase
|
68
|
+
GENERATORS[name] = klass
|
69
|
+
end
|
70
|
+
|
71
|
+
##
|
72
|
+
# Active RDoc::RDoc instance
|
73
|
+
|
74
|
+
def self.current
|
75
|
+
@current
|
76
|
+
end
|
77
|
+
|
78
|
+
##
|
79
|
+
# Sets the active RDoc::RDoc instance
|
80
|
+
|
81
|
+
def self.current= rdoc
|
82
|
+
@current = rdoc
|
83
|
+
end
|
84
|
+
|
85
|
+
##
|
86
|
+
# Creates a new RDoc::RDoc instance. Call #document to parse files and
|
87
|
+
# generate documentation.
|
88
|
+
|
89
|
+
def initialize
|
90
|
+
@current = nil
|
91
|
+
@generator = nil
|
92
|
+
@last_modified = {}
|
93
|
+
@old_siginfo = nil
|
94
|
+
@options = nil
|
95
|
+
@stats = nil
|
96
|
+
@store = nil
|
97
|
+
end
|
98
|
+
|
99
|
+
##
|
100
|
+
# Report an error message and exit
|
101
|
+
|
102
|
+
def error(msg)
|
103
|
+
raise RDoc::Error, msg
|
104
|
+
end
|
105
|
+
|
106
|
+
##
|
107
|
+
# Gathers a set of parseable files from the files and directories listed in
|
108
|
+
# +files+.
|
109
|
+
|
110
|
+
def gather_files files
|
111
|
+
files = ["."] if files.empty?
|
112
|
+
|
113
|
+
file_list = normalized_file_list files, true, @options.exclude
|
114
|
+
|
115
|
+
file_list = remove_unparseable(file_list)
|
116
|
+
|
117
|
+
if file_list.count {|name, mtime|
|
118
|
+
file_list[name] = @last_modified[name] unless mtime
|
119
|
+
mtime
|
120
|
+
} > 0
|
121
|
+
@last_modified.replace file_list
|
122
|
+
file_list.keys.sort
|
123
|
+
else
|
124
|
+
[]
|
125
|
+
end
|
126
|
+
end
|
127
|
+
|
128
|
+
##
|
129
|
+
# Turns RDoc from stdin into HTML
|
130
|
+
|
131
|
+
def handle_pipe
|
132
|
+
@html = RDoc::Markup::ToHtml.new @options
|
133
|
+
|
134
|
+
parser = RDoc::Text::MARKUP_FORMAT[@options.markup]
|
135
|
+
|
136
|
+
document = parser.parse $stdin.read
|
137
|
+
|
138
|
+
out = @html.convert document
|
139
|
+
|
140
|
+
$stdout.write out
|
141
|
+
end
|
142
|
+
|
143
|
+
##
|
144
|
+
# Installs a siginfo handler that prints the current filename.
|
145
|
+
|
146
|
+
def install_siginfo_handler
|
147
|
+
return unless Signal.list.include? 'INFO'
|
148
|
+
|
149
|
+
@old_siginfo = trap 'INFO' do
|
150
|
+
puts @current if @current
|
151
|
+
end
|
152
|
+
end
|
153
|
+
|
154
|
+
##
|
155
|
+
# Loads options from .rdoc_options if the file exists, otherwise creates a
|
156
|
+
# new RDoc::Options instance.
|
157
|
+
|
158
|
+
def load_options
|
159
|
+
options_file = File.expand_path '.rdoc_options'
|
160
|
+
return RDoc::Options.new unless File.exist? options_file
|
161
|
+
|
162
|
+
RDoc.load_yaml
|
163
|
+
|
164
|
+
begin
|
165
|
+
options = YAML.load_file '.rdoc_options'
|
166
|
+
rescue Psych::SyntaxError
|
167
|
+
end
|
168
|
+
|
169
|
+
return RDoc::Options.new if options == false # Allow empty file.
|
170
|
+
|
171
|
+
raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
|
172
|
+
RDoc::Options === options or Hash === options
|
173
|
+
|
174
|
+
if Hash === options
|
175
|
+
# Override the default values with the contents of YAML file.
|
176
|
+
options = RDoc::Options.new options
|
177
|
+
end
|
178
|
+
|
179
|
+
options
|
180
|
+
end
|
181
|
+
|
182
|
+
##
|
183
|
+
# Create an output dir if it doesn't exist. If it does exist, but doesn't
|
184
|
+
# contain the flag file <tt>created.rid</tt> then we refuse to use it, as
|
185
|
+
# we may clobber some manually generated documentation
|
186
|
+
|
187
|
+
def setup_output_dir(dir, force)
|
188
|
+
flag_file = output_flag_file dir
|
189
|
+
|
190
|
+
last = {}
|
191
|
+
|
192
|
+
if @options.dry_run then
|
193
|
+
# do nothing
|
194
|
+
elsif File.exist? dir then
|
195
|
+
error "#{dir} exists and is not a directory" unless File.directory? dir
|
196
|
+
|
197
|
+
begin
|
198
|
+
File.open flag_file do |io|
|
199
|
+
unless force then
|
200
|
+
Time.parse io.gets
|
201
|
+
|
202
|
+
io.each do |line|
|
203
|
+
file, time = line.split "\t", 2
|
204
|
+
time = Time.parse(time) rescue next
|
205
|
+
last[file] = time
|
206
|
+
end
|
207
|
+
end
|
208
|
+
end
|
209
|
+
rescue SystemCallError, TypeError
|
210
|
+
error <<-ERROR
|
211
|
+
|
212
|
+
Directory #{dir} already exists, but it looks like it isn't an RDoc directory.
|
213
|
+
|
214
|
+
Because RDoc doesn't want to risk destroying any of your existing files,
|
215
|
+
you'll need to specify a different output directory name (using the --op <dir>
|
216
|
+
option)
|
217
|
+
|
218
|
+
ERROR
|
219
|
+
end unless @options.force_output
|
220
|
+
else
|
221
|
+
FileUtils.mkdir_p dir
|
222
|
+
FileUtils.touch flag_file
|
223
|
+
end
|
224
|
+
|
225
|
+
last
|
226
|
+
end
|
227
|
+
|
228
|
+
##
|
229
|
+
# Sets the current documentation tree to +store+ and sets the store's rdoc
|
230
|
+
# driver to this instance.
|
231
|
+
|
232
|
+
def store= store
|
233
|
+
@store = store
|
234
|
+
@store.rdoc = self
|
235
|
+
end
|
236
|
+
|
237
|
+
##
|
238
|
+
# Update the flag file in an output directory.
|
239
|
+
|
240
|
+
def update_output_dir(op_dir, time, last = {})
|
241
|
+
return if @options.dry_run or not @options.update_output_dir
|
242
|
+
unless ENV['SOURCE_DATE_EPOCH'].nil?
|
243
|
+
time = Time.at(ENV['SOURCE_DATE_EPOCH'].to_i).gmtime
|
244
|
+
end
|
245
|
+
|
246
|
+
File.open output_flag_file(op_dir), "w" do |f|
|
247
|
+
f.puts time.rfc2822
|
248
|
+
last.each do |n, t|
|
249
|
+
f.puts "#{n}\t#{t.rfc2822}"
|
250
|
+
end
|
251
|
+
end
|
252
|
+
end
|
253
|
+
|
254
|
+
##
|
255
|
+
# Return the path name of the flag file in an output directory.
|
256
|
+
|
257
|
+
def output_flag_file(op_dir)
|
258
|
+
File.join op_dir, "created.rid"
|
259
|
+
end
|
260
|
+
|
261
|
+
##
|
262
|
+
# The .document file contains a list of file and directory name patterns,
|
263
|
+
# representing candidates for documentation. It may also contain comments
|
264
|
+
# (starting with '#')
|
265
|
+
|
266
|
+
def parse_dot_doc_file in_dir, filename
|
267
|
+
# read and strip comments
|
268
|
+
patterns = File.read(filename).gsub(/#.*/, '')
|
269
|
+
|
270
|
+
result = {}
|
271
|
+
|
272
|
+
patterns.split(' ').each do |patt|
|
273
|
+
candidates = Dir.glob(File.join(in_dir, patt))
|
274
|
+
result.update normalized_file_list(candidates, false, @options.exclude)
|
275
|
+
end
|
276
|
+
|
277
|
+
result
|
278
|
+
end
|
279
|
+
|
280
|
+
##
|
281
|
+
# Given a list of files and directories, create a list of all the Ruby
|
282
|
+
# files they contain.
|
283
|
+
#
|
284
|
+
# If +force_doc+ is true we always add the given files, if false, only
|
285
|
+
# add files that we guarantee we can parse. It is true when looking at
|
286
|
+
# files given on the command line, false when recursing through
|
287
|
+
# subdirectories.
|
288
|
+
#
|
289
|
+
# The effect of this is that if you want a file with a non-standard
|
290
|
+
# extension parsed, you must name it explicitly.
|
291
|
+
|
292
|
+
def normalized_file_list(relative_files, force_doc = false,
|
293
|
+
exclude_pattern = nil)
|
294
|
+
file_list = {}
|
295
|
+
|
296
|
+
relative_files.each do |rel_file_name|
|
297
|
+
rel_file_name = rel_file_name.sub(/^\.\//, '')
|
298
|
+
next if rel_file_name.end_with? 'created.rid'
|
299
|
+
next if exclude_pattern && exclude_pattern =~ rel_file_name
|
300
|
+
stat = File.stat rel_file_name rescue next
|
301
|
+
|
302
|
+
case type = stat.ftype
|
303
|
+
when "file" then
|
304
|
+
mtime = (stat.mtime unless (last_modified = @last_modified[rel_file_name] and
|
305
|
+
stat.mtime.to_i <= last_modified.to_i))
|
306
|
+
|
307
|
+
if force_doc or RDoc::Parser.can_parse(rel_file_name) then
|
308
|
+
file_list[rel_file_name] = mtime
|
309
|
+
end
|
310
|
+
when "directory" then
|
311
|
+
next if rel_file_name == "CVS" || rel_file_name == ".svn"
|
312
|
+
|
313
|
+
created_rid = File.join rel_file_name, "created.rid"
|
314
|
+
next if File.file? created_rid
|
315
|
+
|
316
|
+
dot_doc = File.join rel_file_name, RDoc::DOT_DOC_FILENAME
|
317
|
+
|
318
|
+
if File.file? dot_doc then
|
319
|
+
file_list.update(parse_dot_doc_file(rel_file_name, dot_doc))
|
320
|
+
else
|
321
|
+
file_list.update(list_files_in_directory(rel_file_name))
|
322
|
+
end
|
323
|
+
else
|
324
|
+
warn "rdoc can't parse the #{type} #{rel_file_name}"
|
325
|
+
end
|
326
|
+
end
|
327
|
+
|
328
|
+
file_list
|
329
|
+
end
|
330
|
+
|
331
|
+
##
|
332
|
+
# Return a list of the files to be processed in a directory. We know that
|
333
|
+
# this directory doesn't have a .document file, so we're looking for real
|
334
|
+
# files. However we may well contain subdirectories which must be tested
|
335
|
+
# for .document files.
|
336
|
+
|
337
|
+
def list_files_in_directory dir
|
338
|
+
files = Dir.glob File.join(dir, "*")
|
339
|
+
|
340
|
+
normalized_file_list files, false, @options.exclude
|
341
|
+
end
|
342
|
+
|
343
|
+
##
|
344
|
+
# Parses +filename+ and returns an RDoc::TopLevel
|
345
|
+
|
346
|
+
def parse_file filename
|
347
|
+
encoding = @options.encoding
|
348
|
+
filename = filename.encode encoding
|
349
|
+
|
350
|
+
@stats.add_file filename
|
351
|
+
|
352
|
+
return if RDoc::Parser.binary? filename
|
353
|
+
|
354
|
+
content = RDoc::Encoding.read_file filename, encoding
|
355
|
+
|
356
|
+
return unless content
|
357
|
+
|
358
|
+
filename_path = Pathname(filename).expand_path
|
359
|
+
begin
|
360
|
+
relative_path = filename_path.relative_path_from @options.root
|
361
|
+
rescue ArgumentError
|
362
|
+
relative_path = filename_path
|
363
|
+
end
|
364
|
+
|
365
|
+
if @options.page_dir and
|
366
|
+
relative_path.to_s.start_with? @options.page_dir.to_s then
|
367
|
+
relative_path =
|
368
|
+
relative_path.relative_path_from @options.page_dir
|
369
|
+
end
|
370
|
+
|
371
|
+
top_level = @store.add_file filename, relative_name: relative_path.to_s
|
372
|
+
|
373
|
+
parser = RDoc::Parser.for top_level, filename, content, @options, @stats
|
374
|
+
|
375
|
+
return unless parser
|
376
|
+
|
377
|
+
parser.scan
|
378
|
+
|
379
|
+
# restart documentation for the classes & modules found
|
380
|
+
top_level.classes_or_modules.each do |cm|
|
381
|
+
cm.done_documenting = false
|
382
|
+
end
|
383
|
+
|
384
|
+
top_level
|
385
|
+
|
386
|
+
rescue Errno::EACCES => e
|
387
|
+
$stderr.puts <<-EOF
|
388
|
+
Unable to read #{filename}, #{e.message}
|
389
|
+
|
390
|
+
Please check the permissions for this file. Perhaps you do not have access to
|
391
|
+
it or perhaps the original author's permissions are to restrictive. If the
|
392
|
+
this is not your library please report a bug to the author.
|
393
|
+
EOF
|
394
|
+
rescue => e
|
395
|
+
$stderr.puts <<-EOF
|
396
|
+
Before reporting this, could you check that the file you're documenting
|
397
|
+
has proper syntax:
|
398
|
+
|
399
|
+
#{Gem.ruby} -c #{filename}
|
400
|
+
|
401
|
+
RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
|
402
|
+
|
403
|
+
The internal error was:
|
404
|
+
|
405
|
+
\t(#{e.class}) #{e.message}
|
406
|
+
|
407
|
+
EOF
|
408
|
+
|
409
|
+
$stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC
|
410
|
+
|
411
|
+
raise e
|
412
|
+
nil
|
413
|
+
end
|
414
|
+
|
415
|
+
##
|
416
|
+
# Parse each file on the command line, recursively entering directories.
|
417
|
+
|
418
|
+
def parse_files files
|
419
|
+
file_list = gather_files files
|
420
|
+
@stats = RDoc::Stats.new @store, file_list.length, @options.verbosity
|
421
|
+
|
422
|
+
return [] if file_list.empty?
|
423
|
+
|
424
|
+
original_options = @options.dup
|
425
|
+
@stats.begin_adding
|
426
|
+
|
427
|
+
file_info = file_list.map do |filename|
|
428
|
+
@current = filename
|
429
|
+
parse_file filename
|
430
|
+
end.compact
|
431
|
+
|
432
|
+
@stats.done_adding
|
433
|
+
@options = original_options
|
434
|
+
|
435
|
+
file_info
|
436
|
+
end
|
437
|
+
|
438
|
+
##
|
439
|
+
# Removes file extensions known to be unparseable from +files+ and TAGS
|
440
|
+
# files for emacs and vim.
|
441
|
+
|
442
|
+
def remove_unparseable files
|
443
|
+
files.reject do |file, *|
|
444
|
+
file =~ /\.(?:class|eps|erb|scpt\.txt|svg|ttf|yml)$/i or
|
445
|
+
(file =~ /tags$/i and
|
446
|
+
File.open(file, 'rb') { |io|
|
447
|
+
io.read(100) =~ /\A(\f\n[^,]+,\d+$|!_TAG_)/
|
448
|
+
})
|
449
|
+
end
|
450
|
+
end
|
451
|
+
|
452
|
+
##
|
453
|
+
# Generates documentation or a coverage report depending upon the settings
|
454
|
+
# in +options+.
|
455
|
+
#
|
456
|
+
# +options+ can be either an RDoc::Options instance or an array of strings
|
457
|
+
# equivalent to the strings that would be passed on the command line like
|
458
|
+
# <tt>%w[-q -o doc -t My\ Doc\ Title]</tt>. #document will automatically
|
459
|
+
# call RDoc::Options#finish if an options instance was given.
|
460
|
+
#
|
461
|
+
# For a list of options, see either RDoc::Options or <tt>rdoc --help</tt>.
|
462
|
+
#
|
463
|
+
# By default, output will be stored in a directory called "doc" below the
|
464
|
+
# current directory, so make sure you're somewhere writable before invoking.
|
465
|
+
|
466
|
+
def document options
|
467
|
+
self.store = RDoc::Store.new
|
468
|
+
|
469
|
+
if RDoc::Options === options then
|
470
|
+
@options = options
|
471
|
+
@options.finish
|
472
|
+
else
|
473
|
+
@options = load_options
|
474
|
+
@options.parse options
|
475
|
+
end
|
476
|
+
|
477
|
+
if @options.pipe then
|
478
|
+
handle_pipe
|
479
|
+
exit
|
480
|
+
end
|
481
|
+
|
482
|
+
unless @options.coverage_report then
|
483
|
+
@last_modified = setup_output_dir @options.op_dir, @options.force_update
|
484
|
+
end
|
485
|
+
|
486
|
+
@store.encoding = @options.encoding
|
487
|
+
@store.dry_run = @options.dry_run
|
488
|
+
@store.main = @options.main_page
|
489
|
+
@store.title = @options.title
|
490
|
+
@store.path = @options.op_dir
|
491
|
+
|
492
|
+
@start_time = Time.now
|
493
|
+
|
494
|
+
@store.load_cache
|
495
|
+
|
496
|
+
file_info = parse_files @options.files
|
497
|
+
|
498
|
+
@options.default_title = "RDoc Documentation"
|
499
|
+
|
500
|
+
@store.complete @options.visibility
|
501
|
+
|
502
|
+
@stats.coverage_level = @options.coverage_report
|
503
|
+
|
504
|
+
if @options.coverage_report then
|
505
|
+
puts
|
506
|
+
|
507
|
+
puts @stats.report.accept RDoc::Markup::ToRdoc.new
|
508
|
+
elsif file_info.empty? then
|
509
|
+
$stderr.puts "\nNo newer files." unless @options.quiet
|
510
|
+
else
|
511
|
+
gen_klass = @options.generator
|
512
|
+
|
513
|
+
@generator = gen_klass.new @store, @options
|
514
|
+
|
515
|
+
generate
|
516
|
+
end
|
517
|
+
|
518
|
+
if @stats and (@options.coverage_report or not @options.quiet) then
|
519
|
+
puts
|
520
|
+
puts @stats.summary.accept RDoc::Markup::ToRdoc.new
|
521
|
+
end
|
522
|
+
|
523
|
+
exit @stats.fully_documented? if @options.coverage_report
|
524
|
+
end
|
525
|
+
|
526
|
+
##
|
527
|
+
# Generates documentation for +file_info+ (from #parse_files) into the
|
528
|
+
# output dir using the generator selected
|
529
|
+
# by the RDoc options
|
530
|
+
|
531
|
+
def generate
|
532
|
+
if @options.dry_run then
|
533
|
+
# do nothing
|
534
|
+
@generator.generate
|
535
|
+
else
|
536
|
+
Dir.chdir @options.op_dir do
|
537
|
+
unless @options.quiet then
|
538
|
+
$stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
|
539
|
+
end
|
540
|
+
|
541
|
+
@generator.generate
|
542
|
+
update_output_dir '.', @start_time, @last_modified
|
543
|
+
end
|
544
|
+
end
|
545
|
+
end
|
546
|
+
|
547
|
+
##
|
548
|
+
# Removes a siginfo handler and replaces the previous
|
549
|
+
|
550
|
+
def remove_siginfo_handler
|
551
|
+
return unless Signal.list.key? 'INFO'
|
552
|
+
|
553
|
+
handler = @old_siginfo || 'DEFAULT'
|
554
|
+
|
555
|
+
trap 'INFO', handler
|
556
|
+
end
|
557
|
+
|
558
|
+
end
|
559
|
+
|
560
|
+
begin
|
561
|
+
require 'rubygems'
|
562
|
+
|
563
|
+
rdoc_extensions = Gem.find_files 'rdoc/discover'
|
564
|
+
|
565
|
+
rdoc_extensions.each do |extension|
|
566
|
+
begin
|
567
|
+
load extension
|
568
|
+
rescue => e
|
569
|
+
warn "error loading #{extension.inspect}: #{e.message} (#{e.class})"
|
570
|
+
warn "\t#{e.backtrace.join "\n\t"}" if $DEBUG
|
571
|
+
end
|
572
|
+
end
|
573
|
+
rescue LoadError
|
574
|
+
end
|
575
|
+
|
576
|
+
# require built-in generators after discovery in case they've been replaced
|
577
|
+
require_relative 'generator/darkfish'
|
578
|
+
require_relative 'generator/ri'
|
579
|
+
require_relative 'generator/pot'
|