yard-markdown 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3bf19f52aa053b77b3bdfa88b447e7db00c746135a47b77e81e2a08ceb4367a
-  data.tar.gz: 8a141a935807d808abec2fa5f2e6d690cfb0c9ec70e89fc0709e7a39f60fb697
+  metadata.gz: 92bac83ffe7c1f83b26164adef991efe13678b96096ba61af2626f83e9505991
+  data.tar.gz: 7c871bffa551b5acc83e0b954163d933b7289db6542b1485c385ab97fb53e4eb
 SHA512:
-  metadata.gz: d53e7cd3f76693122642ec6196bf8e49f11b2b5457ebb0942be702e33efe25348141580188bb00dfc9846b5766ee412e14c9c059e119358ab79c1a0f828e30c1
-  data.tar.gz: 02d47f00d6408f1d645ac0d46936e2734c89f1c853632d88b4217d0bb2985993ddcd6d99dbe38de18ee40a858b1441a35b44c3ce7e6ea2161b4a6705e2dcb540
+  metadata.gz: 7d7fb3ae97903f7c61aa0a057cdefd878a562264d15d5e7a3da17a5a2bdd5ea35c63cc47244022ab10fe20356c7adf367eee27e1de5b67281376174645c29b54
+  data.tar.gz: 126033d377d8e652a19b33731d57ccfad197731cf819521766dbee5b37d1ee293baf41fc58c7927073ae3cddea9c5a4227b57539023de96ff66740e3d53e88d7

data/README.md

@@ -33,7 +33,7 @@ It seems important to note, that yard claims to have support for RDoc. That supp
 
 If you know how to improve that, please get in touch or submit a patch.
 
-So in meantime, there is work going on a competing gem for RDoc and it's called [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdown/).
+So in meantime, there is work going on a competing gem for RDoc and it's called [rdoc-markdown gem](https://github.com/skatkov/rdoc-markdown/).
 
 ## Note on index.csv file
 This gem emits index of all markdown files in a index.csv file.
@@ -43,6 +43,34 @@ There are decent tools that offer search through structured plain-text files. Bu
 In my personal use-case, I use SQLite. All other databases seem to have a good support for CSV imports.
 
 ## Testing
-Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
+Unit tests verify renderer behavior, index links, and anchor consistency for both YARD-style and RDoc-style sources.
 
