yard-markdown 0.7.0 → 0.7.2

data/Rakefile

@@ -1,196 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "open3"
-require "shellwords"
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-require_relative "test/support/markdown_validator"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
-end
-
-task default: %i[test stree:write]
-
-TYPES_OUTPUT_PATH = "sig/yard/markdown.rbs"
-
-def shell_escape(path)
-  Shellwords.escape(path)
-end
-
-COMMAND_WARNING_REGEX = /\bwarning:/i
-COMMAND_ERROR_REGEX = /\b(?:error|exception|fatal|loaderror)\b/i
-
-def analyze_command_output(text)
-  lines = text.each_line.map(&:strip).reject(&:empty?)
-  {
-    warnings: lines.grep(COMMAND_WARNING_REGEX),
-    errors: lines.grep(COMMAND_ERROR_REGEX)
-  }
-end
-
-def command_log_path(label)
-  safe_label = label.gsub(%r{[^a-zA-Z0-9_-]+}, "_")
-  File.join("tmp", "command-logs", "#{safe_label}.log")
-end
-
-def run_command_with_analysis(command, label:)
-  puts command
-
-  stdout, stderr, status = Open3.capture3(command)
-  combined_output = [stdout, stderr].reject(&:empty?).join("\n")
-  log_path = command_log_path(label)
-
-  FileUtils.mkdir_p(File.dirname(log_path))
-  File.write(log_path, combined_output)
-
-  puts combined_output unless combined_output.empty?
-
-  stdout_analysis = analyze_command_output(stdout)
-  stderr_analysis = analyze_command_output(stderr)
-  combined_analysis = {
-    warnings: stdout_analysis[:warnings] + stderr_analysis[:warnings],
-    errors: stdout_analysis[:errors] + stderr_analysis[:errors]
-  }
-
-  puts "Output analysis for #{label}: warnings=#{combined_analysis[:warnings].size}, errors=#{combined_analysis[:errors].size}"
-
-  return if status.success? && combined_analysis[:errors].empty?
-
-  details = ["#{label} failed output checks (log: #{log_path})"]
-  details << "exit status: #{status.exitstatus}" unless status.success?
-  details << "errors: #{combined_analysis[:errors].first(5).join(' | ')}" unless combined_analysis[:errors].empty?
-  raise details.join("\n")
-end
-
-def generate_markdown_docs(source, output_dir)
-  FileUtils.rm_rf(output_dir)
-  FileUtils.mkdir_p(output_dir)
-
-  command = "yardoc --no-stats --quiet --format markdown --load ./lib/yard-markdown.rb --output-dir #{shell_escape(output_dir)} #{shell_escape(source)}"
-  run_command_with_analysis(command, label: "yardoc_#{output_dir}")
-end
-
-def checkout_repo(url, destination, ref: nil)
-  FileUtils.rm_rf(destination)
-  FileUtils.mkdir_p(File.dirname(destination))
-
-  command = "git clone --depth 1"
-  command += " --branch #{shell_escape(ref)}" if ref
-  command += " #{shell_escape(url)} #{shell_escape(destination)}"
-  run_command_with_analysis(command, label: "git_clone_#{destination}")
-end
-
-def generate_types(output_path = TYPES_OUTPUT_PATH)
-  FileUtils.mkdir_p(File.dirname(output_path))
-
-  command = [
-    "sord gen",
-    "--rbs",
-    "--no-sord-comments",
-    "--replace-unresolved-with-untyped",
-    "--replace-errors-with-untyped",
-    shell_escape(output_path)
-  ].join(" ")
-
-  run_command_with_analysis(command, label: "sord_generate")
-end
-
-def ensure_clean_generated_file(path)
-  command = "git status --short -- #{shell_escape(path)}"
-  stdout, stderr, status = Open3.capture3(command)
-  combined_output = [stdout, stderr].reject(&:empty?).join("\n")
-
-  raise "Unable to verify generated types for #{path}" unless status.success?
-  return if combined_output.strip.empty?
-
-  puts combined_output
-  raise "#{path} is out of date. Run `bundle exec rake types:generate` and commit the updated file."
-end
-
-
-namespace :examples do
-  desc "Generate basic example documentation using yard-markdown plugin"
-  task :generate do
-    Rake::Task["examples:yard"].invoke
-    Rake::Task["examples:rdoc"].invoke
-  end
-
-  desc "Generate example documentation for code annotated with yard"
-  task :yard do
-    generate_markdown_docs("example_yard.rb", "example/yard")
-  end
-
-  desc "Generate example documentation for code annotated with rdoc"
-  task :rdoc do
-    generate_markdown_docs("example_rdoc.rb", "example/rdoc")
-  end
-end
-
-namespace :real_world do
-  REPOS_DIR = "tmp/real-world/repos"
-  RSPEC_REPO = "#{REPOS_DIR}/rspec-core"
-  SIDEKIQ_REPO = "#{REPOS_DIR}/sidekiq"
-
-  desc "Checkout rspec-core repository"
-  task :checkout_rspec do
-    checkout_repo("https://github.com/rspec/rspec-core.git", RSPEC_REPO, ref: "v3.13.2")
-  end
-
-  desc "Checkout sidekiq repository"
-  task :checkout_sidekiq do
-    checkout_repo("https://github.com/sidekiq/sidekiq.git", SIDEKIQ_REPO, ref: "v7.3.10")
-  end
-
-  desc "Generate markdown docs for rspec-core"
-  task rspec: :checkout_rspec do
-    generate_markdown_docs("#{RSPEC_REPO}/lib", "tmp/real-world/rspec-core")
-  end
-
-  desc "Generate markdown docs for sidekiq"
-  task sidekiq: :checkout_sidekiq do
-    generate_markdown_docs("#{SIDEKIQ_REPO}/lib", "tmp/real-world/sidekiq")
-  end
-
-  desc "Generate markdown docs for rspec-core and sidekiq"
-  task :generate do
-    Rake::Task["real_world:rspec"].invoke
-    Rake::Task["real_world:sidekiq"].invoke
-  end
-end
-
-namespace :markdown do
-  desc "Validate checked-in example markdown output"
-  task validate_examples: "examples:generate" do
-    ["example/yard", "example/rdoc"].each do |dir|
-      file_count = MarkdownValidator.new(dir).validate!
-      puts "Validated #{file_count} markdown files in #{dir}"
-    end
-  end
-
-  desc "Generate and validate markdown output for rspec-core and sidekiq"
-  task validate_real_world: "real_world:generate" do
-    ["tmp/real-world/rspec-core", "tmp/real-world/sidekiq"].each do |dir|
-      validator = MarkdownValidator.new(dir, strict_links: false)
-      file_count = validator.validate!
-      puts "Validated #{file_count} markdown files in #{dir} (unresolved local links: #{validator.unresolved_links})"
-    end
-  end
-end
-
-namespace :types do
-  desc "Generate checked-in RBS types from YARD documentation"
-  task :generate do
-    generate_types
-  end
-
-  desc "Verify checked-in RBS types are up to date"
-  task check: :generate do
-    ensure_clean_generated_file(TYPES_OUTPUT_PATH)
-  end
-end

