Update yardoc

* move to docs and add generated documentation
* include previous documentation versions
* Test doc did not change

Author: pitr-ch

.gitignore

@@ -7,7 +7,6 @@
 
 # Yard documentation
 /.yardoc
-/yardoc
 
 # IDEs' files
 *.iml

.travis.yml

@@ -15,11 +15,16 @@ matrix:
     - name: TruffleRuby Latest
       rvm: system
       install:
-        - export TRUFFLERUBY_VERSION=1.0.0-rc3
+        - export TRUFFLERUBY_VERSION=1.0.0-rc5
         - curl -L https://github.com/oracle/truffleruby/releases/download/vm-$TRUFFLERUBY_VERSION/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64.tar.gz | tar xz
         - export PATH="$PWD/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64/bin:$PATH"
         - gem install bundler
         - bundle install
+    - name: YARD uptodate in docs
+      rvm: 2.5.1
+      script:
+      - bundle install --with documentation
+      - bundle exec rake spec:docs_uptodate
 
     - name: MRI 2.4.4
       rvm: 2.4.4
@@ -52,15 +57,15 @@ matrix:
 
     - name: Coverage on MRI 2.3.7
       rvm: 2.3.7
-      jdk: oraclejdk8
       env: COVERAGE=1
 
   allow_failures:
+    - rvm: 2.6.0-preview2
     - rvm: ruby-head
     - rvm: jruby-head
     - rvm: rbx-3
-    - rvm: ruby-2.6.0-preview2
     - name: TruffleRuby Latest
+    - name: YARD uptodate in docs
 
 env:
   global:

.yardopts

@@ -1,18 +1,5 @@
---no-private
---embed-mixins
---output-dir ./yardoc
---markup markdown
---title=Concurrent Ruby
---template default
---template-path ./yard-template
---default-return undocumented
-
-./lib/**/*.rb
-./lib-edge/**/*.rb
-./ext/concurrent_ruby_ext/**/*.c
+--use-bundle-exec-rake-yard-instead
+--output-dir tmp
+--
+no-lib
 -
-doc/thread_pools.md
-doc/promises.out.md
-README.md
-LICENSE.txt
-CHANGELOG.md

Gemfile

@@ -19,7 +19,7 @@ end
 group :documentation, optional: true do
   gem 'yard', '~> 0.9.0', :require => false
   gem 'redcarpet', '~> 3.0', platforms: :mri # understands github markdown
-  gem 'md-ruby-eval'
+  gem 'md-ruby-eval', '~> 0.2'
 end
 
 group :testing do

README.md

