olddoc 1.0.0

data/lib/olddoc/news_atom.rb

@@ -0,0 +1,51 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+require 'builder'
+
+module Olddoc::NewsAtom
+  include Olddoc::History
+  include Olddoc::Readme
+
+  # generates an Atom feed based on git tags in the document directory
+  def news_atom_xml
+    project_name, short_desc, _ = readme_metadata
+    new_tags = tags[0,10]
+    atom_uri = @rdoc_uri.dup
+    atom_uri.path += "NEWS.atom.xml"
+    news_uri = @rdoc_uri.dup
+    news_uri.path += "NEWS.html"
+    x = Builder::XmlMarkup.new
+    x.feed(xmlns: "http://www.w3.org/2005/Atom") do
+      x.id(atom_uri.to_s)
+      x.title("#{project_name} news")
+      x.subtitle(short_desc)
+      x.link(rel: 'alternate', type: 'text/html', href: news_uri.to_s)
+      x.updated(new_tags.empty? ? '1970-01-01:00:00:00Z' : new_tags[0][:time])
+      new_tags.each do |tag|
+        x.entry do
+          x.title(tag[:subject])
+          x.updated(tag[:time])
+          x.published(tag[:time])
+          x.author do
+            x.name(tag[:tagger_name])
+            x.email(tag[:tagger_email])
+          end
+          uri = tag_uri(tag[:tag]).to_s
+          x.link(rel: "alternate", type: 'text/html', href: uri)
+          x.id(uri)
+          x.content(type: :xhtml) { x.pre(tag[:body]) }
+        end # entry
+      end # new_tags
+    end # feed
+    [ x.target!, new_tags ]
+  end
+
+  def news_atom(dest = "NEWS.atom.xml")
+    xml, new_tags = news_atom_xml
+    File.open(dest, "w") { |fp| fp.write(xml) }
+    unless new_tags.empty?
+      time = new_tags[0][:ruby_time]
+      File.utime(time, time, dest)
+    end
+  end
+end

data/lib/olddoc/news_rdoc.rb

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+require 'tempfile'
+
+module Olddoc::NewsRdoc
+  include Olddoc::History
+
+  def puts_tag(fp, tag)
+    time = tag[:time].tr('T', ' ').gsub!(/:\d\dZ/, ' UTC')
+    fp.puts "=== #{tag[:subject]} / #{time}"
+    fp.puts ""
+
+    body = tag[:body]
+    fp.puts tag[:body].gsub(/^/smu, "  ").gsub(/[ \t]+$/smu, "")
+    fp.puts ""
+  end
+
+  # generates a NEWS file in the top-level directory based on git tags
+  def news_rdoc
+    news = Tempfile.new('NEWS', '.')
+    tags.each { |tag| puts_tag(news, tag) }
+    File.open("LATEST", "wb") { |latest|
+      if tags.empty?
+        latest.puts "Currently unreleased"
+        news.puts "No news yet."
+      else
+        puts_tag(latest, tags[0])
+      end
+    }
+    news.chmod(0666 & ~File.umask)
+    File.rename(news.path, 'NEWS')
+    news.close!
+  end
+end

data/lib/olddoc/prepare.rb

@@ -0,0 +1,24 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+require 'uri'
+class Olddoc::Prepare
+  include Olddoc::NewsRdoc
+  include Olddoc::NewsAtom
+  include Olddoc::Readme
+
+  def initialize(opts)
+    rdoc_url = opts['rdoc_url']
+    cgit_url = opts['cgit_url']
+    rdoc_url && cgit_url or
+      abort "rdoc_url and cgit_url required in .olddoc.yml for `prepare'"
+    @rdoc_uri = URI.parse(rdoc_url)
+    @cgit_uri = URI.parse(cgit_url)
+    @name, @short_desc = readme_metadata
+  end
+
+  def run
+    news_rdoc
+    news_atom
+  end
+end

data/lib/olddoc/readme.rb

@@ -0,0 +1,27 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# helpers for parsing the top-level README file
+module Olddoc::Readme
+
+  def readme_path
+    'README'
+  end
+
+  # returns a one-paragraph summary from the README
+  def readme_description
+    File.read(readme_path).split(/\n\n/)[1]
+  end
+
+  # parses the README file in the top-level directory for project metadata
+  def readme_metadata
+    l = File.readlines(readme_path)[0].strip!
+    l.gsub!(/^=\s+/, '') or abort "#{l.inspect} doesn't start with '='"
+    title = l.dup
+    if l.gsub!(/^(\w+\!)\s+/, '') # Rainbows!
+      return $1, l, title
+    else
+      return (l.split(/\s*[:-]\s*/, 2)).push(title)
+    end
+  end
+end

data/lib/oldweb.rb

