rdoc-markdown 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 868f92bb775186af57b719c6aa821b0e69ba3cd27988ac3e3eb549c2e10600cb
-  data.tar.gz: 30fcdb498301cbdddf420b12792e53d2f9f427a30f9e16d5f67527dbf0137e6e
+  metadata.gz: d3d1c4068ecf819554e104801cbf461b722e150e0472bb4215ef96a887750e58
+  data.tar.gz: 5de0a95f8b8265b6877a43f85f14ef55f3a4ce7c5bc4bc972b22be104c91d959
 SHA512:
-  metadata.gz: 92914fc1b0e03ecb0fb09dd2fb1bca56c6222a27beb7c9eb63882a8644567ffa7de863ece0476d688fb91cefcc9b89fcc2949722299724ea90ea3bc768dc2d2d
-  data.tar.gz: 61672973b235fa35b149ff24ab9dc1fd22ccf2eb0d907bad436bde63f73c76ec1f116b143d009adb39d482c59529f2a69929f5786f2e6d48bb49b38ea7b8fc06
+  metadata.gz: 7a7863e3dbcf54782565a065f2997e90e3d5f4a5985e174f855dbd060c0afe6af9dd29239a08e2a6466690126370ae44d366bce012eb8b4612e3740a78704992
+  data.tar.gz: 71251348e64ae468b1b739925635aae9f79e003d5be8fef71b769fd757d72e532d8489375a2887adf606b433142b23b50ca93756f38eb88e6aaa57b22e344258

data/AGENTS.md

@@ -43,6 +43,7 @@ You are done when all of these are green and not reporting any issues:
 bundle exec rake test
 # don't run again if fail-fast has already passed
 bundle exec mutant run --fail-fast --since origin/main
+bundle exec standardrb --fix
 bundle exec rake markdown:validate
 bundle exec yard-lint
 bundle exec rake erb:lint

data/CHANGELOG.md

@@ -3,6 +3,15 @@
 
 ## Unreleased
 
+## 0.16.0
+
+- Don't convert markdown files from source folder. Just copy them.
+
+## 0.15.0
+
+- remove special files types (changelog, readme), just label everything 'File'
+- change "Page" file type to just "File"
+
 ## 0.14.0
 
 - BREAKING: Removing RDoc 7 compatibility code. Support RDoc 8 only.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.14.0)
+    rdoc-markdown (0.16.0)
       csv
       erb
       rdoc (>= 8.0)

data/README.md

@@ -35,6 +35,8 @@ 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.
 
+Input `.md` and `.markdown` pages are copied unchanged to the same relative path. RDoc pages and Ruby documentation are converted to Markdown.
+
 ### 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:
 
