docrb 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74814d0dca672ec2099fcb9092660f198b93ccb3b454979201ad18be4db5fb25
+  data.tar.gz: 34660996e9148eebe8a1757f04f0be4c2f19300d9de1fd43f793e3d7e97502c6
+SHA512:
+  metadata.gz: 6f53696d60c6bf4634dd2c2fe093c24a786b1f6cd9e87432a73e8ca4c5298d2f9c868cd8b8640dbd65bfc67b130272d2708ea6e7cdd01da142da33278dae0625
+  data.tar.gz: a98ca47316bdc564de37a6144dfa8613f49717313d7dee5424ce5feca10f6e91f80353a0078233461d3f6dd4202ce0ecb3635ef6641326b3e325f28b6234562c

data/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+tab_width = 8
+trim_trailing_whitespace = true
+
+[*.gemspec]
+indent_size = 2
+
+[*.rb]
+indent_size = 2
+
+[*.yml]
+indent_size = 2
+
+[./bin/*]
+indent_size = 2

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,70 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - spec/**/*
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+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
+
+Metrics/MethodLength:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Exclude:
+    - spec/**/*
+
+Metrics/BlockLength:
+  Exclude:
+    - exe/*
+    - lib/docrb/ruby_parser.rb
+
+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/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/AbcSize:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Lint/BooleanSymbol:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in docrb.gemspec
+gemspec
+
+group :development do
+  gem "rake", "~> 13.0"
+
+  gem "rspec", "~> 3.0"
+
+  gem "rubocop", "~> 1.8"
+
+  gem "byebug"
+
+  gem "awesome_print"
+end

data/Gemfile.lock

@@ -0,0 +1,79 @@
+PATH
+  remote: .
+  specs:
+    docrb (0.2.0)
+      docrb-html (~> 0.2)
+      parser (~> 3.2)
+      redcarpet (~> 3.6)
+      rouge (~> 4.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    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)
+    json (2.6.3)
+    nokogiri (1.14.2-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.14.2-x86_64-darwin)
+      racc (~> 1.4)
+    parallel (1.22.1)
+    parser (3.2.1.0)
+      ast (~> 2.4.1)
+    racc (1.6.2)
+    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)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.45.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.26.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.11.0)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  arm64-darwin-22
+  x86_64-darwin-20
+
+DEPENDENCIES
+  awesome_print
+  byebug
+  docrb!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.8)
+
+BUNDLED WITH
+   2.2.22

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "docrb"
+require "byebug"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/json

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "docrb"
+require "byebug"
+require "json"
+
+def run
+  data = Docrb.parse_folder(ARGV[0])
+  compiler = Docrb::DocCompiler.new
+  data.each { |f| compiler.append(f) }
+  puts compiler.to_h.to_json
+end
+
+run

data/bin/md

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "docrb"
+
+data = File.read(ARGV[0]).to_s
+puts Docrb::Markdown.render(data)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docrb.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/docrb/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "docrb"
+  spec.version       = Docrb::VERSION
+  spec.authors       = ["Victor Gama"]
+  spec.email         = ["hey@vito.io"]
+
+  spec.summary       = "An opinionated documentation parser"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/heyvito/docrb"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/trunk/lib/docrb"
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  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"
+end

data/exe/docrb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "json"
+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)
+  status = wait_thread.value
+  {
+    code: status.exitstatus,
+    output: stdout_and_err.read.chomp
+  }
+end
+
+def git(*args, **kwargs)
+  exec("git", *args, **kwargs)
+end
+
+def render_html(*args, **kwargs)
+  exec("docrb-html", *args, **kwargs)
+end
+
+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.on("--help", "Prints this help") do
+      puts opts
+      exit
+    end
+
+    opts.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|
+      options[:readme] = r
+    end
+
+    opts.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|
+      options[:summary] = d
+    end
+
+    opts.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|
+      options[:git_url] = u
+    end
+
+    opts.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|
+      options[:license] = license
+    end
+  end
+
+  opts.parse!
+
+  if ARGV.length != 2
+    puts opts
+    exit(1)
+  end
+
+  input = ARGV[0]
+  output = ARGV[1]
+
+  unless File.exist? input
+    puts "#{input}: Does not exist"
+    exit(1)
+  end
+
+  if File.exist? output
+    unless File.directory? output
+      puts "#{output}: Exists and is not a directory."
+      exit(1)
+    end
+  else
+    begin
+      FileUtils.mkdir_p output
+    rescue StandardError => e
+      puts e
+      exit(1)
+    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
+
+  if options[:readme]
+    readme_path = options[:readme]
+    unless File.exist? readme_path
+      puts "--readme was provided, but #{readme_path} could not be found."
+      exit(1)
+    end
+  end
+
+  spec = Docrb::Spec.parse_folder(input) || {}
+
+  %i[name summary host_url git_url authors license].each do |k|
+    spec[k] = options[k] if options.key? k
+  end
+
+  if spec[:name] == "" || spec[:name].nil?
+    puts "Docrb could not detect the project name. Please check your .gemspec, or provide one manually using --name."
+    exit(1)
+  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."
+    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."
+    end
+    tip_data = git("rev-parse", "HEAD", chdir: input)
+    if tip_data[:code] != 0
+      puts "ERROR: Acquiring repository information failed:"
+      puts tip_data[:output]
+      puts "------- 8< cut here"
+      puts "Aborting."
+      exit 1
+    end
+    toplevel = git("rev-parse", "--show-toplevel", chdir: input)
+    if toplevel[:code] != 0
+      puts "ERROR: Acquiring repository toplevel failed:"
+      puts tip_data[:output]
+      puts "------- 8< cut here"
+      puts "Aborting."
+      exit 1
+    end
+
+    git_tip = tip_data[:output]
+    git_root = toplevel[:output]
+  else
+    puts "git status returned status #{git_status[:code]}; avoiding git..."
+  end
+
+  spec[:git_tip] = git_tip if git_tip
+  spec[:git_root] = git_root if git_root
+  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}"
+  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
+end
+
+run

data/lib/docrb/comment_parser/code_example_block.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Docrb
+  class CommentParser
+    # CodeExampleBlock represents a list of characters of a code example
+    class CodeExampleBlock
+      attr_reader :code
+
+      def initialize
+        @code = []
+      end
+
+      def <<(text_block)
+        @code << "\n" unless empty?
+        @code << text_block.text
+      end
+
+      def empty?
+        @code.empty?
+      end
+
+      def normalize
+        @code
+          .map { |txt| txt.split("\n") }
+          .map { |item| item.empty? ? "" : item }
+          .flatten
+          .map { |line| line.gsub(/^\s{2}/, "") }
+          .join("\n")
+      end
+
+      def to_h
+        { type: :code_example, contents: normalize }
+      end
+    end
+  end
+end

data/lib/docrb/comment_parser/code_example_parser.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Docrb
+  class CommentParser
+    # CodeExampleParser attempts to extract code examples from a documentation
+    # block.
+    class CodeExampleParser
+      def self.process(components)
+        new_components = []
+        code_example_group = CodeExampleBlock.new
+        components.each do |c|
+          if !c.is_a?(TextBlock) || !c.text.start_with?("  ")
+            unless code_example_group.empty?
+              new_components << code_example_group
+              code_example_group = CodeExampleBlock.new
+            end
+            new_components << c
+            next
+          end
+
+          code_example_group << c
+        end
+
+        new_components << code_example_group unless code_example_group.empty?
+        new_components
+      end
+    end
+  end
+end

data/lib/docrb/comment_parser/field_block.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Docrb
+  class CommentParser
+    # FieldBlock represents a list of fields obtained by FieldListParser
+    class FieldBlock
+      attr_reader :fields
+
+      def initialize(fields)
+        @fields = fields
+      end
+
+      def to_h
+        { type: :field_block, contents: fields }
+      end
+    end
+  end
+end

data/lib/docrb/comment_parser/field_list_parser.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Docrb
+  class CommentParser
+    # FieldListParser parses a field block (representing arguments of an method,
+    # for instance) into a specialised structure.
+    class FieldListParser
+      FIELD_FORMAT_REGEXP = /^([a-z_][0-9a-z_]*:?)\s+- /i
+
+      def initialize(text)
+        @text = text
+        @data = []
+        @current = []
+        @result = {}
+        @dash_index = nil
+      end
+
+      def detect
+        @text.each_char do |c|
+          next @current << c unless c == LINE_BREAK
+          return false unless handle_linebreak
+        end
+        return false unless handle_linebreak
+
+        flush_current_field!
+        true
+      end
+
+      def handle_linebreak
+        return true if @current.empty?
+
+        # Here's a linebreak. Handle it as needed.
+        @current = @current.join
+        if infer_field_alignment(@current)
+          flush_current_field!
+          @data << @current
+        else
+          # This is not a field. May be a continuation.
+          # Can it be a continuation?
+          return false if @data.empty?
+
+          # Yep. It may be. Is it?
+          return false unless continuation?(@current)
+
+          # It is. Append to data.
+          @data << @current.strip
+        end
+        @current = []
+        true
+      end
+
+      def flush_current_field!
+        return if @data.empty?
+
+        data = @data.join(" ")
+        @data = []
+        field_name = FIELD_FORMAT_REGEXP.match(data)[1]
+        text = data.slice(@dash_index + 1...).strip
+        @result[field_name] = text
+      end
+
+      def continuation?(line)
+        return false unless @dash_index
+
+        # until dash_index, we should have spaces
+        return false if line.length < @dash_index
+
+        return false unless line.slice(0..@dash_index + 1).strip.empty?
+
+        true
+      end
+
+      def infer_field_alignment(line)
+        # is the line a field?
+        return false unless FIELD_FORMAT_REGEXP.match?(line)
+
+        if @dash_index
+          # does it match the same alignment?
+          return false if line[@dash_index] != DASH
+        else
+          @dash_index = line.index(DASH)
+        end
+
+        true
+      end
+
+      attr_reader :result
+    end
+  end
+end