yard-markdown 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1c4368b70ec91bff1a8f9bf1aaefc79578a34251b879d800f59c466b611dd5a
-  data.tar.gz: 917397c1e9df43930d699fe0258dd124260b5168222fc28c5d0a84ded9f21d1e
+  metadata.gz: 92bac83ffe7c1f83b26164adef991efe13678b96096ba61af2626f83e9505991
+  data.tar.gz: 7c871bffa551b5acc83e0b954163d933b7289db6542b1485c385ab97fb53e4eb
 SHA512:
-  metadata.gz: 932de039cf4fbd5fadd8bf012f7663f6cda4b270100b7930a28d6e182949628b727705a47893daebb5b39cf4c630f5c3a4e2f7a8ff3e7609e2aa2a43172db00f
-  data.tar.gz: 1d8191d7f0e0db8eea07842025a3dea14a924a67924464df8053ad00d337c9efb71ca832cafd3b83c2e6d150fa897c3ca08527744e86e043d4f3bd059db54898
+  metadata.gz: 7d7fb3ae97903f7c61aa0a057cdefd878a562264d15d5e7a3da17a5a2bdd5ea35c63cc47244022ab10fe20356c7adf367eee27e1de5b67281376174645c29b54
+  data.tar.gz: 126033d377d8e652a19b33731d57ccfad197731cf819521766dbee5b37d1ee293baf41fc58c7927073ae3cddea9c5a4227b57539023de96ff66740e3d53e88d7

data/.yardopts

@@ -1,8 +1 @@
 --load ./lib/yard-markdown.rb
---format markdown
---markup markdown
---output-dir example
---private
---protected
--
-example.rb

data/README.md

@@ -1,11 +1,15 @@
 # Yard::Markdown
 
-Yard plugin to generate markdown documentation
+Yard plugin to output markdown documentation.
+
+## Motivation
+Markdown has become the de-facto documentation standard. I heavily rely on Obsidian to render my storage of markdown notes. But markdown is used not just for scribbles, supported is far and wide. We can render markdown file on any device, probably even on thermometer with a screen. But also everyone knows enough markdown to be dangerous (or productive).
+It's a pitty that rdoc and yard can't output a proper markdown file. I would like to change that.
 
 ## Goals:
 - Compatible with Github Flavored Markdown
+- Produce .csv index file
 - Mimick yard html layout where it makes sense to maintain familiarity
-- Produce .csv index file alonside markdown documentation to act as file index
 
 ## Usage
 Yard doesn't load plugin by default, so you need to load plugin through `~/.yard/config`:
@@ -24,14 +28,49 @@ gem install yard-markdown
 
 Run `yardoc --format=markdown` to generate markdown documentation.
 
-## Backstory
-This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdown/tree/main/example). These docsets are used in [POSH TUI](https://poshtui.com).
+## Note on RDoc support
+It seems important to note, that yard claims to have support for RDoc. That support is certainly present, but output for rdoc is dramatically different. A lot of useful information seems lost in the process.
+
+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-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.
+
+There are decent tools that offer search through structured plain-text files. But my expectation is that nobody will use CSV as an actual search index, but rather import it into something that performs this function better.
+
+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.
+
+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.
 
-### Testing Rdoc conversion to markdown:
-`yardoc example_rdoc.rb` -> outputs everything into example/ folder.
+GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
 
-### Testing Yard conversion to markdown:
-  `yardoc example_yard.rb` -> outputs everything into example/ folder.
+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"
@@ -10,3 +16,140 @@ Rake::TestTask.new(:test) do |t|
 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"
+  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

data/example/rdoc/Bird.md

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,59 @@
+# 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

@@ -0,0 +1,7 @@
+# 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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,8 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,58 @@
+# 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

@@ -0,0 +1,16 @@
+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