@@ -16,7 +16,7 @@ Modern concurrency tools for Ruby. Inspired by
 [Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
 and classic concurrency patterns.
 
-<img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" />
+<img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc-source/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" />
 
 The design goals of this gem are:
 
@@ -58,7 +58,7 @@ other Ruby library, many of which support the mantra of
 Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and
 immutable variable types and data structures.
 
-We've also initiated discussion to document [memory model](doc/synchronization.md) of Ruby which 
+We've also initiated discussion to document [memory model](docs-source/synchronization.md) of Ruby which 
 would provide consistent behaviour and guarantees on all three of the main Ruby interpreters 
 (MRI/CRuby, JRuby, Rubinius, TruffleRuby).
 

Rakefile

@@ -31,8 +31,10 @@ require 'rake_compiler_dock'
 namespace :repackage do
   desc '- with Windows fat distributions'
   task :all do
-    sh 'bundle package'
-    RakeCompilerDock.exec 'support/cross_building.sh'
+    Dir.chdir(__dir__) do
+      sh 'bundle package'
+      RakeCompilerDock.exec 'support/cross_building.sh'
+    end
   end
 end
 
@@ -65,12 +67,14 @@ begin
 
     desc '- test packaged and installed gems instead of local files'
     task :installed => :repackage do
-      sh 'gem install pkg/concurrent-ruby-1.1.0.pre1.gem'
-      sh 'gem install pkg/concurrent-ruby-ext-1.1.0.pre1.gem' if Concurrent.on_cruby?
-      sh 'gem install pkg/concurrent-ruby-edge-0.4.0.pre1.gem'
-      ENV['NO_PATH'] = 'true'
-      sh 'bundle install'
-      sh 'bundle exec rake spec:ci'
+      Dir.chdir(__dir__) do
+        sh 'gem install pkg/concurrent-ruby-1.1.0.pre1.gem'
+        sh 'gem install pkg/concurrent-ruby-ext-1.1.0.pre1.gem' if Concurrent.on_cruby?
+        sh 'gem install pkg/concurrent-ruby-edge-0.4.0.pre1.gem'
+        ENV['NO_PATH'] = 'true'
+        sh 'bundle install'
+        sh 'bundle exec rake spec:ci'
+      end
     end
   end
 
@@ -87,56 +91,75 @@ begin
   require 'md_ruby_eval'
   require_relative 'support/yard_full_types'
 
-  root = File.expand_path File.dirname(__FILE__)
+  common_yard_options = ['--no-yardopts',
+                         '--no-document',
+                         '--no-private',
+                         '--embed-mixins',
+                         '--markup', 'markdown',
+                         '--title', 'Concurrent Ruby',
+                         '--template', 'default',
+                         '--template-path', 'yard-template',
+                         '--default-return', 'undocumented',]
 
-  cmd = lambda do |command|
-    puts ">> executing: #{command}"
-    puts ">>        in: #{Dir.pwd}"
-    system command or raise "#{command} failed"
-  end
-
-  yard_doc        = YARD::Rake::YardocTask.new(:yard)
-  yard_doc.before = -> do
-    Dir.chdir File.join(root, 'doc') do
-      cmd.call 'bundle exec md-ruby-eval --auto'
-    end
-  end
+  desc 'Generate YARD Documentation (signpost, master)'
+  task :yard => ['yard:signpost', 'yard:master']
 
   namespace :yard do
 
-    desc 'Pushes generated documentation to github pages: http://ruby-concurrency.github.io/concurrent-ruby/'
-    task :push => [:setup, :yard] do
-
-      message = Dir.chdir(root) do
-        `git log -n 1 --oneline`.strip
+    desc '- eval markdown files'
+    task :eval_md do
+      Dir.chdir File.join(__dir__, 'docs-source') do
+        sh 'bundle exec md-ruby-eval --auto'
       end
-      puts "Generating commit: #{message}"
+    end
 
-      Dir.chdir "#{root}/yardoc" do
-        cmd.call "git add -A"
-        cmd.call "git commit -m '#{message}'"
-        cmd.call 'git push origin gh-pages'
+    define_yard_task = -> name do
+      desc "- of #{name} into subdir #{name}"
+      YARD::Rake::YardocTask.new(name) do |yard|
+        yard.options.push(
+            '--output-dir', "docs/#{name}",
+            *common_yard_options)
+        yard.files = ['./lib/**/*.rb',
+                      './lib-edge/**/*.rb',
+                      './ext/concurrent_ruby_ext/**/*.c',
+                      '-',
+                      'docs-source/thread_pools.md',
+                      'docs-source/promises.out.md',
+                      'README.md',
+                      'LICENSE.txt',
+                      'CHANGELOG.md']
       end
-
+      Rake::Task[name].prerequisites.push 'yard:eval_md'
     end
 
-    desc 'Setups second clone in ./yardoc dir for pushing doc to github'
-    task :setup do
+    define_yard_task.call(Concurrent::VERSION.split('.')[0..2].join('.'))
+    define_yard_task.call('master')
 
-      unless File.exist? "#{root}/yardoc/.git"
-        cmd.call "rm -rf #{root}/yardoc" if File.exist?("#{root}/yardoc")
-        Dir.chdir "#{root}" do
-          cmd.call 'git clone --single-branch --branch gh-pages git@github.com:ruby-concurrency/concurrent-ruby.git ./yardoc'
+    desc "- signpost for versions"
+    YARD::Rake::YardocTask.new(:signpost) do |yard|
+      yard.options.push(
+          '--output-dir', 'docs',
+          '--main', 'docs-source/signpost.md',
+          *common_yard_options)
+      yard.files = ['no-lib']
+    end
+  end
+
+  namespace :spec do
+    desc '- ensure that generated documentation is matching the source code'
+    task :docs_uptodate do
+      Dir.chdir(__dir__) do
+        begin
+          FileUtils.cp_r 'docs', 'docs-copy', verbose: true
+          Rake::Task[:yard].invoke
+          sh 'diff -r docs/ docs-copy/'
+        ensure
+          FileUtils.rm_rf 'docs-copy', verbose: true
         end
       end
-      Dir.chdir "#{root}/yardoc" do
-        cmd.call 'git fetch origin'
-        cmd.call 'git reset --hard origin/gh-pages'
-      end
-
     end
-
   end
+
 rescue LoadError => e
   puts 'YARD is not installed, skipping documentation task definitions: ' + e.message
 end
@@ -150,34 +173,38 @@ namespace :release do
   task :build => 'repackage:all'
 
   task :test do
-    old = ENV['RBENV_VERSION']
+    Dir.chdir(__dir__) do
+      old = ENV['RBENV_VERSION']
 
-    ENV['RBENV_VERSION'] = mri_version
-    sh 'rbenv version'
-    sh 'bundle exec rake spec:installed'
+      ENV['RBENV_VERSION'] = mri_version
+      sh 'rbenv version'
+      sh 'bundle exec rake spec:installed'
 
-    ENV['RBENV_VERSION'] = jruby_version
-    sh 'rbenv version'
-    sh 'bundle exec rake spec:installed'
+      ENV['RBENV_VERSION'] = jruby_version
+      sh 'rbenv version'
+      sh 'bundle exec rake spec:installed'
 
-    puts 'Windows build is untested'
+      puts 'Windows build is untested'
 
-    ENV['RBENV_VERSION'] = old
+      ENV['RBENV_VERSION'] = old
+    end
   end
 
   task :push do
-    sh 'git fetch'
-    sh 'test $(git show-ref --verify --hash refs/heads/master) = $(git show-ref --verify --hash refs/remotes/github/master)'
-
-    sh "git tag v#{Concurrent::VERSION}"
-    sh "git tag edge-v#{Concurrent::EDGE_VERSION}"
-    sh "git push github v#{Concurrent::VERSION} edge-v#{Concurrent::EDGE_VERSION}"
-
-    sh "gem push pkg/concurrent-ruby-#{Concurrent::VERSION}.gem"
-    sh "gem push pkg/concurrent-ruby-edge-#{Concurrent::EDGE_VERSION}.gem"
-    sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}.gem"
-    sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}-x64-mingw32.gem"
-    sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}-x86-mingw32.gem"
+    Dir.chdir(__dir__) do
+      sh 'git fetch'
+      sh 'test $(git show-ref --verify --hash refs/heads/master) = $(git show-ref --verify --hash refs/remotes/github/master)'
+
+      sh "git tag v#{Concurrent::VERSION}"
+      sh "git tag edge-v#{Concurrent::EDGE_VERSION}"
+      sh "git push github v#{Concurrent::VERSION} edge-v#{Concurrent::EDGE_VERSION}"
+
+      sh "gem push pkg/concurrent-ruby-#{Concurrent::VERSION}.gem"
+      sh "gem push pkg/concurrent-ruby-edge-#{Concurrent::EDGE_VERSION}.gem"
+      sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}.gem"
+      sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}-x64-mingw32.gem"
+      sh "gem push pkg/concurrent-ruby-ext-#{Concurrent::VERSION}-x86-mingw32.gem"
+    end
   end
 
   task :notify do