@@ -130,15 +132,19 @@ 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:reverse_markdown
 rake vendor:docs:rails
 # or generate all
 rake vendor:docs
 ```
 
+`rake vendor:setup` also checks out the dependency-aligned `reverse_markdown` source in `vendor/reverse_markdown`.
+
 Output is written to:
 
 - `vendor/docs/minitest`
 - `vendor/docs/jekyll-seo-tag`
+- `vendor/docs/reverse_markdown`
 - `vendor/docs/rails`
 
 ## Release

data/Rakefile

@@ -59,6 +59,18 @@ namespace :markdown do
     minitest_count = MarkdownValidator.new(minitest_output).validate!
     puts "Validated #{minitest_count} markdown files in #{minitest_output}"
 
+    Rake::Task["vendor:setup:reverse_markdown"].invoke
+    reverse_markdown_root = File.expand_path("vendor/reverse_markdown", __dir__)
+    reverse_markdown_output = File.join(validation_root, "reverse_markdown")
+    generate_markdown_docs(
+      title: "reverse_markdown",
+      root: reverse_markdown_root,
+      output: reverse_markdown_output,
+      files: reverse_markdown_docs_files(reverse_markdown_root)
+    )
+    reverse_markdown_count = MarkdownValidator.new(reverse_markdown_output).validate!
+    puts "Validated #{reverse_markdown_count} markdown files in #{reverse_markdown_output}"
+
     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)
@@ -168,6 +180,10 @@ def minitest_docs_files(root)
   files.uniq
 end
 
+def reverse_markdown_docs_files(root)
+  Dir[File.join(root, "lib/**/*.rb")] + Dir[File.join(root, "*.md")]
+end
+
 def rails_validation_files(root)
   files = Dir[File.join(root, "activesupport/lib/**/*.rb")]
   files.concat(Dir[File.join(root, "activerecord/lib/**/*.rb")])
@@ -176,9 +192,6 @@ def rails_validation_files(root)
 
   files.concat(Dir[File.join(root, "{active*,action*,railties}/README.{rdoc,md,markdown}")])
 
-  main_page = File.join(root, "railties/RDOC_MAIN.md")
-  files << main_page if File.file?(main_page)
-
   files.uniq
 end
 
@@ -186,6 +199,7 @@ namespace :vendor do
   namespace :setup do
     minitest_ref = "v6.0.1"
     rails_ref = ENV.fetch("RAILS_REF", "main")
+    reverse_markdown_ref = "v3.0.2"
 
     desc "Clone/update vendor/jekyll-seo-tag and checkout docs-aligned tag"
     task :jekyll_seo_tag do
@@ -210,10 +224,20 @@ namespace :vendor do
     task :rails do
       ensure_git_checkout(path: "vendor/rails", url: "https://github.com/rails/rails.git", ref: rails_ref)
     end
+
+    desc "Clone/update vendor/reverse_markdown and checkout dependency-aligned tag"
+    task :reverse_markdown do
+      ensure_git_checkout(
+        path: "vendor/reverse_markdown",
+        url: "https://github.com/xijo/reverse_markdown.git",
+        ref: reverse_markdown_ref
+      )
+      Dir.chdir("vendor/reverse_markdown") { sh "git checkout #{reverse_markdown_ref}" }
+    end
   end
 
   desc "Prepare all vendored repositories"
-  task setup: ["vendor:setup:jekyll_seo_tag", "vendor:setup:minitest", "vendor:setup:rails"]
+  task setup: ["vendor:setup:jekyll_seo_tag", "vendor:setup:minitest", "vendor:setup:rails", "vendor:setup:reverse_markdown"]
 
   namespace :docs do
     desc "Generate markdown docs for vendored jekyll-seo-tag"
@@ -233,6 +257,21 @@ namespace :vendor do
       puts "Generated minitest markdown docs in #{output}"
     end
 
+    desc "Generate markdown docs for vendored reverse_markdown"
+    task :reverse_markdown do
+      root = File.expand_path("vendor/reverse_markdown", __dir__)
+      raise "Missing vendor/reverse_markdown. Run `rake vendor:setup:reverse_markdown` first." unless Dir.exist?(root)
+
+      output = File.expand_path("vendor/docs/reverse_markdown", __dir__)
+      generate_markdown_docs(
+        title: "reverse_markdown",
+        root: root,
+        output: output,
+        files: reverse_markdown_docs_files(root)
+      )
+      puts "Generated reverse_markdown markdown docs in #{output}"
+    end
+
     desc "Generate markdown docs for vendored rails"
     task :rails do
       root = File.expand_path("vendor/rails", __dir__)
@@ -249,7 +288,7 @@ namespace :vendor do
     end
 
     desc "Generate markdown docs for all vendored repositories"
-    task all: [:jekyll_seo_tag, :minitest, :rails]
+    task all: [:jekyll_seo_tag, :minitest, :reverse_markdown, :rails]
   end
 
   desc "Generate markdown docs for all vendored repositories"

data/lib/rdoc/generator/markdown.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
-# shareable_constant_value: literal
 
 require "erb"
 require "reverse_markdown"
 require "csv"
+require "fileutils"
 require "optparse"
 
 # Generates Markdown output and a CSV search index from an RDoc store.
@@ -12,37 +12,12 @@ class RDoc::Generator::Markdown
 
   require_relative "markdown/crossref"
 
-  # Supported reverse_markdown unknown-tag modes.
-  MARKDOWN_UNKNOWN_TAGS = %i[pass_through drop bypass raise]
-
-  # Root source page basenames and their search-index types.
-  ROOT_PAGES = {
-    "readme" => "Readme",
-    "guide" => "Readme",
-    "changelog" => "Changelog",
-    "history" => "Changelog"
-  }
-
-  # Source page extensions eligible for root page classification.
-  ROOT_PAGE_EXTENSIONS = %w[.rdoc .md .markdown]
-
-  # Returns the configured search-index type for an eligible root text page path.
-  #
-  # @param source_path [String] Normalized source path relative to the root.
-  #
-  # @return [String, nil]
-  def self.root_page_type_for(source_path)
-    return unless File.dirname(source_path) == "."
-    return unless ROOT_PAGE_EXTENSIONS.include?(File.extname(source_path))
-
-    ROOT_PAGES[File.basename(source_path, ".*").downcase]
-  end
-
-  # shareable_constant_value: none
-
   # Directory containing ERB templates.
   TEMPLATE_DIR = File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "templates"))
 
+  # Supported reverse_markdown unknown-tag modes.
+  MARKDOWN_UNKNOWN_TAGS = %i[pass_through drop bypass raise].freeze
+
   # Adds rdoc-markdown generator configuration to RDoc's option object.
   module OptionsExtension
     # Initializes markdown generator options alongside RDoc's built-in options.
@@ -124,8 +99,6 @@ class RDoc::Generator::Markdown
     @store = store
     @options = rdoc_options
     @markdown_unknown_tags = self.class.validate_markdown_unknown_tags(rdoc_options.markdown_unknown_tags)
-
-    @expanded_root = Pathname(@options.root.to_s).expand_path
   end
 
   # Writes class files, page files, and the search index.
@@ -219,7 +192,7 @@ class RDoc::Generator::Markdown
       @pages.each do |page|
         csv << [
           page.page_name,
-          page_type(page),
+          "File",
           page_output_path(page)
         ]
       end
@@ -250,6 +223,8 @@ class RDoc::Generator::Markdown
       out_file = Pathname.new("#{output_dir}/#{page_output_path(page)}")
       out_file.dirname.mkpath
 
+      next FileUtils.cp(page.absolute_name, out_file) if page.relative_name.end_with?(".md", ".markdown")
+
       content = markdownify(render_description(page))
       File.write(out_file, finalize_markdown(
         content,
@@ -274,6 +249,8 @@ class RDoc::Generator::Markdown
   # @return [String] Relative Markdown path.
   def page_output_path(page)
     source_path = normalize_input_path_for_output(page.relative_name)
+    return source_path if page.relative_name.match?(/\.(?:md|markdown)\z/)
+
     dirname = File.dirname(source_path)
     basename = "#{File.basename(source_path).tr(".", "_")}.md"
 
@@ -282,26 +259,6 @@ class RDoc::Generator::Markdown
     "#{dirname}/#{basename}"
   end
 
-  # Checks whether a text page is the configured main page.
-  #
-  # @param page [RDoc::TopLevel] Page object to index.
-  #
-  # @return [Boolean]
-  def main_page?(page)
-    normalize_input_path_for_output(page.full_name) == normalize_input_path_for_output(@options.main_page.to_s)
-  end
-
-  # Returns the search-index type for a text page.
-  #
-  # @param page [RDoc::TopLevel] Page object to index.
-  #
-  # @return [String]
-  def page_type(page)
-    return "Readme" if main_page?(page)
-
-    self.class.root_page_type_for(normalize_input_path_for_output(page.relative_name)) || "Page"
-  end
-
   # Returns the normalized display name for a class or module.
   #
   # @param code_object [RDoc::Context] Class or module object.
@@ -740,6 +697,7 @@ class RDoc::Generator::Markdown
   # @return [String, nil] Resolved output path, or nil when unresolved.
   def resolve_output_path(path, current_dir)
     candidates = [path, path.delete_prefix("#{@root_path_segment}/")]
+    candidates += candidates.map { |candidate| candidate.sub(/_(md|markdown)\.md\z/, '.\1') }
 
     candidates.each do |candidate|
       return candidate if @known_output_paths.include?(candidate)
@@ -761,7 +719,7 @@ class RDoc::Generator::Markdown
   def normalize_input_path_for_output(path)
     normalized = path.tr("\\", "/").sub(%r{\A\./}, "")
 
-    root = @expanded_root.to_s
+    root = File.expand_path(@options.root.to_s)
     normalized = normalized.sub(%r{\A#{Regexp.escape(root)}/}, "")
     normalized = normalized.sub(%r{\A/}, "")
 

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # @private
   module Markdown
     # @private
-    VERSION = "0.14.0"
+    VERSION = "0.16.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov