rdoc-markdown 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df1f3da8afd7010551e9edbaf2f33de617d63584760e3c59120c6f3b38232f19
-  data.tar.gz: 82b591023300cf619230ef8786b3ae10ed3cb5d2aadae9afcd43b5da4c0528b7
+  metadata.gz: 87cca03aa4d398385640d41bb6373d6607885593855cc7753253ce3453b92cbd
+  data.tar.gz: 230d405d4b7feca88a1b5fd3baab2ab707d3cd24628a8a9cd6706cbe8b7b45dd
 SHA512:
-  metadata.gz: ac5335f705812d01d5bd24488cda5fb77ce69f8fa6b32677b13f048aab476062c0845681324f3b05de9c0965bbcc2c0f1c64dbb5e4f58dc5ee8a8c4a8906dd33
-  data.tar.gz: b682c9b99cace11662bff88be24560b370a2b8a084ec9fac47a854e90a0bfdfafd246e4c62d9c84055c426bcaf3572d1f69bb2e0d02aacc838a7be46e6da8b01
+  metadata.gz: 3a5829cb97da49560f0aebd62f4e405a59ba7ad9a8ca4a9d1ac43aa4c6cc13189230630828b962d12124bc4a7544cb314f82cf9baeae73f25ba0700639802249
+  data.tar.gz: 8a47baf609af1888fd049294cfe4c3f97a0e65f1f80d19f013acf42a482db57c89f5a38b854eb6cf2e4b594fa9c9fc515e7e428144827856b236d9d25699da60

data/Gemfile.lock

@@ -1,50 +1,55 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.5.0)
+    rdoc-markdown (0.6.0)
       csv
       erb
       rdoc
       reverse_markdown
-      unindent
 
 GEM
   remote: https://rubygems.org/
   specs:
-    cgi (0.4.1)
-    csv (3.3.2)
-    date (3.4.1)
-    erb (4.0.4)
-      cgi (>= 0.3.3)
-    minitest (5.25.4)
-    nokogiri (1.18.0-aarch64-linux-gnu)
+    commonmarker (2.6.3-aarch64-linux)
+    commonmarker (2.6.3-arm-linux)
+    commonmarker (2.6.3-arm64-darwin)
+    commonmarker (2.6.3-x86_64-darwin)
+    commonmarker (2.6.3-x86_64-linux)
+    commonmarker (2.6.3-x86_64-linux-musl)
+    csv (3.3.5)
+    date (3.5.1)
+    erb (6.0.1)
+    minitest (5.27.0)
+    nokogiri (1.19.0-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.0-aarch64-linux-musl)
+    nokogiri (1.19.0-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.0-arm-linux-gnu)
+    nokogiri (1.19.0-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.0-arm-linux-musl)
+    nokogiri (1.19.0-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.0-arm64-darwin)
+    nokogiri (1.19.0-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.0-x86_64-darwin)
+    nokogiri (1.19.0-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.0-x86_64-linux-gnu)
+    nokogiri (1.19.0-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.0-x86_64-linux-musl)
+    nokogiri (1.19.0-x86_64-linux-musl)
       racc (~> 1.4)
-    psych (5.2.2)
+    psych (5.3.1)
       date
       stringio
     racc (1.8.1)
-    rake (13.2.1)
+    rake (13.3.1)
     rdiscount (2.2.7.3)
-    rdoc (6.10.0)
+    rdoc (7.2.0)
+      erb
       psych (>= 4.0.0)
-    reverse_markdown (3.0.0)
+      tsort
+    reverse_markdown (3.0.2)
       nokogiri
-    stringio (3.1.2)
-    unindent (1.0)
+    stringio (3.2.0)
+    tsort (0.2.0)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -58,6 +63,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.0)
+  commonmarker
   minitest (~> 5.0)
   rake (~> 13.0)
   rdiscount (~> 2.0)

data/README.md

@@ -1,5 +1,10 @@
 # RDoc-Markdown
-RDoc plugin to generate markdown documentation and search index backed by sqlite database.
+RDoc plugin to generate markdown documentation and search index file (CSV).
+
+## 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.
 
 ## Installation
 
@@ -23,6 +28,13 @@ Run following command in directory with ruby source code:
 
 This will produce a tree of markdown documents and search index in `/doc` folder. Every class in library will have it's own markdown file.
 
+## 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.
+
 ## Development
 Biggest issue is testing this locally, but that's not as hard to do these days.
 
