rdoc-markdown 0.6.0 → 0.8.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.6.0)
+    rdoc-markdown (0.8.0)
       csv
       erb
       rdoc
@@ -10,64 +10,194 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    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)
+    actionview (8.1.3)
+      activesupport (= 8.1.3)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    better_html (2.2.0)
+      actionview (>= 7.0)
+      activesupport (>= 7.0)
+      ast (~> 2.0)
+      erubi (~> 1.4)
+      parser (>= 2.4)
+      smart_properties
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    commonmarker (2.8.1-x86_64-linux)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crass (1.0.6)
     csv (3.3.5)
     date (3.5.1)
-    erb (6.0.1)
+    diff-lcs (2.0.0)
+    docile (1.4.1)
+    drb (2.2.3)
+    erb (6.0.4)
+    erb_lint (0.9.0)
+      activesupport
+      better_html (>= 2.0.1)
+      parser (>= 2.7.1.4)
+      rainbow
+      rubocop (>= 1)
+      smart_properties
+    erubi (1.13.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.4)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
     minitest (5.27.0)
-    nokogiri (1.19.0-aarch64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.0-aarch64-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.19.0-arm-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.0-arm-linux-musl)
-      racc (~> 1.4)
-    nokogiri (1.19.0-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.19.0-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.19.0-x86_64-linux-gnu)
-      racc (~> 1.4)
-    nokogiri (1.19.0-x86_64-linux-musl)
+    minitest-strict (1.0.0)
+      minitest (>= 5.21, < 7)
+    mutant (0.16.2)
+      diff-lcs (>= 1.6, < 3)
+      irb (~> 1.15)
+      parser (~> 3.3.10)
+      regexp_parser (~> 2.10)
+      securerandom (>= 0.3)
+      sorbet-runtime (~> 0.6.0)
+      unparser (>= 0.8.2, < 0.10)
+    mutant-minitest (0.16.2)
+      minitest (>= 5.11, < 7)
+      mutant (= 0.16.2)
+      mutex_m (~> 0.2)
+    mutex_m (0.3.0)
+    nokogiri (1.19.2-x86_64-linux-gnu)
       racc (~> 1.4)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
     psych (5.3.1)
       date
       stringio
     racc (1.8.1)
