From d81b7a80ae147d653e9e8dabdc0671fdf8ac3883 Mon Sep 17 00:00:00 2001 From: Magnus Holm Date: Tue, 4 Aug 2009 01:59:59 +0200 Subject: [PATCH] Combine the docs into a single template/formatter --- Rakefile | 44 ++----------- extras/rdoc/generator/book.rb | 44 ------------- extras/rdoc/generator/singledarkfish.rb | 55 +++++++++++++--- .../generator/template/flipbook/book.rhtml | 12 ++-- .../template/flipbook/classpage.rhtml | 0 .../template/flipbook/filepage.rhtml | 0 .../generator/template/flipbook/index.rhtml | 62 ------------------- .../generator/template/flipbook/readme.rhtml | 31 ++++++++++ .../template/flipbook/reference.rhtml | 10 +-- 9 files changed, 92 insertions(+), 166 deletions(-) delete mode 100644 extras/rdoc/generator/book.rb delete mode 100644 extras/rdoc/generator/template/flipbook/classpage.rhtml delete mode 100644 extras/rdoc/generator/template/flipbook/filepage.rhtml delete mode 100644 extras/rdoc/generator/template/flipbook/index.rhtml create mode 100644 extras/rdoc/generator/template/flipbook/readme.rhtml diff --git a/Rakefile b/Rakefile index cacd255..78a8e9b 100644 --- a/Rakefile +++ b/Rakefile @@ -16,10 +16,7 @@ REV = `#{GIT} rev-list HEAD`.strip.split.length VERS = ENV['VERSION'] || (REV.zero? ? BRANCH : [BRANCH, REV] * '.') CLEAN.include ['**/.*.sw?', '*.gem', '.config', 'test/test.log', '.*.pt'] -RDOC_OPTS = ['--title', "Camping, a Microframework", - "--line-numbers", - "--quiet", - "--main", "README"] +RDOC_OPTS = ["--line-numbers", "--quiet", "--main", "README"] ## Packaging spec = @@ -73,10 +70,9 @@ require 'rdoc' if defined?(RDoc::VERSION) && RDoc::VERSION[0,3] == "2.4" require 'rdoc/generator/singledarkfish' - require 'rdoc/generator/book' require 'rdoctask' - - Camping::RDocTask.new(:rdoc) do |rdoc| + + Camping::RDocTask.new(:docs) do |rdoc| rdoc.before_running_rdoc do mv "lib/camping.rb", "lib/camping-mural.rb" mv "lib/camping-unabridged.rb", "lib/camping.rb" @@ -87,41 +83,11 @@ if defined?(RDoc::VERSION) && RDoc::VERSION[0,3] == "2.4" mv "lib/camping-mural.rb", "lib/camping.rb" end - rdoc.rdoc_dir = 'doc/api' - rdoc.options += ['-f', 'singledarkfish', *RDOC_OPTS] - rdoc.template = "flipbook" - rdoc.title = "Camping, the Reference" - rdoc.rdoc_files.add ['lib/camping.rb', 'lib/camping/**/*.rb'] - end - - Camping::RDocTask.new(:readme) do |rdoc| rdoc.rdoc_dir = 'doc' - rdoc.options += RDOC_OPTS + rdoc.options += ['-f', 'singledarkfish', *RDOC_OPTS] rdoc.template = "flipbook" rdoc.title = "Camping, a Microframework" - rdoc.rdoc_files.add ['README'] - end - - Camping::RDocTask.new(:book) do |rdoc| - rdoc.rdoc_dir = 'doc/book' - rdoc.options += ['-f', 'book', *RDOC_OPTS] - rdoc.template = "flipbook" - rdoc.title = "Camping, the Book" - rdoc.rdoc_files.add ['book/*'] - end - - desc "Build full documentation." - task :docs => [:readme, :rdoc, :book] - desc "Rebuild full documentation." - task :redocs => [:rereadme, :rerdoc, :rebook] - desc "Remove full documentation." - task :clobber_docs => [:clobber_readme, :clobber_rdoc, :clobber_book] - - %w(docs redocs clobber_docs).each do |task_name| - task = Rake::Task[task_name] - task.prerequisites.each do |pre| - Rake::Task[pre].instance_eval { @comment = nil } - end + rdoc.rdoc_files.add ['README', 'lib/camping.rb', 'lib/camping/**/*.rb', 'book/*'] end task :rubygems_docs do diff --git a/extras/rdoc/generator/book.rb b/extras/rdoc/generator/book.rb deleted file mode 100644 index 4bae42e..0000000 --- a/extras/rdoc/generator/book.rb +++ /dev/null @@ -1,44 +0,0 @@ -class RDoc::Generator::Book < RDoc::Generator::SingleDarkfish - RDoc::RDoc.add_generator(self) - - def index_template - 'book.rhtml' - end - - def chapters - @chapters ||= @files.each do |file| - (class << file; self; end).class_eval { attr_accessor :title, :content, :toc, :id } - file.toc = [] - file.content = convert(file) - - file.content.gsub!(%r{