-Easiest way to test is to run `rake generate_example` and check output in `example` directory.
+Run:
+
+```bash
+bundle exec rake test
+```
+
+Regenerate local sample docs:
+
+```bash
+bundle exec rake examples:generate
+```
+
+Validate generated markdown in sample docs:
+
+```bash
+bundle exec rake markdown:validate_examples
+```
+
+There is also a real-world validation harness for repositories with substantial YARD documentation (`rspec-core`, `sidekiq`):
+
+```bash
+bundle exec rake markdown:validate_real_world
+```
+
+This task validates generated markdown against CommonMark + GFM rendering, and reports unresolved local links found in upstream source comments while still validating local anchor/link structure.
+
+GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
+
+For reproducible checks, the task clones pinned tags (`rspec-core` `v3.13.2`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` before generating output.

data/Rakefile

@@ -1,8 +1,14 @@
 # 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"
@@ -11,6 +17,73 @@ end
 
 task default: %i[test stree:write]
 
+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
+
 
 namespace :examples do
   desc "Generate basic example documentation using yard-markdown plugin"
@@ -21,11 +94,62 @@ namespace :examples do
 
   desc "Generate example documentation for code annotated with yard"
   task :yard do
-    sh "yardoc --output-dir example/yard example_yard.rb"
+    generate_markdown_docs("example_yard.rb", "example/yard")
   end
 
   desc "Generate example documentation for code annotated with rdoc"
   task :rdoc do
-    sh "yardoc --output-dir example/rdoc example_rdoc.rb"
+    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

data/example/rdoc/Bird.md

@@ -1,16 +1,11 @@
-# Class: Bird
-**Inherits:** Object
-    
-
-The base class for all birds.
-
+# Class Bird <a id="class-Bird"></a>
 
+**Inherits:** `Object`
 
-#Instance Methods
-## _fly_impl(_direction, _velocity) [](#method-i-_fly_impl)
-:nodoc:
+The base class for all birds.
 
-## fly(direction, velocity) [](#method-i-fly)
+## 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.
@@ -25,8 +20,6 @@ Flying is the most critical feature of birds.
 
     fly(:south, 70)
 
-## speak() [](#method-i-speak)
+### `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"] 
-
+- **@yield** ["tweet"]

data/example/rdoc/Duck.md

@@ -1,10 +1,8 @@
-# Class: Duck
-**Inherits:** Object
-  
-**Extended by:** Animal
-    
-**Includes:** Waterfowl
-  
+# Class Duck <a id="class-Duck"></a>
+
+**Inherits:** `Object`
+**Extended by:** `Animal`
+**Includes:** `Waterfowl`
 
 A duck is a Waterfowl Bird.
 
@@ -19,42 +17,43 @@ Features:
 
       * 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.
 
-# Class Methods
-## rubber_ducks() [](#method-c-rubber_ducks)
-**@return** [Array<Duck>] list of all rubber ducks
+### `MAX_VELOCITY` <a id="constant-MAX_VELOCITY"></a> <a id="MAX_VELOCITY-constant"></a>
+Maximum velocity for a flying duck.
 
-# Attributes
-## domestic[RW] [](#attribute-i-domestic)
+## Attributes
+### `domestic` [RW] <a id="attribute-i-domestic"></a> <a id="domestic-instance_method"></a>
 True for domestic ducks.
 
-## rubber[RW] [](#attribute-i-rubber)
+### `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
 
-#Instance Methods
-## initialize(domestic, rubber) [](#method-i-initialize)
+## 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
 
-**@param** [Boolean] 
-
-**@param** [Boolean] 
-
-**@return** [Duck] a new instance of Duck
-
-## speak() [](#method-i-speak)
+### `speak()` <a id="method-i-speak"></a> <a id="speak-instance_method"></a>
 Duck overrides generic implementation.
+- **@yield** [speech]
 
-**@yield** [speech] 
-
-## swim() [](#method-i-swim)
+### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swimming helper.
 
-## useful?() [](#method-i-useful?)
+### `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] 
-
+- **@return** [Boolean]

data/example/rdoc/Waterfowl.md

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

data/example/rdoc/index.csv

@@ -1,21 +1,16 @@
 name,type,path
 Waterfowl,Module,Waterfowl.md
-Waterfowl.DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
-Waterfowl.DEFAULT_SPEED,Constant,Waterfowl.md#constant-DEFAULT_SPEED
 Waterfowl.swim,Method,Waterfowl.md#method-i-swim
 Bird,Class,Bird.md
-Bird.DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
-Bird.DEFAULT_SPEED,Constant,Bird.md#constant-DEFAULT_SPEED
-Bird._fly_impl,Method,Bird.md#method-i-_fly_impl
 Bird.fly,Method,Bird.md#method-i-fly
 Bird.speak,Method,Bird.md#method-i-speak
 Duck,Class,Duck.md
-Duck.DEFAULT_DUCK_VELOCITY,Constant,Duck.md#constant-DEFAULT_DUCK_VELOCITY
-Duck.DEFAULT_SPEED,Constant,Duck.md#constant-DEFAULT_SPEED
+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?
+Duck.useful?,Method,Duck.md#method-i-useful-3F
 Duck.rubber_ducks,Method,Duck.md#method-c-rubber_ducks
-domestic,Attribute,Duck.md#attribute-i-domestic
-rubber,Attribute,Duck.md#attribute-i-rubber
+Duck.domestic,Attribute,Duck.md#attribute-i-domestic
+Duck.rubber,Attribute,Duck.md#attribute-i-rubber

data/example/yard/Aquatic.md

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

data/example/yard/Fish.md

@@ -1,34 +1,25 @@
-# Class: Fish
-**Inherits:** Object
-    
-
-The base class for all fish.
+# Class Fish <a id="class-Fish"></a>
 
+**Inherits:** `Object`
 
+The base class for all fish.
 
-#Instance Methods
-## make_sound() [](#method-i-make_sound)
+## 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
 
-**@return** [void] 
-
-**@yield** [sound] The sound produced by the fish
-
-**@yieldparam** [String] The actual sound
-
-## swim(direction, speed) [](#method-i-swim)
+### `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** [Symbol, String] The direction to swim
-
-**@param** [Integer] The speed at which to swim
-
-**@return** [Boolean] Whether the swim was successful
-
+- **@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,8 +1,7 @@
-# Class: Salmon
-**Inherits:** Fish
-    
-**Includes:** Aquatic
-  
+# Class Salmon <a id="class-Salmon"></a>
+
+**Inherits:** `Fish`
+**Includes:** `Aquatic`
 
 A salmon is an Aquatic Fish.
 
@@ -14,47 +13,46 @@ A salmon is an Aquatic Fish.
 *   **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.
 
-# Class Methods
-## wild_salmon() [](#method-c-wild_salmon)
-**@return** [Array<Salmon>] List of all wild salmon
-
-# Attributes
-## farmed[RW] [](#attribute-i-farmed)
-
-**@return** [Boolean] True for farmed salmon
-
-## wild[RW] [](#attribute-i-wild)
-
-**@return** [Boolean] True for wild salmon
-
-
-#Instance Methods
-## initialize(farmed, wild) [](#method-i-initialize)
-Creates a new salmon.
+Use for conservation efforts.
 
-**@param** [Boolean] Whether the salmon is farmed
+## Attributes
+### Salmon specific attributes
+#### `farmed` [RW] <a id="attribute-i-farmed"></a> <a id="farmed-instance_method"></a>
+- **@return** [Boolean] True for farmed salmon
 
-**@param** [Boolean] Whether the salmon is wild
+#### `wild` [R] <a id="attribute-i-wild"></a> <a id="wild-instance_method"></a>
+- **@return** [Boolean] True for wild salmon
 
-**@return** [Salmon] a new instance of 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
 
-## make_sound() [](#method-i-make_sound)
+## 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
 
-**@return** [void] 
-
-**@yield** [sound] The sound produced by the salmon
-
-**@yieldparam** [String] The actual sound
-
-## sustainable?() [](#method-i-sustainable?)
+#### `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
 
-**@return** [Boolean] Whether the salmon is sustainable
-
-## swim() [](#method-i-swim)
+#### `swim()` <a id="method-i-swim"></a> <a id="swim-instance_method"></a>
 Swim in the water.
-
-**@return** [void] 
-
+- **@return** [void]

data/example/yard/index.csv

@@ -1,20 +1,16 @@
 name,type,path
 Aquatic,Module,Aquatic.md
-Aquatic.DEFAULT_SALMON_SPEED,Constant,Aquatic.md#constant-DEFAULT_SALMON_SPEED
-Aquatic.MAX_DEPTH,Constant,Aquatic.md#constant-MAX_DEPTH
 Aquatic.swim,Method,Aquatic.md#method-i-swim
 Fish,Class,Fish.md
-Fish.DEFAULT_SALMON_SPEED,Constant,Fish.md#constant-DEFAULT_SALMON_SPEED
-Fish.MAX_DEPTH,Constant,Fish.md#constant-MAX_DEPTH
 Fish.make_sound,Method,Fish.md#method-i-make_sound
 Fish.swim,Method,Fish.md#method-i-swim
 Salmon,Class,Salmon.md
-Salmon.DEFAULT_SALMON_SPEED,Constant,Salmon.md#constant-DEFAULT_SALMON_SPEED
-Salmon.MAX_DEPTH,Constant,Salmon.md#constant-MAX_DEPTH
+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?
+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
-farmed,Attribute,Salmon.md#attribute-i-farmed
-wild,Attribute,Salmon.md#attribute-i-wild
+Salmon.farmed,Attribute,Salmon.md#attribute-i-farmed
+Salmon.wild,Attribute,Salmon.md#attribute-i-wild