-    rake (13.3.1)
-    rdiscount (2.2.7.3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rdiscount (2.2.7.4)
     rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
     reverse_markdown (3.0.2)
       nokogiri
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    smart_properties (1.17.0)
+    sorbet-runtime (0.6.13163)
+    standard (1.54.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.84.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
     stringio (3.2.0)
     tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    unparser (0.9.0)
+      diff-lcs (>= 1.6, < 3)
+      parser (>= 3.3.0)
+      prism (>= 1.5.1)
+    uri (1.1.1)
+    yard (0.9.43)
+    yard-lint (1.5.1)
+      yard (~> 0.9)
+      zeitwerk (~> 2.6)
+    zeitwerk (2.7.5)
 
 PLATFORMS
-  aarch64-linux-gnu
-  aarch64-linux-musl
-  arm-linux-gnu
-  arm-linux-musl
-  arm64-darwin
-  x86_64-darwin
   x86_64-linux-gnu
-  x86_64-linux-musl
 
 DEPENDENCIES
-  bundler (~> 2.0)
+  bundler (>= 2.0)
   commonmarker
+  erb_lint
   minitest (~> 5.0)
+  minitest-strict (~> 1.0)
+  mutant
+  mutant-minitest
+  mutex_m
   rake (~> 13.0)
   rdiscount (~> 2.0)
   rdoc-markdown!
+  simplecov (~> 0.22)
+  standard
+  yard-lint
 
 BUNDLED WITH
-   2.6.1
+  4.0.10

data/README.md

@@ -1,10 +1,15 @@
 # RDoc-Markdown
 RDoc plugin to generate markdown documentation and search index file (CSV).
 
+> [!CAUTION]
+> This gem relies on multiple hacks to generate "plausible" markdown documentation. This is **NOT PRODUCTION READY**, use at your own risk.
+>
+> rdoc maintainers are actively working on markdown support, things will improve with time... 
+
 ## 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).
+Markdown has become the de-facto documentation standard. We can render markdown file on any device, possibly on thermometer with a screen. And everyone knows markdown...
 
-It's a pitty that rdoc and yard can't output a proper markdown file. I would like to change that.
+It's a pitty that rdoc can't output a proper markdown file. Somebody has to try and build it.
 
 ## Installation
 
@@ -16,7 +21,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install rdoc-markdown
 ## Examples
-Find examples in [/examples](/example/) folder. You can regenerate examples by running `./bin/generate.sh`, it will produce examples based on file in `test/data/*` folder.
+Find examples in [/example](/example/) folder. You can regenerate examples by running `./bin/generate.sh`; it produces the sample docs from `test/data/example.rb` and a pinned `jekyll-seo-tag` example from `vendor/jekyll-seo-tag`.
 
 
 ## Usage
@@ -28,6 +33,22 @@ 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.
 
+### Unknown HTML tags
+rdoc-markdown uses `reverse_markdown` to convert RDoc's HTML fragments to Markdown. You can configure how unknown HTML tags are handled with:
+
+```sh
+rdoc --format=markdown --markdown-unknown-tags=raise
+```
+
+Accepted values are `pass_through`, `drop`, `bypass`, and `raise`. The default is `pass_through`, which matches `reverse_markdown`'s default behavior.
+
+The same setting can be stored in RDoc's `.rdoc_options` file:
+
+```yaml
+---
+markdown_unknown_tags: :raise
+```
+
 ## Note on index.csv file
 This gem emits index of all markdown files in a index.csv file.
 
@@ -57,6 +78,7 @@ Following command should run entire testsuit:
 ```
 rake test
 ```
+The test suite loads `minitest-strict`, so boolean and nil assertions only pass on exact `true`, `false`, and `nil` values.
 Testing is not excessive, just verifies that basic functionality is operational.
 
 To validate generated markdown against GitHub Flavored Markdown and check local links/anchors:
@@ -69,6 +91,7 @@ This task validates:
 
 - generated sample docs,
 - checked-in `example/` docs,
+- generated `jekyll-seo-tag` docs,
 - vendored minitest docs,
 - vendored rails docs (Active Support, Active Record, Action Pack, Railties slices).
 
@@ -81,6 +104,12 @@ MARKDOWN_VALIDATE_STRICT_VENDOR=1 rake markdown:validate
 
 This task is also executed in CI.
 
+To lint markdown ERB templates:
+
+```
+bundle exec rake erb:lint
+```
+
 ### Integration harness: minitest
 To run the integration harness against minitest (aligned with docs.seattlerb.org/minitest):
 
@@ -106,15 +135,17 @@ Use rake tasks to generate markdown output for vendored projects:
 
 ```
 rake vendor:setup
+rake vendor:docs:jekyll_seo_tag
 rake vendor:docs:minitest
 rake vendor:docs:rails
-# or generate both
+# or generate all
 rake vendor:docs
 ```
 
 Output is written to:
 
 - `vendor/docs/minitest`
+- `vendor/docs/jekyll-seo-tag`
 - `vendor/docs/rails`
 
 ## Release

data/Rakefile

@@ -5,6 +5,11 @@ require "rdoc/rdoc"
 require "rdoc/markdown"
 require_relative "test/support/markdown_validator"
 
+JEKYLL_SEO_TAG_NAME = "jekyll-seo-tag"
+JEKYLL_SEO_TAG_REF = "v2.8.0"
+JEKYLL_SEO_TAG_TITLE = "#{JEKYLL_SEO_TAG_NAME} #{JEKYLL_SEO_TAG_REF.delete_prefix("v")}"
+JEKYLL_SEO_TAG_VENDOR_PATH = "vendor/#{JEKYLL_SEO_TAG_NAME}"
+
 Rake::TestTask.new do |t|
   t.verbose = true
   t.warning = false
@@ -13,6 +18,13 @@ end
 
 task default: [:test]
 
+namespace :erb do
+  desc "Lint markdown ERB templates"
+  task :lint do
+    sh "bundle exec erb_lint --lint-all"
+  end
+end
+
 namespace :markdown do
   desc "Validate generated markdown as GitHub Flavored Markdown"
   task :validate do
@@ -22,12 +34,7 @@ namespace :markdown do
     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__)]