data/config/mutant.yml

@@ -1,25 +0,0 @@
-usage: opensource
-
-integration:
-  name: minitest
-
-includes:
-  - lib
-  - test
-
-requires:
-  - ./test/support/mutant_setup.rb
-
-matcher:
-  subjects:
-    - YARD::Markdown::AnchorComponentHelper#
-    - YARD::Markdown::ArefHelper#
-    - YARD::Markdown::CollectionRenderingHelper#
-    - YARD::Markdown::DocumentationHelper#
-    - YARD::Markdown::HeadingHelper#
-    - YARD::Markdown::LinkNormalizationHelper#
-    - YARD::Markdown::MethodPresentationHelper#
-    - YARD::Markdown::ObjectListingHelper#
-    - YARD::Markdown::RelationshipSectionHelper#
-    - YARD::Markdown::SectionAssemblyHelper#
-    - YARD::Markdown::TagFormattingHelper#

data/example/rdoc/Bird.md

@@ -1,25 +0,0 @@
-# Class Bird <a id="class-Bird"></a>
-
-**Inherits:** `Object`
-
-The base class for all birds.
-
-## Public Instance Methods
-### `fly(direction, velocity)` <a id="method-i-fly"></a> <a id="fly-instance_method"></a>
-Fly somewhere.
-
-Flying is the most critical feature of birds.
-
-:args: direction, velocity
-
-:call-seq:
-    Bird.fly(symbol, number) -> bool
-    Bird.fly(string, number) -> bool
-
-# Example
-
-    fly(:south, 70)
-
-### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
-Produce some noise. -- FIXME: maybe extract this to a base class `Animal`? ++
-- **@yield** ["tweet"]

