resolves #1231 sort README files

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

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
 

spec/cli/yardoc_spec.rb

@@ -647,13 +647,47 @@ 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('')
       @yardoc.parse_arguments(*%w(--one-file lib/*.rb))
       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