-    )
+    generate_sample_docs(output: sample_output)
 
     sample_count = MarkdownValidator.new(sample_output).validate!
     puts "Validated #{sample_count} markdown files in #{sample_output}"
@@ -52,6 +59,14 @@ namespace :markdown do
     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:jekyll_seo_tag"].invoke
+    jekyll_seo_tag_output = File.join(validation_root, JEKYLL_SEO_TAG_NAME)
+    generate_jekyll_seo_tag_docs(output: jekyll_seo_tag_output)
+    jekyll_seo_tag_validator = MarkdownValidator.new(jekyll_seo_tag_output, strict_links: strict_vendor_links)
+    jekyll_seo_tag_count = jekyll_seo_tag_validator.validate!
+    puts "Validated #{jekyll_seo_tag_count} markdown files in #{jekyll_seo_tag_output}"
+    puts "Skipped #{jekyll_seo_tag_validator.unresolved_links} unresolved local links in vendored jekyll-seo-tag docs"
+
     Rake::Task["vendor:setup:rails"].invoke
     rails_root = File.expand_path("vendor/rails", __dir__)
     rails_output = File.join(validation_root, "rails")
@@ -100,13 +115,60 @@ def generate_markdown_docs(title:, root:, output:, files:)
   RDoc::RDoc.new.document(options)
 end
 
+def generate_sample_docs(output:)
+  generate_markdown_docs(
+    title: "sample",
+    root: File.expand_path("test/data", __dir__),
+    output: output,
+    files: [File.expand_path("test/data/example.rb", __dir__)]
+  )
+end
+
+def jekyll_seo_tag_root
+  File.expand_path(JEKYLL_SEO_TAG_VENDOR_PATH, __dir__)
+end
+
+def generate_jekyll_seo_tag_docs(output:)
+  root = jekyll_seo_tag_root
+  unless Dir.exist?(root)
+    raise "Missing #{JEKYLL_SEO_TAG_VENDOR_PATH}. Run `rake vendor:setup:jekyll_seo_tag` first."
+  end
+
+  generate_markdown_docs(
+    title: JEKYLL_SEO_TAG_TITLE,
+    root: root,
+    output: output,
+    files: Dir[File.join(root, "lib/**/*.rb")].uniq
+  )
+end
+
+namespace :examples do
+  desc "Generate checked-in example markdown docs"
+  task :generate do
+    Rake::Task["vendor:setup:jekyll_seo_tag"].invoke
+
+    sample_output = File.expand_path("example", __dir__)
+    staging_root = File.expand_path("tmp/examples-generate", __dir__)
+    staged_sample_output = File.join(staging_root, "example")
+
+    FileUtils.rm_rf(staging_root)
+    generate_sample_docs(output: staged_sample_output)
+    generate_jekyll_seo_tag_docs(output: File.join(staged_sample_output, JEKYLL_SEO_TAG_NAME))
+
+    FileUtils.rm_rf(sample_output)
+    FileUtils.mv(staged_sample_output, sample_output)
+
+    puts "Generated sample markdown docs in #{sample_output}"
+    puts "Generated #{JEKYLL_SEO_TAG_NAME} markdown docs in #{File.join(sample_output, JEKYLL_SEO_TAG_NAME)}"
+  ensure
+    FileUtils.rm_rf(staging_root) if staging_root
+  end
+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
 
@@ -131,25 +193,45 @@ end
 
 namespace :vendor do
   namespace :setup do