data/example/rdoc/Duck.md

@@ -1,59 +0,0 @@
-# Class Duck <a id="class-Duck"></a>
-
-**Inherits:** `Object`
-**Extended by:** `Animal`
-**Includes:** `Waterfowl`
-
-A duck is a Waterfowl Bird.
-
-Features:
-
-    bird::
-
-      * speak
-      * fly
-
-    waterfowl::
-
-      * swim
-
-## Constants
-### `@@rubber_ducks` <a id="classvariable--40-40rubber_ducks"></a> <a id="@@rubber_ducks-classvariable"></a>
-Global list of all rubber ducks.
-
-Use when in trouble.
-
-### `MAX_VELOCITY` <a id="constant-MAX_VELOCITY"></a> <a id="MAX_VELOCITY-constant"></a>
-Maximum velocity for a flying duck.
-
-## Attributes
-### `domestic` [RW] <a id="attribute-i-domestic"></a> <a id="domestic-instance_method"></a>
-True for domestic ducks.
-
-### `rubber` [R] <a id="attribute-i-rubber"></a> <a id="rubber-instance_method"></a>
-True for rubber ducks.
-
-## Public Class Methods
-### `rubber_ducks()` <a id="method-c-rubber_ducks"></a> <a id="rubber_ducks-class_method"></a>
-- **@return** [Array<Duck>] list of all rubber ducks
-
-## Public Instance Methods
-### `initialize(domestic, rubber)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
-Creates a new duck.
-- **@param** `domestic` [Boolean]
-- **@param** `rubber` [Boolean]
-- **@return** [Duck] a new instance of Duck
-
-### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
-Duck overrides generic implementation.
-- **@yield** [speech]
-
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swimming helper.
-
-### `useful?()` <a id="method-i-useful-3F"></a> <a id="useful?-instance_method"></a>
-Checks if this duck is a useful one.
-
-:call-seq:
-    Bird.useful? -> bool
-- **@return** [Boolean]

data/example/rdoc/Waterfowl.md

@@ -1,7 +0,0 @@
-# Module Waterfowl <a id="module-Waterfowl"></a>
-
-A mixin for waterfowl creatures.
-
-## Public Instance Methods
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swimming helper.

data/example/rdoc/index.csv

@@ -1,16 +0,0 @@
-name,type,path
-Waterfowl,Module,Waterfowl.md
-Waterfowl.swim,Method,Waterfowl.md#method-i-swim
-Bird,Class,Bird.md
-Bird.fly,Method,Bird.md#method-i-fly
-Bird.speak,Method,Bird.md#method-i-speak
-Duck,Class,Duck.md
-Duck.MAX_VELOCITY,Constant,Duck.md#constant-MAX_VELOCITY
-Duck.@@rubber_ducks,Constant,Duck.md#classvariable--40-40rubber_ducks
-Duck.initialize,Method,Duck.md#method-i-initialize
-Duck.speak,Method,Duck.md#method-i-speak
-Duck.swim,Method,Duck.md#method-i-swim
-Duck.useful?,Method,Duck.md#method-i-useful-3F
-Duck.rubber_ducks,Method,Duck.md#method-c-rubber_ducks
-Duck.domestic,Attribute,Duck.md#attribute-i-domestic
-Duck.rubber,Attribute,Duck.md#attribute-i-rubber

data/example/yard/Aquatic.md

