Class: Docurium
- Inherits:
-
Object
- Object
- Docurium
- Defined in:
- lib/docurium/cli.rb,
lib/docurium/cparser.rb,
lib/docurium/version.rb,
lib/docurium/docparser.rb,
lib/docurium.rb
Defined Under Namespace
Classes: CLI, CParser, DocParser
Constant Summary collapse
- Version =
VERSION = '0.4.2'
Instance Attribute Summary collapse
-
#branch ⇒ Object
Returns the value of attribute branch.
-
#data ⇒ Object
Returns the value of attribute data.
-
#output_dir ⇒ Object
Returns the value of attribute output_dir.
Instance Method Summary collapse
- #format_examples!(data, version) ⇒ Object
- #generate_doc_for(version) ⇒ Object
- #generate_docs ⇒ Object
- #get_versions ⇒ Object
- #init_data(version = 'HEAD') ⇒ Object
-
#initialize(config_file, repo = nil) ⇒ Docurium
constructor
A new instance of Docurium.
- #option_version(version, option, default = nil) ⇒ Object
- #parse_headers(index, version) ⇒ Object
- #show_warnings(data) ⇒ Object
Constructor Details
#initialize(config_file, repo = nil) ⇒ Docurium
Returns a new instance of Docurium.
22 23 24 25 26 27 |
# File 'lib/docurium.rb', line 22 def initialize(config_file, repo = nil) raise "You need to specify a config file" if !config_file raise "You need to specify a valid config file" if !valid_config(config_file) @sigs = {} @repo = repo || Rugged::Repository.discover('.') end |
Instance Attribute Details
#branch ⇒ Object
Returns the value of attribute branch.
20 21 22 |
# File 'lib/docurium.rb', line 20 def branch @branch end |
#data ⇒ Object
Returns the value of attribute data.
20 21 22 |
# File 'lib/docurium.rb', line 20 def data @data end |
#output_dir ⇒ Object
Returns the value of attribute output_dir.
20 21 22 |
# File 'lib/docurium.rb', line 20 def output_dir @output_dir end |
Instance Method Details
#format_examples!(data, version) ⇒ Object
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/docurium.rb', line 48 def format_examples!(data, version) examples = [] if ex = option_version(version, 'examples') if subtree = find_subtree(version, ex) # check that it exists index = Rugged::Index.new index.read_tree(subtree) files = [] index.each do |entry| next unless entry[:path].match(/\.c$/) files << entry[:path] end files.each do |file| # highlight, roccoize and link rocco = Rocco.new(file, files, {:language => 'c'}) do ientry = index[file] blob = @repo.lookup(ientry[:oid]) blob.content end extlen = -(File.extname(file).length + 1) rf_path = file[0..extlen] + '.html' rel_path = "ex/#{version}/#{rf_path}" rocco_layout = Rocco::Layout.new(rocco, @tf) # find out how deep our file is so we can use the right # number of ../ in the path depth = rel_path.count('/') - 1 if depth == 0 rocco_layout[:dirsup] = "./" else rocco_layout[:dirsup] = "../"*depth end rocco_layout.version = version rf = rocco_layout.render # look for function names in the examples and link id_num = 0 data[:functions].each do |f, fdata| rf.gsub!(/#{f}([^\w])/) do |fmatch| extra = $1 id_num += 1 name = f + '-' + id_num.to_s # save data for cross-link data[:functions][f][:examples] ||= {} data[:functions][f][:examples][file] ||= [] data[:functions][f][:examples][file] << rel_path + '#' + name "<a name=\"#{name}\" class=\"fnlink\" href=\"../../##{version}/group/#{fdata[:group]}/#{f}\">#{f}</a>#{extra}" end end # write example to the repo sha = @repo.write(rf, :blob) examples << [rel_path, sha] data[:examples] ||= [] data[:examples] << [file, rel_path] end end end examples end |
#generate_doc_for(version) ⇒ Object
115 116 117 118 119 120 |
# File 'lib/docurium.rb', line 115 def generate_doc_for(version) index = Rugged::Index.new read_subtree(index, version, option_version(version, 'input', '')) data = parse_headers(index, version) data end |
#generate_docs ⇒ Object
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
# File 'lib/docurium.rb', line 122 def generate_docs output_index = Rugged::Index.new write_site(output_index) @tf = File.(File.join(File.dirname(__FILE__), 'docurium', 'layout.mustache')) versions = get_versions versions << 'HEAD' nversions = versions.size output = Queue.new pipes = {} versions.each do |version| # We don't need to worry about joining since this process is # going to die immediately read, write = IO.pipe pid = Process.fork do read.close data = generate_doc_for(version) examples = format_examples!(data, version) Marshal.dump([version, data, examples], write) write.close end pipes[pid] = read write.close end print "Generating documentation [0/#{nversions}]\r" head_data = nil # This may seem odd, but we need to keep reading from the pipe or # the buffer will fill and they'll block and never exit. Therefore # we can't rely on Process.wait to tell us when the work is # done. Instead read from all the pipes concurrently and send the # ruby objects through the queue. Thread.abort_on_exception = true pipes.each do |pid, read| Thread.new do result = read.read output << Marshal.load(result) end end for i in 1..nversions version, data, examples = output.pop # There's still some work we need to do serially tally_sigs!(version, data) sha = @repo.write(data.to_json, :blob) print "Generating documentation [#{i}/#{nversions}]\r" # Store it so we can show it at the end if version == 'HEAD' head_data = data end output_index.add(:path => "#{version}.json", :oid => sha, :mode => 0100644) examples.each do |path, id| output_index.add(:path => path, :oid => id, :mode => 0100644) end if head_data puts '' show_warnings(data) end end # We tally the sigantures in the order they finished, which is # arbitrary due to the concurrency, so we need to sort them once # they've finsihed. sort_sigs! project = { :versions => versions.reverse, :github => @options['github'], :name => @options['name'], :signatures => @sigs, } sha = @repo.write(project.to_json, :blob) output_index.add(:path => "project.json", :oid => sha, :mode => 0100644) css = File.read(File.(File.join(File.dirname(__FILE__), 'docurium', 'css.css'))) sha = @repo.write(css, :blob) output_index.add(:path => "ex/css.css", :oid => sha, :mode => 0100644) br = @options['branch'] out "* writing to branch #{br}" refname = "refs/heads/#{br}" tsha = output_index.write_tree(@repo) puts "\twrote tree #{tsha}" ref = @repo.references[refname] user = { :name => @repo.config['user.name'], :email => @repo.config['user.email'], :time => Time.now } = {} [:tree] = tsha [:author] = user [:committer] = user [:message] = 'generated docs' [:parents] = ref ? [ref.target] : [] [:update_ref] = refname csha = Rugged::Commit.create(@repo, ) puts "\twrote commit #{csha}" puts "\tupdated #{br}" end |
#get_versions ⇒ Object
254 255 256 257 258 259 |
# File 'lib/docurium.rb', line 254 def get_versions releases = @repo. .map { |tag| tag.name.gsub(%r(^refs/tags/), '') } .delete_if { |tagname| tagname.match(%r(-rc\d*$)) } VersionSorter.sort(releases) end |
#init_data(version = 'HEAD') ⇒ Object
29 30 31 32 33 |
# File 'lib/docurium.rb', line 29 def init_data(version = 'HEAD') data = {:files => [], :functions => {}, :callbacks => {}, :globals => {}, :types => {}, :prefix => ''} data[:prefix] = option_version(version, 'input', '') data end |
#option_version(version, option, default = nil) ⇒ Object
35 36 37 38 39 40 41 42 43 44 45 46 |
# File 'lib/docurium.rb', line 35 def option_version(version, option, default = nil) if @options['legacy'] if valhash = @options['legacy'][option] valhash.each do |value, versions| return value if versions.include?(version) end end end opt = @options[option] opt = default if !opt opt end |
#parse_headers(index, version) ⇒ Object
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 |
# File 'lib/docurium.rb', line 261 def parse_headers(index, version) headers = index.map { |e| e[:path] }.grep(/\.h$/) files = headers.map do |file| [file, @repo.lookup(index[file][:oid]).content] end data = init_data(version) parser = DocParser.new headers.each do |header| records = parser.parse_file(header, files) update_globals!(data, records) end data[:groups] = group_functions!(data) data[:types] = data[:types].sort # make it an assoc array find_type_usage!(data) data end |
#show_warnings(data) ⇒ Object
228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 |
# File 'lib/docurium.rb', line 228 def show_warnings(data) out '* checking your api' # check for unmatched paramaters unmatched = [] data[:functions].each do |f, fdata| unmatched << f if fdata[:comments] =~ /@param/ end if unmatched.size > 0 out ' - unmatched params in' unmatched.sort.each { |p| out ("\t" + p) } end # check for changed signatures sigchanges = [] @sigs.each do |fun, data| if data[:changes]['HEAD'] sigchanges << fun end end if sigchanges.size > 0 out ' - signature changes in' sigchanges.sort.each { |p| out ("\t" + p) } end end |