@@ -46,6 +58,65 @@ Following command should run entire testsuit:
 rake test
 ```
 Testing is not excessive, just verifies that basic functionality is operational.
+
+To validate generated markdown against GitHub Flavored Markdown and check local links/anchors:
+
+```
+rake markdown:validate
+```
+
+This task validates:
+
+- generated sample docs,
+- checked-in `example/` docs,
+- vendored minitest docs,
+- vendored rails docs (Active Support, Active Record, Action Pack, Railties slices).
+
+Validation artifacts are written to `tmp/markdown-validate/` inside this repository.
+To fail on every unresolved vendor local link/anchor, run with:
+
+```
+MARKDOWN_VALIDATE_STRICT_VENDOR=1 rake markdown:validate
+```
+
+This task is also executed in CI.
+
+### Integration harness: minitest
+To run the integration harness against minitest (aligned with docs.seattlerb.org/minitest):
+
+```
+rake vendor:setup:minitest
+bundle exec rake test
+```
+
+The harness validates markdown formatting quality, generated page files, class/module paths, and search index output.
+
+### Integration harness: rails
+To run the rails harness (focused on Active Support + Active Record API docs with sdoc-like structure):
+
+```
+rake vendor:setup:rails
+bundle exec rake test
+```
+
+The rails harness validates alias rendering, preserved code blocks, file/page links rewritten to markdown, and index stability (no synthetic nested class names).
+
+### Generate vendored docs
+Use rake tasks to generate markdown output for vendored projects:
+
+```
+rake vendor:setup
+rake vendor:docs:minitest
+rake vendor:docs:rails
+# or generate both
+rake vendor:docs
+```
+
+Output is written to:
+
+- `vendor/docs/minitest`
+- `vendor/docs/rails`
+
 ## Release
 ```
 gem build rdoc-markdown.gemspec

data/Rakefile

@@ -1,5 +1,9 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "fileutils"
+require "rdoc/rdoc"
+require "rdoc/markdown"
+require_relative "test/support/markdown_validator"
 
 Rake::TestTask.new do |t|
   t.verbose = true
@@ -8,3 +12,173 @@ Rake::TestTask.new do |t|
 end
 
 task default: [:test]