@@ -1,8 +0,0 @@
-# Module Aquatic <a id="module-Aquatic"></a>
-
-A mixin for aquatic creatures.
-
-## Public Instance Methods
-### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swim in the water.
-- **@return** [void]

data/example/yard/Fish.md

@@ -1,25 +0,0 @@
-# Class Fish <a id="class-Fish"></a>
-
-**Inherits:** `Object`
-
-The base class for all fish.
-
-## Public Instance Methods
-### `make_sound()` <a id="method-i-make_sound"></a> <a id="make_sound-instance_method"></a>
-Make a sound.
-- **@return** [void]
-- **@yield** [sound] The sound produced by the fish
-- **@yieldparam** `sound` [String] The actual sound
-
-### `swim(direction, speed)` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swim in a specific direction.
-
-Swimming is the most critical feature of fish.
-- **@param** `direction` [Symbol, String] The direction to swim
-- **@param** `speed` [Integer] The speed at which to swim
-- **@return** [Boolean] Whether the swim was successful
-
-**@example**
-```ruby
-swim(:north, 30)
-```

data/example/yard/Salmon.md

@@ -1,58 +0,0 @@
-# Class Salmon <a id="class-Salmon"></a>
-
-**Inherits:** `Fish`
-**Includes:** `Aquatic`
-
-A salmon is an Aquatic Fish.
-
-## Features
-
-*   **Fish**
-    *   make_sound
-    *   swim
-*   **Aquatic**
-    *   swim (overridden)
-
-## Constants
-### Salmon specific attributes
-#### `MAX_SPEED` <a id="constant-MAX_SPEED"></a> <a id="MAX_SPEED-constant"></a>
-- **@return** [Integer] Maximum speed for a swimming salmon
-### General
-#### `@@wild_salmon` <a id="classvariable--40-40wild_salmon"></a> <a id="@@wild_salmon-classvariable"></a>
-Global list of all wild salmon.
-
-Use for conservation efforts.
-
-## Attributes
-### Salmon specific attributes
-#### `farmed` [RW] <a id="attribute-i-farmed"></a> <a id="farmed-instance_method"></a>
-- **@return** [Boolean] True for farmed salmon
-
-#### `wild` [R] <a id="attribute-i-wild"></a> <a id="wild-instance_method"></a>
-- **@return** [Boolean] True for wild salmon
-
-## Public Class Methods
-### `wild_salmon()` <a id="method-c-wild_salmon"></a> <a id="wild_salmon-class_method"></a>
-- **@return** [Array<Salmon>] List of all wild salmon
-
-## Public Instance Methods
-### Fish overrides
-#### `make_sound()` <a id="method-i-make_sound"></a> <a id="make_sound-instance_method"></a>
-Salmon overrides generic implementation.
-- **@return** [void]
-- **@yield** [sound] The sound produced by the salmon
-- **@yieldparam** `sound` [String] The actual sound
-### General
-#### `initialize(farmed, wild)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
-Creates a new salmon.
-- **@param** `farmed` [Boolean] Whether the salmon is farmed
-- **@param** `wild` [Boolean] Whether the salmon is wild
-- **@return** [Salmon] a new instance of Salmon
-
-#### `sustainable?()` <a id="method-i-sustainable-3F"></a> <a id="sustainable?-instance_method"></a>
-Checks if this salmon is sustainable.
-- **@return** [Boolean] Whether the salmon is sustainable
-
-#### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
-Swim in the water.
-- **@return** [void]

data/example/yard/index.csv

@@ -1,16 +0,0 @@
-name,type,path
-Aquatic,Module,Aquatic.md
-Aquatic.swim,Method,Aquatic.md#method-i-swim
-Fish,Class,Fish.md
-Fish.make_sound,Method,Fish.md#method-i-make_sound
-Fish.swim,Method,Fish.md#method-i-swim
-Salmon,Class,Salmon.md
-Salmon.MAX_SPEED,Constant,Salmon.md#constant-MAX_SPEED
-Salmon.@@wild_salmon,Constant,Salmon.md#classvariable--40-40wild_salmon
-Salmon.initialize,Method,Salmon.md#method-i-initialize
-Salmon.make_sound,Method,Salmon.md#method-i-make_sound
-Salmon.sustainable?,Method,Salmon.md#method-i-sustainable-3F
-Salmon.swim,Method,Salmon.md#method-i-swim
-Salmon.wild_salmon,Method,Salmon.md#method-c-wild_salmon
-Salmon.farmed,Attribute,Salmon.md#attribute-i-farmed
-Salmon.wild,Attribute,Salmon.md#attribute-i-wild

data/example_rdoc.rb

@@ -1,147 +0,0 @@
-##
-# === RDoc::Generator::Markdown example.
-#
-# This example employs various RDoc features to demonstrate
-# generator output.
-#
-# ---
-#
-# Links:
-#
-#  1. {Project Home Page}[https://github.com/skatkov/rdoc-markdown)
-#  2. {RDoc Documentation}[http://ruby-doc.org/stdlib-2.0.0/libdoc/rdoc/rdoc/RDoc/Markup.html]
-#
-
-##
-# A mixin for waterfowl creatures.
-module Waterfowl
-  # Swimming helper.
-  def swim
-    puts "swimming around"
-  end
-end
-
-##
-# The base class for all birds.
-class Bird
-  ##
-  # Produce some noise.
-  #--
-  # FIXME: maybe extract this to a base class +Animal+?
-  #++
-  def speak # :yields: text
-    puts "generic tweeting"
-    yield "tweet"
-    yield "tweet"
-  end
-
-  # Fly somewhere.
-  #
-  # Flying is the most critical feature of birds.
-  #
-  # :args: direction, velocity
-  #
-  # :call-seq:
-  #   Bird.fly(symbol, number) -> bool
-  #   Bird.fly(string, number) -> bool
-  #
-  # = Example
-  #
-  #   fly(:south, 70)
-  def fly(direction, velocity)
-    _fly_impl(direction, velocity)
-  end
-
-  def _fly_impl(_direction, _velocity) # :nodoc:
-    puts "flying away: direction=#{direction}, velocity=#{velocity}"
-  end
-end
-
-##
-# A duck is a Waterfowl Bird.
-#
-# Features:
-#
-#  bird::
-#
-#    * speak
-#    * fly
-#
-#  waterfowl::
-#
-#    * swim
-class Duck
-  extend Animal
-  include Waterfowl
-
-  # :section: Bird overrides
-
-  # Duck overrides generic implementation.
-  def speak
-    speech = quack
-    yield speech
-  end
-
-  # Implements quacking
-  def quack
-    "quack"
-  end
-
-  private :quack
-
-  # :section: Duck extensions
-
-  # True for domestic ducks.
-  attr_accessor :domestic
-
-  # True for rubber ducks.
-  attr_reader :rubber
-
-  MAX_VELOCITY = 130 # Maximum velocity for a flying duck.
-
-  ##
-  # Global list of all rubber ducks.
-  #
-  # Use when in trouble.
-  @@rubber_ducks = []
-
-  # @return [Array<Duck>] list of all rubber ducks
-  def self.rubber_ducks
-    @@rubber_ducks
-  end
-
-  # Creates a new duck.
-  #
-  # @param [Boolean] domestic
-  # @param [Boolean] rubber
-  def initialize(domestic, rubber)
-    @domestic = domestic
-    @rubber = rubber
-    @@rubber_ducks << self if rubber
-  end
-
-  # Checks if this duck is a useful one.
-  #
-  # :call-seq:
-  #   Bird.useful? -> bool
-  def useful?
-    @domestic || @rubber
-  end
-end
-
-# Default velocity for a flying duck.
-DEFAULT_DUCK_VELOCITY = 70
-DEFAULT_SPEED = 10 # Maximum speed for a swimming duck.
-
-
-# Default rubber duck.
-#
-# *Note:*
-#  Global variables are evil, but rubber ducks are worth it.
-$default_rubber_duck = Duck.new(false, true)
-
-# Domestic rubber duck.
-#
-# *Note:*
-#  This is weird... Thus not making it global.
-domestic_rubber_duck = Duck.new(true, true) # rubocop:disable Lint/UselessAssignment