From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-2.7 required=3.0 tests=ALL_TRUSTED,AWL,BAYES_00, URIBL_BLOCKED shortcircuit=no autolearn=unavailable version=3.3.2 X-Original-To: olddoc-public@80x24.org Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 42FAA1F716; Thu, 7 Jan 2016 03:37:51 +0000 (UTC) Date: Thu, 7 Jan 2016 03:37:51 +0000 From: Eric Wong To: olddoc-public@80x24.org Subject: [PATCH 5/4] nodoc some internals Message-ID: <20160107033751.GA22955@dcvr.yhbt.net> References: <20160107013636.9998-1-e@80x24.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20160107013636.9998-1-e@80x24.org> List-Id: We don't want to advertise an API we'd have to support long-term --- lib/olddoc.rb | 4 ++-- lib/olddoc/gemspec.rb | 2 +- lib/olddoc/history.rb | 2 +- lib/olddoc/merge.rb | 2 +- lib/olddoc/news_atom.rb | 2 +- lib/olddoc/news_rdoc.rb | 2 +- lib/olddoc/prepare.rb | 2 +- lib/olddoc/readme.rb | 2 +- lib/oldweb.rb | 52 +++++++++++++++++++++++++++---------------------- lib/rdoc/discover.rb | 2 ++ 10 files changed, 40 insertions(+), 32 deletions(-) diff --git a/lib/olddoc.rb b/lib/olddoc.rb index 1621f85..d9bc384 100644 --- a/lib/olddoc.rb +++ b/lib/olddoc.rb @@ -1,7 +1,7 @@ # Copyright (C) 2015-2016 all contributors # License: GPL-3.0+ -module Olddoc - VERSION = '1.1.2' +module Olddoc # :nodoc: + VERSION = '1.1.2' # :nodoc: autoload :Gemspec, 'olddoc/gemspec' autoload :History, 'olddoc/history' diff --git a/lib/olddoc/gemspec.rb b/lib/olddoc/gemspec.rb index f5f008d..f9f6417 100644 --- a/lib/olddoc/gemspec.rb +++ b/lib/olddoc/gemspec.rb @@ -1,7 +1,7 @@ # Copyright (C) 2015-2016 all contributors # License: GPL-3.0+ # helper methods for gemspecs -module Olddoc::Gemspec +module Olddoc::Gemspec # :nodoc: include Olddoc::Readme def extra_rdoc_files(manifest) diff --git a/lib/olddoc/history.rb b/lib/olddoc/history.rb index 595994d..dcdf0fe 100644 --- a/lib/olddoc/history.rb +++ b/lib/olddoc/history.rb @@ -2,7 +2,7 @@ # License: GPL-3.0+ require 'uri' -module Olddoc::History +module Olddoc::History # :nodoc: def initialize_history @tags = @old_summaries = nil end diff --git a/lib/olddoc/merge.rb b/lib/olddoc/merge.rb index b5dae65..de5e2ae 100644 --- a/lib/olddoc/merge.rb +++ b/lib/olddoc/merge.rb @@ -1,7 +1,7 @@ # Copyright (C) 2015-2016 all contributors # License: GPL-3.0+ -class Olddoc::Merge +class Olddoc::Merge # :nodoc: def initialize(opts) @merge_html = opts["merge_html"] || {} end diff --git a/lib/olddoc/news_atom.rb b/lib/olddoc/news_atom.rb index a093e64..a9e8002 100644 --- a/lib/olddoc/news_atom.rb +++ b/lib/olddoc/news_atom.rb @@ -2,7 +2,7 @@ # License: GPL-3.0+ require 'builder' -module Olddoc::NewsAtom +module Olddoc::NewsAtom # :nodoc: include Olddoc::History include Olddoc::Readme diff --git a/lib/olddoc/news_rdoc.rb b/lib/olddoc/news_rdoc.rb index e8c6a34..2427591 100644 --- a/lib/olddoc/news_rdoc.rb +++ b/lib/olddoc/news_rdoc.rb @@ -4,7 +4,7 @@ # require 'tempfile' -module Olddoc::NewsRdoc +module Olddoc::NewsRdoc # :nodoc: include Olddoc::History def puts_tag(fp, tag) diff --git a/lib/olddoc/prepare.rb b/lib/olddoc/prepare.rb index f42bd04..f902fff 100644 --- a/lib/olddoc/prepare.rb +++ b/lib/olddoc/prepare.rb @@ -2,7 +2,7 @@ # License: GPL-3.0+ require 'uri' -class Olddoc::Prepare +class Olddoc::Prepare # :nodoc: include Olddoc::NewsRdoc include Olddoc::NewsAtom include Olddoc::Readme diff --git a/lib/olddoc/readme.rb b/lib/olddoc/readme.rb index 423d18b..0b3ee97 100644 --- a/lib/olddoc/readme.rb +++ b/lib/olddoc/readme.rb @@ -2,7 +2,7 @@ # License: GPL-3.0+ # helpers for parsing the top-level README file -module Olddoc::Readme +module Olddoc::Readme # :nodoc: def readme_path 'README' diff --git a/lib/oldweb.rb b/lib/oldweb.rb index af62050..a5da1cc 100644 --- a/lib/oldweb.rb +++ b/lib/oldweb.rb @@ -8,11 +8,15 @@ require 'yaml' require 'cgi' require 'uri' +# oldweb is an \RDoc template and not intended as a programming API. +# You may specify it as an \RDoc formatter: +# +# rdoc -f oldweb ... class Oldweb - RDoc::RDoc.add_generator(self) - include ERB::Util - attr_reader :class_dir - attr_reader :file_dir + RDoc::RDoc.add_generator(self) # :nodoc: + include ERB::Util # :nodoc: + attr_reader :class_dir # :nodoc: + attr_reader :file_dir # :nodoc: # description of the generator DESCRIPTION = 'minimal HTML generator' @@ -20,7 +24,7 @@ class Oldweb # version of this generator VERSION = '1' - def initialize(store, options) + def initialize(store, options) # :nodoc: # 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. @@ -76,7 +80,7 @@ class Oldweb end end - def generate + def generate # :nodoc: setup generate_class_files generate_file_files @@ -90,13 +94,13 @@ class Oldweb end if src end - def rel_path(out_file) + def rel_path(out_file) # :nodoc: rel_prefix = @outputdir.relative_path_from(out_file.dirname) rel_prefix.to_s == '.' ? '' : "#{rel_prefix}/" end # called standalone by servelet - def generate_class(klass, template_file = nil) + def generate_class(klass, template_file = nil) # :nodoc: setup current = klass template_file ||= @template_dir + 'class.rhtml' @@ -108,7 +112,7 @@ class Oldweb end # Generate a documentation file for each class and module - def generate_class_files + def generate_class_files # :nodoc: setup template_file = @template_dir + 'class.rhtml' current = nil @@ -122,7 +126,7 @@ class Oldweb end # Generate a documentation file for each file - def generate_file_files + def generate_file_files # :nodoc: setup @files.each do |file| generate_page(file) if file.text? @@ -130,7 +134,7 @@ class Oldweb end # Generate a page file for +file+ - def generate_page(file, out_file = @outputdir + file.path) + def generate_page(file, out_file = @outputdir + file.path) # :nodoc: setup template_file = @template_dir + 'page.rhtml' rel_prefix = rel_path(out_file) @@ -152,7 +156,7 @@ class Oldweb end # Generates the 404 page for the RDoc servlet - def generate_servlet_not_found(message) + def generate_servlet_not_found(message) # :nodoc: setup template_file = @template_dir + 'servlet_not_found.rhtml' rel_prefix = '' @@ -164,7 +168,7 @@ class Oldweb end # Generates the servlet root page for the RDoc servlet - def generate_servlet_root(installed) + def generate_servlet_root(installed) # :nodoc: setup template_file = @template_dir + 'servlet_root.rhtml' @@ -178,7 +182,7 @@ class Oldweb e!(e, "error generating servlet_root: #{e.message} (#{e.class})") end - def generate_table_of_contents + def generate_table_of_contents # :nodoc: setup template_file = @template_dir + 'table_of_contents.rhtml' out_file = @outputdir + 'table_of_contents.html' @@ -190,7 +194,7 @@ class Oldweb e!(e, "error generating table_of_contents.html: #{e.message} (#{e.class})") end - def setup + def setup # :nodoc: return if @outputdir @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir) return unless @store @@ -201,7 +205,7 @@ class Oldweb end # Creates a template from its components and the +body_file+. - def assemble_template(body_file) + def assemble_template(body_file) # :nodoc: body = body_file.read head = @template_dir + '_head.rhtml' tail = @template_dir + '_tail.rhtml' @@ -211,7 +215,7 @@ class Oldweb # 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) + def render(file_name) # :nodoc: template_file = @template_dir + file_name template = template_for(template_file, false, RDoc::ERBPartial) template.filename = template_file.to_s @@ -222,7 +226,7 @@ class Oldweb # 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 + def render_template(template_file, out_file = nil) # :nodoc: io_output = out_file && !@dry_run && @file_output erb_klass = io_output ? RDoc::ERBIO : ERB template = template_for(template_file, true, erb_klass) @@ -242,14 +246,14 @@ class Oldweb # 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) + def template_result(template, context, template_file) # :nodoc: 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) + def template_for(file, page = true, klass = ERB) # :nodoc: template = @template_cache[file] return template if template @@ -268,11 +272,11 @@ class Oldweb @template_cache[file] = template end - def e!(e, msg) + def e!(e, msg) # :nodoc: raise RDoc::Error, msg, e.backtrace end - def method_srclink(m) + def method_srclink(m) # :nodoc: url = @old_vcs_url or return "" line = m.line or return "" path = URI.escape(m.file_name) @@ -280,7 +284,7 @@ class Oldweb end # reach into RDoc internals to generate less HTML - module LessHtml + module LessHtml # :nodoc: def accept_verbatim(verbatim) @res << "\n
#{CGI.escapeHTML(verbatim.text.rstrip)}
\n" end @@ -296,8 +300,10 @@ class Oldweb end end +# :stopdoc: class RDoc::Markup::ToHtml # :nodoc: remove_method :accept_heading remove_method :accept_verbatim include Oldweb::LessHtml end +# :startdoc: diff --git a/lib/rdoc/discover.rb b/lib/rdoc/discover.rb index e497514..9450f42 100644 --- a/lib/rdoc/discover.rb +++ b/lib/rdoc/discover.rb @@ -1,5 +1,7 @@ +# :stopdoc: begin gem 'rdoc', '~> 4.1' require_relative '../olddoc' rescue Gem::LoadError end unless defined?(Olddoc) +# :startdoc: -- EW