+
+namespace :markdown do
+  desc "Validate generated markdown as GitHub Flavored Markdown"
+  task :validate do
+    strict_vendor_links = ENV["MARKDOWN_VALIDATE_STRICT_VENDOR"] == "1"
+    validation_root = File.expand_path("tmp/markdown-validate", __dir__)
+    FileUtils.rm_rf(validation_root)
+    FileUtils.mkdir_p(validation_root)
+
+    sample_output = File.join(validation_root, "sample")
+    generate_markdown_docs(
+      title: "sample",
+      root: File.expand_path("test/data", __dir__),
+      output: sample_output,
+      files: [File.expand_path("test/data/example.rb", __dir__)]
+    )
+
+    sample_count = MarkdownValidator.new(sample_output).validate!
+    puts "Validated #{sample_count} markdown files in #{sample_output}"
+
+    example_dir = File.expand_path("example", __dir__)
+    if Dir.exist?(example_dir)
+      example_count = MarkdownValidator.new(example_dir).validate!
+      puts "Validated #{example_count} markdown files in #{example_dir}"
+    end
+
+    Rake::Task["vendor:setup:minitest"].invoke
+    minitest_root = File.expand_path("vendor/minitest", __dir__)
+    minitest_output = File.join(validation_root, "minitest")
+    generate_markdown_docs(
+      title: "minitest",
+      root: minitest_root,
+      output: minitest_output,
+      files: minitest_docs_files(minitest_root)
+    )
+    minitest_validator = MarkdownValidator.new(minitest_output, strict_links: strict_vendor_links)
+    minitest_count = minitest_validator.validate!
+    puts "Validated #{minitest_count} markdown files in #{minitest_output}"
+    puts "Skipped #{minitest_validator.unresolved_links} unresolved local links in vendored minitest docs"
+
+    Rake::Task["vendor:setup:rails"].invoke
+    rails_root = File.expand_path("vendor/rails", __dir__)
+    rails_output = File.join(validation_root, "rails")
+    generate_markdown_docs(
+      title: "rails validation",
+      root: rails_root,
+      output: rails_output,
+      files: rails_validation_files(rails_root)
+    )
+    rails_validator = MarkdownValidator.new(rails_output, strict_links: strict_vendor_links)
+    rails_count = rails_validator.validate!
+    puts "Validated #{rails_count} markdown files in #{rails_output}"
+    puts "Skipped #{rails_validator.unresolved_links} unresolved local links in vendored rails docs"
+
+    puts "Markdown validation artifacts written to #{validation_root}"
+  end
+end
+
+def ensure_git_checkout(path:, url:, ref: nil)
+  return if Dir.exist?(path)
+
+  FileUtils.mkdir_p(File.dirname(path))
+
+  clone_command = ["git", "clone", "--depth", "1"]
+  clone_command += ["--branch", ref] if ref
+  clone_command += [url, path]
+
+  sh clone_command.join(" ")
+end
+
+def generate_markdown_docs(title:, root:, output:, files:)
+  raise "No input files for #{title}" if files.empty?
+
+  FileUtils.rm_rf(output)
+  FileUtils.mkdir_p(output)
+
+  options = RDoc::Options.new
+  options.setup_generator("markdown")
+  options.verbosity = 0
+  options.files = files
+  options.op_dir = output
+  options.root = root
+  options.title = title
+  options.force_output = true
+
+  RDoc::RDoc.new.document(options)
+end
+
+def minitest_docs_files(root)
+  files = Dir[File.join(root, "lib/**/*.rb")]
+  files.concat(Dir[File.join(root, "*.rdoc")])
+
+  manifest = File.join(root, "Manifest.txt")
+  files << manifest if File.file?(manifest)
+
+  files.uniq
+end
+
+def rails_validation_files(root)
+  files = Dir[File.join(root, "activesupport/lib/**/*.rb")]
+  files.concat(Dir[File.join(root, "activerecord/lib/**/*.rb")])
+  files.concat(Dir[File.join(root, "actionpack/lib/**/*.rb")])
+  files.concat(Dir[File.join(root, "railties/lib/**/*.rb")])
+
+  [
+    "activerecord/README.rdoc",
+    "actionpack/README.rdoc",
+    "railties/README.rdoc",
+    "railties/RDOC_MAIN.md"
+  ].each do |relative_path|
+    file = File.join(root, relative_path)
+    files << file if File.file?(file)
+  end
+
+  files.uniq
+end
+
+namespace :vendor do
+  namespace :setup do
+    MINITEST_REF = "v6.0.1"
+    RAILS_REF = ENV.fetch("RAILS_REF", "main")
+
+    desc "Clone/update vendor/minitest and checkout docs-aligned tag"
+    task :minitest do
+      ensure_git_checkout(path: "vendor/minitest", url: "https://github.com/minitest/minitest.git", ref: MINITEST_REF)
+      Dir.chdir("vendor/minitest") { sh "git checkout #{MINITEST_REF}" }
+    end
+
+    desc "Clone/update vendor/rails"
+    task :rails do
+      ensure_git_checkout(path: "vendor/rails", url: "https://github.com/rails/rails.git", ref: RAILS_REF)
+    end
+  end
+
+  desc "Prepare all vendored repositories"
+  task setup: ["vendor:setup:minitest", "vendor:setup:rails"]
+
+  namespace :docs do
+    desc "Generate markdown docs for vendored minitest"
+    task :minitest do
+      root = File.expand_path("vendor/minitest", __dir__)
+      raise "Missing vendor/minitest. Run `rake vendor:setup:minitest` first." unless Dir.exist?(root)
+
+      output = File.expand_path("vendor/docs/minitest", __dir__)
+      generate_markdown_docs(title: "minitest", root: root, output: output, files: minitest_docs_files(root))
+      puts "Generated minitest markdown docs in #{output}"
+    end
+
+    desc "Generate markdown docs for vendored rails"
+    task :rails do
+      root = File.expand_path("vendor/rails", __dir__)
+      raise "Missing vendor/rails. Run `rake vendor:setup:rails` first." unless Dir.exist?(root)
+
+      files = Dir[File.join(root, "*/lib/**/*.rb")]
+
+      active_record_readme = File.join(root, "activerecord/README.rdoc")
+      files << active_record_readme if File.file?(active_record_readme)
+
+      output = File.expand_path("vendor/docs/rails", __dir__)
+      generate_markdown_docs(title: "rails", root: root, output: output, files: files)
+      puts "Generated rails markdown docs in #{output}"
+    end
+
+    desc "Generate markdown docs for all vendored repositories"
+    task all: [:minitest, :rails]
+  end
+
+  desc "Generate markdown docs for all vendored repositories"
+  task docs: ["vendor:docs:all"]
+end