-    MINITEST_REF = "v6.0.1"
-    RAILS_REF = ENV.fetch("RAILS_REF", "main")
+    minitest_ref = "v6.0.1"
+    rails_ref = ENV.fetch("RAILS_REF", "main")
+
+    desc "Clone/update vendor/jekyll-seo-tag and checkout docs-aligned tag"
+    task :jekyll_seo_tag do
+      ensure_git_checkout(
+        path: JEKYLL_SEO_TAG_VENDOR_PATH,
+        url: "https://github.com/jekyll/jekyll-seo-tag.git",
+        ref: JEKYLL_SEO_TAG_REF
+      )
+      Dir.chdir(JEKYLL_SEO_TAG_VENDOR_PATH) do
+        sh "git fetch --tags --force"
+        sh "git checkout #{JEKYLL_SEO_TAG_REF}"
+      end
+    end
 
     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}" }
+      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)
+      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"]
+  task setup: ["vendor:setup:jekyll_seo_tag", "vendor:setup:minitest", "vendor:setup:rails"]
 
   namespace :docs do
+    desc "Generate markdown docs for vendored jekyll-seo-tag"
+    task :jekyll_seo_tag do
+      output = File.expand_path("vendor/docs/#{JEKYLL_SEO_TAG_NAME}", __dir__)
+      generate_jekyll_seo_tag_docs(output: output)
+      puts "Generated #{JEKYLL_SEO_TAG_NAME} markdown docs in #{output}"
+    end
+
     desc "Generate markdown docs for vendored minitest"
     task :minitest do
       root = File.expand_path("vendor/minitest", __dir__)
@@ -176,7 +258,7 @@ namespace :vendor do
     end
 
     desc "Generate markdown docs for all vendored repositories"
-    task all: [:minitest, :rails]
+    task all: [:jekyll_seo_tag, :minitest, :rails]
   end
 
   desc "Generate markdown docs for all vendored repositories"

data/example/Bird.md

@@ -1,11 +1,11 @@
 # Class Bird
-<a id="class-Bird"></a>
+<a id="class-bird"></a>
 
 The base class for all birds.
 
 ### Public Instance Methods
 
-#### `fly(string, number) -> bool`
+#### `fly(direction: string, velocity: number) -> bool`
 <a id="method-i-fly"></a>
 
 Fly somewhere.

data/example/Duck.md

@@ -1,5 +1,5 @@
 # Class Duck
-<a id="class-Duck"></a>
+<a id="class-duck"></a>
 
 A duck is a [`Waterfowl`](Waterfowl.md) [`Bird`](Bird.md).
 

data/example/Object.md

@@ -1,5 +1,5 @@
 # Class Object
-<a id="class-Object"></a>
+<a id="class-object"></a>
 
 ### Constants
 

data/example/Waterfowl.md

@@ -1,5 +1,5 @@
 # Module Waterfowl
-<a id="module-Waterfowl"></a>
+<a id="module-waterfowl"></a>
 
 A mixin for waterfowl creatures.
 

data/example/jekyll-seo-tag/Jekyll/SeoTag/AuthorDrop.md

@@ -0,0 +1,40 @@
+# Class Jekyll::SeoTag::AuthorDrop
+<a id="class-jekyll-seotag-authordrop"></a>
+
+A drop representing the current page’s author
+
+Author name will be pulled from:
+
+1. The page’s `author` key
+
+2. The first author in the page’s `authors` key
+
+3. The `author` key in the site config
+
+If the result from the name search is a string, we’ll also check for additional author metadata in `site.data.authors`
+
+### Public Class Methods
+
+#### `new(page: nil, site: nil)`
+<a id="method-c-new"></a>
+
+Initialize a new [`AuthorDrop`](AuthorDrop.md)
+
+page - The page hash (e.g., Page#to\_liquid) site - The Jekyll::Drops::SiteDrop
+
+### Public Instance Methods
+
+#### `name()`
+<a id="method-i-name"></a>
+
+[`AuthorDrop#to_s`](AuthorDrop.md#method-i-to_s) should return name, allowing the author drop to safely replace `page.author`, if necessary, and remain backwards compatible
+
+#### `to_s()`
+<a id="method-i-to_s"></a>
+
+Alias for: [`name`](#method-i-name)
+
+#### `twitter()`
+<a id="method-i-twitter"></a>
+
+Not documented.