@@ -0,0 +1,303 @@
+# Copyright (C) 2015, all contributors <olddoc-public@80x24.org>
+# License: GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.txt)
+# Loosely derived from Darkfish in the main rdoc distribution
+require 'rdoc'
+require 'erb'
+require 'pathname'
+require 'yaml'
+require 'cgi'
+require 'uri'
+
+class Oldweb
+  RDoc::RDoc.add_generator(self)
+  include ERB::Util
+  attr_reader :class_dir
+  attr_reader :file_dir
+
+  # description of the generator
+  DESCRIPTION = 'minimal HTML generator'
+
+  # version of this generator
+  VERSION = '1'
+
+  def initialize(store, options)
+    # just because we're capable of generating UTF-8 to get human names
+    # right does not mean we should overuse it for quotation marks and such,
+    # our clients may not have the necessary fonts.
+    RDoc::Text::TO_HTML_CHARACTERS[Encoding::UTF_8] =
+      RDoc::Text::TO_HTML_CHARACTERS[Encoding::ASCII]
+
+    @store = store
+    @options = options
+    @base_dir = Pathname.pwd.expand_path
+    @dry_run = options.dry_run
+    @file_output = true
+    @template_dir = Pathname.new(File.join(File.dirname(__FILE__), 'oldweb'))
+    @template_cache = {}
+    @classes = nil
+    @context = nil
+    @files = nil
+    @methods = nil
+    @modsort = nil
+    @class_dir = nil
+    @file_dir = nil
+    @outputdir = nil
+    @old_vcs_url = nil
+    @git_tag = nil
+
+    # olddoc-specific stuff
+    # infer title from README
+    if options.title == 'RDoc Documentation' && File.readable?('README')
+      line = File.open('README') { |fp| fp.gets.strip }
+      line.sub!(/\A=+\s*/, '')
+      options.title = line
+    end
+
+    # load olddoc config
+    cfg = '.olddoc.yml'
+    if File.readable?(cfg)
+      @old_cfg = YAML.load(File.read(cfg))
+    else
+      @old_cfg = {}
+      warn "#{cfg} not readable"
+    end
+    %w(toc_max).each { |k| v = @old_cfg[k] and @old_cfg[k] = v.to_i }
+    @old_cfg['toc_max'] ||= 6
+
+    ni = {}
+    noindex = @old_cfg['noindex'] and noindex.each { |k| ni[k] = true }
+    @old_cfg['noindex'] = ni
+
+    if cgit_url = @old_cfg['cgit_url']
+      cgit_url += '/tree/%s' # path name
+      tag = @git_tag and cgit_url << "id=#{URI.escape(tag)}"
+      cgit_url << '#n%d' # lineno
+      @old_vcs_url = cgit_url
+    end
+  end
+
+  def generate
+    setup
+    generate_class_files
+    generate_file_files
+    generate_table_of_contents
+    src = Dir["#@outputdir/README*.html"].first
+    begin
+      dst = "#@outputdir/index.html"
+      File.link(src, dst)
+    rescue SystemCallError
+      IO.copy_stream(src, dst)
+    end if src
+  end
+
+  def rel_path(out_file)
+    rel_prefix = @outputdir.relative_path_from(out_file.dirname)
+    rel_prefix == '.' ? '' : "#{rel_prefix}/"
+  end
+
+  # called standalone by servelet
+  def generate_class(klass, template_file = nil)
+    setup
+    current = klass
+    template_file ||= @template_dir + 'class.rhtml'
+    out_file = @outputdir + klass.path
+    rel_prefix = rel_path(out_file)
+    @title = "#{klass.type} #{klass.full_name}"
+    @suppress_warning = [ rel_prefix, current ]
+    render_template(template_file, out_file) { |io| binding }
+  end
+
+  # Generate a documentation file for each class and module
+  def generate_class_files
+    setup
+    template_file = @template_dir + 'class.rhtml'
+    current = nil
+
+    @classes.each do |klass|
+      current = klass
+      generate_class(klass, template_file)
+    end
+  rescue => e
+    e!(e, "error generating #{current.path}: #{e.message} (#{e.class})")
+  end
+
+  # Generate a documentation file for each file
+  def generate_file_files
+    setup
+    @files.each do |file|
+      generate_page(file) if file.text?
+    end
+  end
+
+  # Generate a page file for +file+
+  def generate_page(file, out_file = @outputdir + file.path)
+    setup
+    template_file = @template_dir + 'page.rhtml'
+    rel_prefix = rel_path(out_file)
+    current = file
+
+    @title = "#{file.page_name} - #{@options.title}"
+
+    # use the first header as title instead of page_name if there is one
+    File.open("#{@options.root}/#{file.absolute_name}") do |f|
+      line = f.gets.strip
+      line.sub!(/^=+\s*/, '') and @title = line
+    end
+
+    @suppress_warning = [ current, rel_prefix ]
+
+    render_template(template_file, out_file) { |io| binding }
+  rescue => e
+    e!(e, "error generating #{out_file}: #{e.message} (#{e.class})")
+  end
+
+  # Generates the 404 page for the RDoc servlet
+  def generate_servlet_not_found(message)
+    setup
+    template_file = @template_dir + 'servlet_not_found.rhtml'
+    rel_prefix = ''
+    @suppress_warning = rel_prefix
+    @title = 'Not Found'
+    render_template(template_file) { |io| binding }
+  rescue => e
+    e!(e, "error generating servlet_not_found: #{e.message} (#{e.class})")
+  end
+
+  # Generates the servlet root page for the RDoc servlet
+  def generate_servlet_root(installed)
+    setup
+
+    template_file = @template_dir + 'servlet_root.rhtml'
+
+    rel_prefix = ''
+    @suppress_warning = rel_prefix
+
+    @title = 'Local RDoc Documentation'
+    render_template(template_file) { |io| binding }
+  rescue => e
+    e!(e, "error generating servlet_root: #{e.message} (#{e.class})")
+  end
+
+  def generate_table_of_contents
+    setup
+    template_file = @template_dir + 'table_of_contents.rhtml'
+    out_file = @outputdir + 'table_of_contents.html'
+    rel_prefix = rel_path(out_file)
+    @suppress_warning = rel_prefix
+    @title = "Table of Contents - #{@options.title}"
+    render_template(template_file, out_file) { |io| binding }
+  rescue => e
+    e!(e, "error generating table_of_contents.html: #{e.message} (#{e.class})")
+  end
+
+  def setup
+    return if @outputdir
+    @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
+    return unless @store
+    @classes = @store.all_classes_and_modules.sort
+    @files = @store.all_files.sort
+    @methods = @classes.map(&:method_list).flatten.sort
+    @modsort = @classes.select(&:display?).sort
+  end
+
+  # Creates a template from its components and the +body_file+.
+  def assemble_template(body_file)
+    body = body_file.read
+    head = @template_dir + '_head.rhtml'
+    tail = @template_dir + '_tail.rhtml'
+    "<html><head>#{head.read.strip}</head><body\n" \
+      "id=\"top\">#{body.strip}#{tail.read.strip}</body></html>"
+  end
+
+  # Renders the ERb contained in +file_name+ relative to the template
+  # directory and returns the result based on the current context.
+  def render(file_name)
+    template_file = @template_dir + file_name
+    template = template_for(template_file, false, RDoc::ERBPartial)
+    template.filename = template_file.to_s
+    template.result(@context)
+  end
+
+  # Load and render the erb template in the given +template_file+ and write
+  # it out to +out_file+.
+  # Both +template_file+ and +out_file+ should be Pathname-like objects.
+  # An io will be yielded which must be captured by binding in the caller.
+  def render_template(template_file, out_file = nil) # :yield: io
+    io_output = out_file && !@dry_run && @file_output
+    erb_klass = io_output ? RDoc::ERBIO : ERB
+    template = template_for(template_file, true, erb_klass)
+
+    if io_output
+      out_file.dirname.mkpath
+      out_file.open('w', 0644) do |io|
+        io.set_encoding(@options.encoding)
+        @context = yield io
+        template_result(template, @context, template_file)
+      end
+    else
+      @context = yield nil
+      template_result(template, @context, template_file)
+    end
+  end
+
+  # Creates the result for +template+ with +context+.  If an error is raised a
+  # Pathname +template_file+ will indicate the file where the error occurred.
+  def template_result(template, context, template_file)
+    template.filename = template_file.to_s
+    template.result(context)
+  rescue NoMethodError => e
+    e!(e, "Error while evaluating #{template_file.expand_path}: #{e.message}")
+  end
+
+  def template_for(file, page = true, klass = ERB)
+    template = @template_cache[file]
+
+    return template if template
+
+    if page
+      template = assemble_template(file)
+      erbout = 'io'
+    else
+      template = file.read
+      template = template.encode(@options.encoding)
+      file_var = File.basename(file).sub(/\..*/, '')
+      erbout = "_erbout_#{file_var}"
+    end
+
+    template = klass.new(template, nil, '<>', erbout)
+    @template_cache[file] = template
+  end
+
+  def e!(e, msg)
+    raise RDoc::Error, msg, e.backtrace
+  end
+
+  def method_srclink(m)
+    url = @old_vcs_url or return ""
+    line = m.line or return ""
+    path = URI.escape(m.file_name)
+    %Q(<a href="#{url % [ path, line ]}">source</a>)
+  end
+
+  # reach into RDoc internals to generate less HTML
+  module LessHtml
+    def accept_verbatim(verbatim)
+      @res << "\n<pre>#{CGI.escapeHTML(verbatim.text.rstrip)}</pre>\n"
+    end
+
+    def accept_heading(heading)
+      level = [6, heading.level].min
+      label = heading.label(@code_object)
+      @res << "<h#{level}"
+      @res << (@options.output_decoration ? "\nid=\"#{label}\">" : ">")
+      @res << to_html(heading.text)
+      @res << "</h#{level}>"
+    end
+  end
+end
+
+class RDoc::Markup::ToHtml # :nodoc:
+  remove_method :accept_heading
+  remove_method :accept_verbatim
+  include Oldweb::LessHtml
+end

data/lib/oldweb/_head.rhtml

@@ -0,0 +1,7 @@
+<meta charset="<%= @options.charset %>"><title><%= h @title %></title><%
+if rdoc_url = @old_cfg['rdoc_url'] %><link
+rel="alternate"
+title="Atom feed"
+href="<%= rdoc_url %>NEWS.atom.xml"
+type="application/atom+xml" /><%
+end %>