(.*?)

}) do - file.title = $1 - file.id = make_id($1) - '

%s

' % [file.id, file.title] - end - - file.content.gsub!(%r{

(.*?)

}) do |match| - arr = [file.id + '-' + make_id($1), $1] - file.toc << arr - '

%s

' % arr - end - end - end - - def convert(file) - case File.extname(file.relative_name) - when '.rdoc', '' - file.description - when '.markdown', '.md' - require 'rdiscount' - RDiscount.new(file.comment).to_html - when '.textile' - require 'redcloth' - RedCloth.new(file.comment).to_html - end - end - - def make_id(title) - title.downcase.gsub(/\s/, '-').gsub(/[^\w-]+/, '') - end -end diff --git a/extras/rdoc/generator/singledarkfish.rb b/extras/rdoc/generator/singledarkfish.rb index 55e4e99..d819ee7 100644 --- a/extras/rdoc/generator/singledarkfish.rb +++ b/extras/rdoc/generator/singledarkfish.rb @@ -2,7 +2,7 @@ # vim: noet ts=2 sts=8 sw=2 require 'rubygems' -gem 'rdoc', '>= 2.4' unless defined? $rdoc_rakefile +gem 'rdoc', '>= 2.4' require 'pp' require 'pathname' @@ -122,10 +122,10 @@ def file_dir '#file-' end - def index_template - 'reference.rhtml' + def template(name) + "#{name}.rhtml" end - + ### Build the initial indices and output objects ### based on an array of TopLevel objects containing ### the extracted information. @@ -137,17 +137,20 @@ def generate( top_levels ) @methods = @classes.map { |m| m.method_list }.flatten.sort @modsort = get_sorted_module_list( @classes ) - # Now actually write the output - generate_index + # Now actually write the output + write_style_sheet + generate_thing(:readme, 'index.html') + generate_thing(:reference, 'api.html') + generate_thing(:book, 'book.html') rescue StandardError => err debug_msg "%s: %s\n %s" % [ err.class.name, err.message, err.backtrace.join("\n ") ] raise end - def generate_index - debug_msg "Rendering the index page..." + def generate_thing(name, to) + debug_msg "Rendering #{name}..." - templatefile = @template_dir + index_template + templatefile = @template_dir + template(name) template_src = templatefile.read template = ERB.new( template_src, nil, '<>' ) template.filename = templatefile.to_s @@ -165,7 +168,9 @@ def generate_index ], err.backtrace end - outfile = @basedir + @options.op_dir + 'index.html' + outfile = @basedir + @options.op_dir + to + FileUtils.mkdir_p(File.dirname(outfile)) + unless $dryrun debug_msg "Outputting to %s" % [outfile.expand_path] outfile.open( 'w', 0644 ) do |fh| @@ -175,6 +180,36 @@ def generate_index debug_msg "Would have output to %s" % [outfile.expand_path] end end + + ## For book.rhtml + + def chapters + @chapters ||= @files.select do |file| + next unless file.full_name =~ /^book\// + + (class << file; self; end).class_eval { attr_accessor :title, :content, :toc, :id } + file.toc = [] + file.content = file.description + + file.content.gsub!(%r{

(.*?)

}) do + file.title = $1 + file.id = make_id($1) + '

%s

' % [file.id, file.title] + end + + file.content.gsub!(%r{

(.*?)

}) do |match| + arr = [file.id + '-' + make_id($1), $1] + file.toc << arr + '

%s

' % arr + end + + true + end + end + + def make_id(title) + title.downcase.gsub(/\s/, '-').gsub(/[^\w-]+/, '') + end end # Roc::Generator::SingleDarkfish # :stopdoc: \ No newline at end of file diff --git a/extras/rdoc/generator/template/flipbook/book.rhtml b/extras/rdoc/generator/template/flipbook/book.rhtml index 8cef51f..ebd1a7f 100644 --- a/extras/rdoc/generator/template/flipbook/book.rhtml +++ b/extras/rdoc/generator/template/flipbook/book.rhtml @@ -2,15 +2,15 @@ <%= @options.title %> - - - + + +