data/example/Bird.md

@@ -1,18 +1,24 @@
-# class Bird [](#class-Bird) [](#top)
+# Class Bird
+<a id="class-Bird"></a>
+
 The base class for all birds.
 
- ## Public Instance Methods
- ### fly(string, number) -> bool [](#method-i-fly)
- Fly somewhere.
+### Public Instance Methods
+
+#### `fly(string, number) -> bool`
+<a id="method-i-fly"></a>
+
+Fly somewhere.
 
 Flying is the most critical feature of birds.
 
-# Example[¶](#method-i-fly-label-Example) [↑](#top)
+##### Example
 
 ```
-fly(:south,70)
+fly(:south, 70)
 ```
- ### speak() { |text| ... } [](#method-i-speak)
- Produce some noise.
 
- 
+#### `speak() { |text| ... }`
+<a id="method-i-speak"></a>
+
+Produce some noise.

data/example/Duck.md

@@ -1,52 +1,64 @@
-# class Duck [](#class-Duck) [](#top)
-A duck is a [`Waterfowl`](Waterfowl.html) [`Bird`](Bird.html).
+# Class Duck
+<a id="class-Duck"></a>
+
+A duck is a [`Waterfowl`](Waterfowl.md) [`Bird`](Bird.md).
 
 Features:
 
-```
-bird::
-
- * speak
- * fly
-
-waterfowl::
-
- * swim
-```
- ## Constants
- | Name | Description |
- | ---- | ----------- |
- | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
- # Bird overrides
- ## Constants
- | Name | Description |
- | ---- | ----------- |
- | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
- ## Public Instance Methods
- ### speak() { |speech| ... } [](#method-i-speak)
- [`Duck`](Duck.html) overrides generic implementation.
-
- # Duck extensions
- ## Constants
- | Name | Description |
- | ---- | ----------- |
- | **MAX_VELOCITY[](#MAX_VELOCITY)** | Not documented |
- ## Attributes
- ### domestic[RW] [](#attribute-i-domestic)
- True for domestic ducks.
-
- ### rubber[R] [](#attribute-i-rubber)
- True for rubber ducks.
-
- ## Public Class Methods
- ### new(domestic, rubber) [](#method-c-new)
- Creates a new duck.
-
- ### rubber_ducks() [](#method-c-rubber_ducks)
- Returns list of all rubber ducks.
-
- ## Public Instance Methods
- ### useful? -> bool [](#method-i-useful-3F)
- Checks if this duck is a useful one.
-
- 
+bird:
+
+- speak
+- fly
+
+waterfowl:
+
+- swim
+
+## Bird overrides
+
+### Public Instance Methods
+
+#### `speak() { |speech| ... }`
+<a id="method-i-speak"></a>
+
+[`Duck`](Duck.md) overrides generic implementation.
+
+## Duck extensions
+
+### Constants
+
+#### `MAX_VELOCITY`
+<a id="MAX_VELOCITY"></a>
+
+Not documented.
+
+### Attributes
+
+#### `domestic` [RW]
+<a id="attribute-i-domestic"></a>
+
+True for domestic ducks.
+
+#### `rubber` [R]
+<a id="attribute-i-rubber"></a>
+
+True for rubber ducks.
+
+### Public Class Methods
+
+#### `new(domestic, rubber)`
+<a id="method-c-new"></a>
+
+Creates a new duck.
+
+#### `rubber_ducks()`
+<a id="method-c-rubber_ducks"></a>
+
+Returns list of all rubber ducks.
+
+### Public Instance Methods
+
+#### `useful? -> bool`
+<a id="method-i-useful-3F"></a>
+
+Checks if this duck is a useful one.

data/example/Object.md

@@ -1,6 +1,9 @@
-# class Object [](#class-Object) [](#top)
- ## Constants
- | Name | Description |
- | ---- | ----------- |
- | **DEFAULT_DUCK_VELOCITY[](#DEFAULT_DUCK_VELOCITY)** | Default velocity for a flying duck. |
- 
+# Class Object
+<a id="class-Object"></a>
+
+### Constants
+
+#### `DEFAULT_DUCK_VELOCITY`
+<a id="DEFAULT_DUCK_VELOCITY"></a>
+
+Default velocity for a flying duck.

data/example/Waterfowl.md

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