Add YARD documentation to ruby-git (#502)

Signed-off-by: James Couball <jcouball@yahoo.com>

.gitignore

@@ -3,6 +3,8 @@
 *.sw?
 .DS_Store
 coverage
+doc
+.yardoc
 pkg
 rdoc
 Gemfile.lock

.yardopts

@@ -0,0 +1,11 @@
+--default-return=''
+--hide-void-return
+--markup-provider=redcarpet
+--markup=markdown
+--fail-on-warning
+-
+README.md
+CHANGELOG.md
+CONTRIBUTING.md
+RELEASING.md
+MAINTAINERS.md

CHANGELOG.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title Change Log
+-->
+
 # Change Log
 
 ## 1.7.0

CONTRIBUTING.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title How To Contribute
+-->
+
 # Contributing to ruby-git
 
 Thank you for your interest in contributing to the ruby-git project.
@@ -8,7 +13,7 @@ judgement.
 
 Propose changes to these guidelines with a pull request.
 
-## How to contribute to ruby-git
+## How to contribute
 
 You can contribute in two ways:
 

MAINTAINERS.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title Maintainers
+-->
+
 # Maintainers
 
 When making changes in this repository, one of the maintainers below must review and approve your pull request.

README.md

@@ -1,13 +1,36 @@
-# Git Library for Ruby
+<!--
+# @markup markdown
+# @title README
+-->
 
-Library for using Git in Ruby.
+# The Git Gem
+
+The Git Gem provides an API that can be used to create, read, and manipulate
+Git repositories by wrapping system calls to the `git` binary. The API can be
+used for working with Git in complex interactions including branching and
+merging, object inspection and manipulation, history, patch generation and
+more.
 
 ## Homepage
 
-Git public hosting of the project source code is at:
+The project source code is at:
 
 http://github.com/ruby-git/ruby-git
 
+## Documentation
+
+Detailed documentation can be found at:
+
+https://rubydoc.info/gems/git/Git.html
+
+Get started by obtaining a repository object by:
+
+* opening an existing working copy with [Git.open](https://rubydoc.info/gems/git/Git#open-class_method)
+* initializing a new repository with [Git.init](https://rubydoc.info/gems/git/Git#init-class_method)
+* cloning a repository with [Git.clone](https://rubydoc.info/gems/git/Git#clone-class_method)
+
+Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
+
 ## Install
 
 You can install Ruby/Git like this:

RELEASING.md

@@ -1,3 +1,8 @@
+<!--
+# @markup markdown
+# @title Releasing
+-->
+
 # How to release a new git.gem
 
 Releasing a new version of the `git` gem requires these steps:

Rakefile

@@ -1,16 +1,44 @@
 require 'bundler/gem_tasks'
-require 'rubygems'
 
 require "#{File.expand_path(File.dirname(__FILE__))}/lib/git/version"
 
-task :default => :test
+default_tasks = []
 
 desc 'Run Unit Tests'
-task :test do |t|
+task :test do
   sh 'git config --global user.email "git@example.com"' if `git config user.email`.empty?
   sh 'git config --global user.name "GitExample"' if `git config user.name`.empty?
 
-  $VERBOSE = true
-
   require File.dirname(__FILE__) + '/tests/all_tests.rb'
 end
+default_tasks << :test
+
+unless RUBY_PLATFORM == 'java'
+  #
+  # YARD documentation for this project can NOT be built with JRuby.
+  # This project uses the redcarpet gem which can not be installed on JRuby.
+  #
+  require 'yard'
+  YARD::Rake::YardocTask.new
+  CLEAN << '.yardoc'
+  CLEAN << 'doc'
+  default_tasks << :yard
+
+  require 'yardstick/rake/verify'
+  Yardstick::Rake::Verify.new(:'yardstick:coverage') do |t|
+    t.threshold = 50
+    t.require_exact_threshold = false
+  end
+  default_tasks << :'yardstick:coverage'
+
+  desc 'Run yardstick to check yard docs'
+  task :yardstick do
+    sh "yardstick 'lib/**/*.rb'"
+  end
+  # Do not include yardstick as a default task for now since there are too many
+  # warnings.  Will work to get the warnings down before re-enabling it.
+  #
+  # default_tasks << :yardstick
+end
+
+task default: default_tasks

git.gemspec

@@ -7,23 +7,36 @@ Gem::Specification.new do |s|
   s.homepage = 'http://github.com/ruby-git/ruby-git'
   s.license = 'MIT'
   s.name = 'git'
-  s.summary = 'Ruby/Git is a Ruby library that can be used to create, read and manipulate Git repositories by wrapping system calls to the git binary.'
+  s.summary = 'An API to create, read, and manipulate Git repositories'
+  s.description = <<~DESCRIPTION
+    The Git Gem provides an API that can be used to create, read, and manipulate
+    Git repositories by wrapping system calls to the `git` binary. The API can be
+    used for working with Git in complex interactions including branching and
+    merging, object inspection and manipulation, history, patch generation and
+    more.
+  DESCRIPTION
   s.version = Git::VERSION
 
+  s.metadata['homepage_uri'] = s.homepage
+  s.metadata['source_code_uri'] = s.homepage
+  s.metadata['changelog_uri'] = 'http://rubydoc.info/gems/git/file.CHANGELOG.html'
+
   s.require_paths = ['lib']
   s.required_ruby_version = '>= 2.3'
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to?(:required_rubygems_version=)
   s.requirements = ['git 1.6.0.0, or greater']
 
   s.add_runtime_dependency 'rchardet', '~> 1.8'
 
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'rdoc'
-  s.add_development_dependency 'minitar', '0.9'
-  s.add_development_dependency 'test-unit', '>=2', '< 4'
+  s.add_development_dependency 'minitar', '~> 0.9'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'test-unit', '~> 3.3'
 
-  s.extra_rdoc_files = ['README.md']
-  s.rdoc_options = ['--charset=UTF-8']
+  unless RUBY_PLATFORM == 'java'
+    s.add_development_dependency 'redcarpet', '~> 3.5'
+    s.add_development_dependency 'yard', '~> 0.9'
+    s.add_development_dependency 'yardstick', '~> 0.9'
+  end
 
   s.files = [
     'CHANGELOG.md',