From 88da7e6b4279bd84f8475c39b23447786cb2fb0b Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Sat, 30 Mar 2019 02:18:22 -0600
Subject: [PATCH] resolves #1231 sort README files

- sort README files, first by file extension, then by basename
- prefer README basename over all other files
- prefer file without extension over file with extension
- don't glob for files if README is missing and files list is empty
---
 Gemfile                 |  3 +--
 lib/yard/cli/yardoc.rb  | 11 +++++++++--
 spec/cli/yardoc_spec.rb | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 4 deletions(-)

diff --git a/Gemfile b/Gemfile
index 27e7f8d2f..d87863fb6 100644
--- a/Gemfile
+++ b/Gemfile
@@ -13,8 +13,7 @@ group :development do
 end
 
 group :asciidoc do
-  # Asciidoctor 2.0 drops support for Ruby < 2.3.
-  gem 'asciidoctor', RUBY_VERSION < '2.3' ? '< 2' : '>= 0'
+  gem 'asciidoctor'
 end
 
 group :markdown do
diff --git a/lib/yard/cli/yardoc.rb b/lib/yard/cli/yardoc.rb
index 7d356c3fa..dc2b4bdf1 100644
--- a/lib/yard/cli/yardoc.rb
+++ b/lib/yard/cli/yardoc.rb
@@ -294,8 +294,15 @@ def parse_arguments(*args)
         # Last minute modifications
         self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if files.empty?
         files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
-        readme = Dir.glob('README{,*[^~]}').first
-        readme ||= Dir.glob(files.first).first if options.onefile
+        readmes = Dir.glob('README{,*[^~]}')
+        if readmes.empty?
+          readme = Dir.glob(files.first).first if options.onefile && !files.empty?
+        else
+          readme = readmes.
+            sort {|a, b| File.extname(a) <=> File.extname(b) }.
+            sort {|a, b| a.slice(0, a.rindex('.') || a.length) <=> b.slice(0, b.rindex('.') || b.length) }.
+            first
+        end
         options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme
         options.files.unshift(options.readme).uniq! if options.readme
 
diff --git a/spec/cli/yardoc_spec.rb b/spec/cli/yardoc_spec.rb
index 58f9a9b4d..65c4824d1 100644
--- a/spec/cli/yardoc_spec.rb
+++ b/spec/cli/yardoc_spec.rb
@@ -647,6 +647,12 @@ def foo; end
       expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('lib/foo.rb', '')
     end
 
+    it "uses no readme if files is empty and no readme is specified when using --one-file" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
+      @yardoc.parse_arguments '--one-file', ''
+      expect(@yardoc.options.readme).to be_nil
+    end
+
     it "uses readme it exists when using --one-file" do
       expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README']
       expect(File).to receive(:read).with('README').and_return('')
@@ -654,6 +660,34 @@ def foo; end
       expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
     end
 
+    it "selects readme with no file extension over readme with file extension" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.md', 'README']
+      expect(File).to receive(:read).with('README').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
+    end
+
+    it "selects readme with no suffix over readme with hyphenated suffix" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README.md', 'README-de.md']
+      expect(File).to receive(:read).with('README.md').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.md', '')
+    end
+
+    it "selects readme with no suffix over readme with dotted suffix" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.fr.md', 'README.md', 'README.de.md']
+      expect(File).to receive(:read).with('README.md').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.md', '')
+    end
+
+    it "selects first readme from lexically sorted list" do
+      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README-de.md']
+      expect(File).to receive(:read).with('README-de.md').and_return('')
+      @yardoc.parse_arguments
+      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README-de.md', '')
+    end
+
     it "does not allow US-ASCII charset when using --one-file" do
       ienc = Encoding.default_internal
       eenc = Encoding.default_external