docrb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74814d0dca672ec2099fcb9092660f198b93ccb3b454979201ad18be4db5fb25
-  data.tar.gz: 34660996e9148eebe8a1757f04f0be4c2f19300d9de1fd43f793e3d7e97502c6
+  metadata.gz: 6f0802ce2c22dc5e953086dc6a7ceb943f2698123aa218b84ffe0c12979cf6d8
+  data.tar.gz: e6ffe294b8f3ca2aea65b8a29295c69597241a7369356e48a655dcc4267da2ff
 SHA512:
-  metadata.gz: 6f53696d60c6bf4634dd2c2fe093c24a786b1f6cd9e87432a73e8ca4c5298d2f9c868cd8b8640dbd65bfc67b130272d2708ea6e7cdd01da142da33278dae0625
-  data.tar.gz: a98ca47316bdc564de37a6144dfa8613f49717313d7dee5424ce5feca10f6e91f80353a0078233461d3f6dd4202ce0ecb3635ef6641326b3e325f28b6234562c
+  metadata.gz: a5186508c23d6da130f52ca66e704f049c9545ac486faf0da9f93bd72620d5139a4e9835955e419062cbd4a2eeb29c417523253c27e74927a7a29408b151588f
+  data.tar.gz: 8d8c70b0bcacfedea85f401abd53901c3b1835ceadcfc9f8f089a1fef74ec6f1dcb83cc5fb83983f76fc9e9db6c9d8087472717e096099c5f85c2ecb93e677e0

data/.rubocop.yml

@@ -1,8 +1,7 @@
 AllCops:
   TargetRubyVersion: 3.2
+  SuggestExtensions: false
   NewCops: enable
-  Exclude:
-    - spec/**/*
 
 Style/StringLiterals:
   Enabled: true
@@ -12,59 +11,50 @@ Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
-Style/Documentation:
-  Exclude:
-    - lib/docrb/module_extensions.rb
-
 Layout/LineLength:
   Max: 120
-  Exclude:
-    - exe/*
-    - lib/docrb/comment_parser.rb
-    - lib/docrb/ruby_parser.rb
 
-Metrics/ClassLength:
-  Enabled: false
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
 
-Metrics/MethodLength:
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/Documentation:
   Enabled: false
 
-Naming/MethodParameterName:
-  Exclude:
-    - spec/**/*
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent_relative_to_receiver
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Style/EmptyCaseCondition:
+  Enabled: false
 
 Metrics/BlockLength:
-  Exclude:
-    - exe/*
-    - lib/docrb/ruby_parser.rb
+  Enabled: false
 
-Metrics/PerceivedComplexity:
-  Exclude:
-    - exe/*
-    - lib/docrb/doc_compiler/base_container.rb
-    - lib/docrb/doc_compiler/base_container/computations.rb
-    - lib/docrb/doc_compiler/object_container.rb
-    - lib/docrb/resolvable.rb
-    - lib/docrb/ruby_parser.rb
+Metrics/ClassLength:
+  Enabled: false
 
-Metrics/CyclomaticComplexity:
-  Exclude:
-    - exe/*
-    - lib/docrb/doc_compiler/base_container.rb
-    - lib/docrb/doc_compiler/base_container/computations.rb
-    - lib/docrb/doc_compiler/object_container.rb
-    - lib/docrb/resolvable.rb
-    - lib/docrb/ruby_parser.rb
-
-Lint/ShadowingOuterLocalVariable:
-  Exclude:
-    - exe/*
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
 
 Metrics/AbcSize:
   Enabled: false
 
-Metrics/ModuleLength:
+Metrics/CyclomaticComplexity:
   Enabled: false
 
-Lint/BooleanSymbol:
+Metrics/PerceivedComplexity:
   Enabled: false

data/Gemfile

@@ -2,6 +2,10 @@
 
 source "https://rubygems.org"
 
+gem "docrb-html", path: "../docrb-html"
+
+gem "docrb-parser", path: "../docrb-parser"
+
 # Specify your gem's dependencies in docrb.gemspec
 gemspec
 
@@ -10,7 +14,7 @@ group :development do
 
   gem "rspec", "~> 3.0"
 
-  gem "rubocop", "~> 1.8"
+  gem "rubocop", "~> 1.21"
 
   gem "byebug"
 

data/Gemfile.lock

@@ -1,11 +1,24 @@
 PATH
-  remote: .
+  remote: ../docrb-html
   specs:
-    docrb (0.2.0)
-      docrb-html (~> 0.2)
-      parser (~> 3.2)
+    docrb-html (0.3.0)
+      nokogiri (~> 1.14)
       redcarpet (~> 3.6)
       rouge (~> 4.1)
+      sassc (~> 2.4)
+
+PATH
+  remote: ../docrb-parser
+  specs:
+    docrb-parser (0.1.0)
+      prism (~> 0.13)
+
+PATH
+  remote: .
+  specs:
+    docrb (0.3.0)
+      docrb-html (~> 0.3)
+      docrb-parser (~> 0.1)
 
 GEM
   remote: https://rubygems.org/
@@ -14,25 +27,23 @@ GEM
     awesome_print (1.9.2)
     byebug (11.1.3)
     diff-lcs (1.5.0)
-    docrb-html (0.2.5)
-      nokogiri (~> 1.14)
-      sassc (~> 2.4)
-    ffi (1.15.5)
+    ffi (1.16.3)
     json (2.6.3)
-    nokogiri (1.14.2-arm64-darwin)
+    nokogiri (1.15.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.14.2-x86_64-darwin)
+    nokogiri (1.15.4-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.22.1)
     parser (3.2.1.0)
       ast (~> 2.4.1)
-    racc (1.6.2)
+    prism (0.14.0)
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
     redcarpet (3.6.0)
     regexp_parser (2.7.0)
     rexml (3.2.5)
-    rouge (4.1.0)
+    rouge (4.2.0)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -65,15 +76,19 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  arm64-darwin-23
   x86_64-darwin-20
+  x86_64-darwin-22
 
 DEPENDENCIES
   awesome_print
   byebug
   docrb!
+  docrb-html!
+  docrb-parser!
   rake (~> 13.0)
   rspec (~> 3.0)
-  rubocop (~> 1.8)
+  rubocop (~> 1.21)
 
 BUNDLED WITH
    2.2.22

data/docrb.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/trunk/lib/docrb"
   spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
@@ -25,9 +26,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "docrb-html", "~> 0.2"
-  spec.add_dependency "parser", "~> 3.2"
-  spec.add_dependency "redcarpet", "~> 3.6"
-  spec.add_dependency "rouge", "~> 4.1"
-  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.add_dependency "docrb-html", "~> 0.3"
+  spec.add_dependency "docrb-parser", "~> 0.1"
 end

data/exe/docrb

@@ -7,12 +7,11 @@ require "fileutils"
 require "optparse"
 require "open3"
 require "tmpdir"
-require "renderer"
 
 require "docrb"
 
-def exec(cmd, *args, **kwargs)
-  _, stdout_and_err, wait_thread = Open3.popen2e(cmd, *args, **kwargs)
+def exec(cmd, *, **)
+  _, stdout_and_err, wait_thread = Open3.popen2e(cmd, *, **)
   status = wait_thread.value
   {
     code: status.exitstatus,
@@ -20,57 +19,55 @@ def exec(cmd, *args, **kwargs)
   }
 end
 
-def git(*args, **kwargs)
-  exec("git", *args, **kwargs)
-end
-
-def render_html(*args, **kwargs)
-  exec("docrb-html", *args, **kwargs)
-end
+def git(*, **) = exec("git", *, **)
 
 def run
   options = {}
-  opts = OptionParser.new do |opts|
-    opts.banner = "Usage: bin/docrb [options] [input directory] [output directory]"
-    gemspec_info = "When omitted, Docrb attempts to extract information from a .gemspec file in the provided input directory."
+  opts = OptionParser.new do |opt|
+    opt.banner = "Usage: bin/docrb [options] [input directory] [output directory]"
+    gemspec_info = "When omitted, Docrb attempts to extract information from " \
+                   "a .gemspec file in the provided input directory."
 
-    opts.on("--help", "Prints this help") do
-      puts opts
+    opt.on("--help", "Prints this help") do
+      puts opt
       exit
     end
 
-    opts.on("-bPATH", "--base=PATH",
-            "Base directory to search for source files. Defaults to the provided input directory.") do |b|
+    opt.on("-bPATH", "--base=PATH",
+      "Base directory to search for source files. Defaults to the provided input directory.") do |b|
       options[:base] = b
     end
 
-    opts.on("-rPATH", "--readme=PATH",
-            "Path for README.md file. When omitted, Docrb searches for a README.md file in the provided input directory.") do |r|
+    opt.on("-rPATH", "--readme=PATH",
+      "Path for README.md file. When omitted, Docrb searches for a README.md " \
+      "file in the provided input directory.") do |r|
       options[:readme] = r
     end
 
-    opts.on("-nNAME", "--name=NAME", "Name of the project being documented. #{gemspec_info}") do |n|
+    opt.on("-nNAME", "--name=NAME", "Name of the project being documented. #{gemspec_info}") do |n|
       options[:name] = n
     end
 
-    opts.on("-sSUMMARY", "--summary=SUMMARY", "Short summary of the project being documented. #{gemspec_info}") do |d|
+    opt.on("-sSUMMARY", "--summary=SUMMARY", "Short summary of the project being documented. #{gemspec_info}") do |d|
       options[:summary] = d
     end
 
-    opts.on("-hURL", "--host=URL", "URL for the gem's hosted URL. #{gemspec_info}") do |u|
+    opt.on("-hURL", "--host=URL", "URL for the gem's hosted URL. #{gemspec_info}") do |u|
       options[:host_url] = u
     end
 
-    opts.on("-gURL", "--git-repo=URL",
-            "URL for the repository containing the documented project. When omitted, Docrb attempts to extract this information from the .git directory present in the provided input directory, if any.") do |u|
+    opt.on("-gURL", "--git-repo=URL",
+      "URL for the repository containing the documented project. When " \
+      "omitted, Docrb attempts to extract this information from the " \
+      ".git directory present in the provided input directory, if any.") do |u|
       options[:git_url] = u
     end
 
-    opts.on("--authors a,b,c", "List of name of project authors. #{gemspec_info}") do |list|
+    opt.on("--authors a,b,c", "List of name of project authors. #{gemspec_info}") do |list|
       options[:authors] = list
     end
 
-    opts.on("-lLICENSE", "--license=LICENSE", "The project's license. #{gemspec_info}") do |license|
+    opt.on("-lLICENSE", "--license=LICENSE", "The project's license. #{gemspec_info}") do |license|
       options[:license] = license
     end
   end
@@ -104,10 +101,6 @@ def run
     end
   end
 
-  tmp_output = Dir.mktmpdir
-  data_path = File.join(tmp_output, "data.json")
-  markdown_path = File.join(tmp_output, "readme.html")
-  metadata_path = File.join(tmp_output, "metadata.json")
   readme_path = File.join(input, "README.md")
   base_path = input
 
@@ -119,7 +112,16 @@ def run
     end
   end
 
-  spec = Docrb::Spec.parse_folder(input) || {}
+  if options[:base]
+    path = File.join(input, options[:base])
+    unless File.exist? path
+      puts "--base was provided, but #{path} does not exist."
+      exit(1)
+    end
+    base_path = path
+  end
+
+  source, spec = Docrb.parse_folder(base_path, input)
 
   %i[name summary host_url git_url authors license].each do |k|
     spec[k] = options[k] if options.key? k
@@ -131,25 +133,17 @@ def run
   end
 
   if spec[:summary] == "" || spec[:summary].nil?
-    puts "Docrb could not detect the project's summary. Please check your .gemspec, or provide one manually using --summary."
+    puts "Docrb could not detect the project's summary. Please check your " \
+         ".gemspec, or provide one manually using --summary."
     exit(1)
   end
 
-  if options[:base]
-    path = File.join(input, options[:base])
-    unless File.exist? path
-      puts "--base was provided, but #{path} does not exist."
-      exit(1)
-    end
-    base_path = path
-  end
-
   git_tip = nil
   git_root = nil
   git_status = git("status", "--porcelain", chdir: input)
   if (git_status[:code]).zero?
     if git_status[:output].length.positive?
-      puts "WARNING: Your local git copy seems to be dirty. Consider commiting your changes before generating docs."
+      puts "WARNING: Your local git copy seems to be dirty. Consider committing your changes before generating docs."
     end
     tip_data = git("rev-parse", "HEAD", chdir: input)
     if tip_data[:code] != 0
@@ -179,27 +173,15 @@ def run
   spec[:timestamp] = Time.now.utc.strftime("%A, %d %b %Y %l:%M %p GMT")
   spec[:version] = Docrb::VERSION
 
-  data = Docrb.parse_folder(base_path)
-  compiler = Docrb::DocCompiler.new
-  data.each { |f| compiler.append(f) }
-
-  File.write(data_path, compiler.to_h.to_json)
-  puts "Created: #{data_path}"
-
   if File.exist? readme_path
-    puts "Found #{readme_path}"
     md = File.read(readme_path).to_s
-    result = Docrb::Markdown.render(md)
-    File.write(markdown_path, result)
-    puts "Created #{markdown_path}"
+    spec[:readme] = md
   else
     puts "#{readme_path} does not exist. Skipping..."
   end
-  File.write(metadata_path, spec.to_json)
-  puts "Created #{metadata_path}"
 
-  puts "Generating HTML into #{output}"
-  Renderer.new(tmp_output, output).render
+  compiler = Docrb::DocCompiler.new(source, spec, output)
+  compiler.run!
 end
 
 run

data/lib/docrb/doc_compiler.rb

@@ -1,55 +1,15 @@
 # frozen_string_literal: true
 
 module Docrb
-  # DocCompiler implements utilities to post-process documentation data
-  # generated by RubyParser.
-  class DocCompiler < Resolvable
-    autoload :FileRef, "docrb/doc_compiler/file_ref"
-    autoload :BaseContainer, "docrb/doc_compiler/base_container"
-    autoload :DocClass, "docrb/doc_compiler/doc_class"
-    autoload :DocModule, "docrb/doc_compiler/doc_module"
-    autoload :DocMethod, "docrb/doc_compiler/doc_method"
-    autoload :DocAttribute, "docrb/doc_compiler/doc_attribute"
-    autoload :ObjectContainer, "docrb/doc_compiler/object_container"
-    autoload :DocBlocks, "docrb/doc_compiler/doc_blocks"
-
-    attr_reader :classes, :modules, :methods, :parent
-
-    def initialize
-      super
-      @classes = ObjectContainer.new(self, DocClass)
-      @modules = ObjectContainer.new(self, DocModule)
-      @methods = ObjectContainer.new(self, DocMethod)
-      @parent = nil
-    end
-
-    # Appends a given object to the compiler collection. Raises ArgumentError in
-    # case the object cannot be appended to the current container.
-    #
-    # obj - Object to be appended
-    def append(obj)
-      filename = obj[:filename]
-      target = case obj[:type]
-               when :module
-                 @modules
-               when :class
-                 @classes
-               when :def, :defs
-                 @methods
-               end
-
-      raise ArgumentError, "cannot append obj of type #{obj[:type]}" if target.nil?
-
-      target.push(filename, obj)
+  class DocCompiler
+    def initialize(source, spec, output)
+      @source = source
+      @spec = spec
+      @output = output
     end
 
-    # Transforms the content's of the parser into a Hash representation
-    def to_h
-      {
-        modules: @modules.map(&:to_h),
-        classes: @classes.map(&:to_h),
-        methods: @methods.map(&:to_h)
-      }
+    def run!
+      Renderer.new(@source, @spec, @output).render
     end
   end
 end

data/lib/docrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docrb
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/docrb.rb

@@ -1,71 +1,32 @@
 # frozen_string_literal: true
 
-require "parser/current"
-require "forwardable"
 require "json"
-require "redcarpet"
-require "rouge"
-require "rouge/plugins/redcarpet"
 require "rubygems"
 
-Parser::Builders::Default.emit_lambda              = true
-Parser::Builders::Default.emit_procarg0            = true
-Parser::Builders::Default.emit_encoding            = true
-Parser::Builders::Default.emit_index               = true
-Parser::Builders::Default.emit_arg_inside_procarg0 = true
-Parser::Builders::Default.emit_forward_arg         = true
-Parser::Builders::Default.emit_kwargs              = true
-Parser::Builders::Default.emit_match_pattern       = true
+require "docrb-html"
+require "docrb-parser"
 
-require_relative "docrb/version"
-require_relative "docrb/ruby_parser"
-require_relative "docrb/module_extensions"
+require_relative "docrb/spec"
+require_relative "docrb/doc_compiler"
 
 # Docrb implements a source and documentation parser for Ruby projects
 module Docrb
   # Error class from which all other Docrb errors derive from
   class Error < StandardError; end
 
-  autoload :CommentParser, "docrb/comment_parser"
-  autoload :DocCompiler, "docrb/doc_compiler"
-  autoload :Resolvable, "docrb/resolvable"
-  autoload :Markdown, "docrb/markdown"
-  autoload :Spec, "docrb/spec"
-
-  # Public: Parses a single file under a provided path
-  #
-  # path - Path to the file to be parsed
-  #
-  # Returns an object representing the parsed source and documentation
-  def self.parse(path)
-    inst = RubyParser.new(path)
-    inst.parse
-    inst
-  end
-
-  # Public: Parses a given input folder recursivelly and returns all sources
+  # Public: Parses a given input folder recursively and returns all sources
   # and documentations
   #
-  # inp - Folder to be parsed. Finds all .rb files recursivelly from this path.
+  # inp - Folder to be parsed. Finds all .rb files recursively from this path.
   #
-  # Returns an array with all parsed files
-  def self.parse_folder(inp)
-    output = []
-    Dir["#{inp}/**/*.rb"].each do |f|
-      inst = parse(f)
-      inst.classes.each do |c|
-        c[:filename] = f
-        output << c
-      end
-      inst.modules.each do |c|
-        c[:filename] = f
-        output << c
-      end
-      inst.methods.each do |c|
-        c[:filename] = f
-        output << c
-      end
-    end
-    output
+  # Returns a NodeArray with parsed nodes.
+  def self.parse_folder(base, input)
+    source = Docrb::Parser
+      .new
+      .tap { |parser| Dir["#{base}/**/*.rb"].each { parser.parse(_1) } }
+      .tap(&:finalize)
+    spec = Spec.parse_folder(input)
+
+    [source, spec]
   end
 end