Adds Ruby source code documentation to docs.dev.to (#2656)

* Add YARD and plugins to generate source code doc

* Expose yard Ruby doc in gitdocs

* Add yard doc step to Travis

* Tell netlify to build the docs before deploying

* Add Gemfile for Ruby prerequisites and Makefile

* Makefile uses tabs, not spaces

* Build ruby-doc and then gitdocs

* Add recent Ruby version to make sure yard plugins work

* Switch Ruby to a pre-built version inside Netlify

* Add ActiveRecord for the yard-activerecord plugin

* Add Ruby doc header link and info to build it locally

.gitignore

@@ -55,3 +55,6 @@ package-lock.json
 
 # Development Docker storage location
 _docker-storage/
+
+# YARD generated doc (in the Gitdocs folder)
+docs/.static/ruby-doc/

.yardopts

@@ -0,0 +1 @@
+--no-cache --no-save --protected --private --charset utf-8 --plugin yard-activerecord --plugin yard-activesupport-concern

Gemfile

@@ -117,6 +117,9 @@ group :development do
   gem "pry", "~> 0.12" # An IRB alternative and runtime developer console
   gem "pry-rails", "~> 0.3" # Use Pry as your rails console
   gem "web-console", "~> 3.7" # Rails Console on the Browser
+  gem "yard-activerecord", "~> 0.0.16" # YARD extension that handles and interprets methods used when developing applications with ActiveRecord
+  gem "yard-activesupport-concern", "~> 0.0.1" # YARD extension that brings support for modules making use of ActiveSupport::Concern
+  gem "yard", "~> 0.9.19" # YARD is a documentation generation tool for the Ruby programming language
 end
 
 group :development, :test do

Gemfile.lock

@@ -812,6 +812,11 @@ GEM
     xpath (3.2.0)
       nokogiri (~> 1.8)
     yajl-ruby (1.4.1)
+    yard (0.9.19)
+    yard-activerecord (0.0.16)
+      yard (>= 0.8.3)
+    yard-activesupport-concern (0.0.1)
+      yard (>= 0.8)
     zonebie (0.6.1)
 
 PLATFORMS
@@ -947,6 +952,9 @@ DEPENDENCIES
   webmock (~> 3.5)
   webpacker (~> 3.5)
   webpush (~> 0.3)
+  yard (~> 0.9.19)
+  yard-activerecord (~> 0.0.16)
+  yard-activesupport-concern (~> 0.0.1)
   zonebie (~> 0.6.1)
 
 RUBY VERSION

docs/.gitdocs.json

@@ -12,6 +12,11 @@
       "title": "DEV",
       "href": "https://dev.to",
       "target": "_blank"
+    },
+    {
+      "title": "Ruby doc",
+      "href": "http://docs.dev.to/ruby-doc",
+      "target": "_blank"
     }
   ]
 }

docs/.ruby-version

@@ -0,0 +1 @@
+2.6.2

docs/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gem "activerecord", "~> 5.2.3" # Databases on Rails
+gem "yard-activerecord", "~> 0.0.16" # YARD extension that handles and interprets methods used when developing applications with ActiveRecord
+gem "yard-activesupport-concern", "~> 0.0.1" # YARD extension that brings support for modules making use of ActiveSupport::Concern
+gem "yard", "~> 0.9.19" # YARD is a documentation generation tool for the Ruby programming language

docs/Makefile

@@ -0,0 +1,10 @@
+.PHONY: build
+
+build: ruby-doc gitdocs
+
+ruby-doc:
+  # docs/.static/ruby-doc will let gitdocs serve the Ruby doc as static content
+	cd .. && yard doc -o docs/.static/ruby-doc
+
+gitdocs:
+	npm install -g gitdocs@latest && gitdocs build

docs/faqs.md

@@ -3,3 +3,12 @@ title: FAQs
 ---
 
 # Frequently Asked Questions
+
+## How do I build my local copy of the Ruby source code documentation?
+
+```shell
+cd docs
+make ruby-doc
+```
+
+Then open `.static/ruby-doc/index.html` in the `docs` directory and browse the Ruby documentation

netlify.toml

@@ -7,9 +7,17 @@
 
 [build]
   base = "docs/"
+  command = "make"
+
 [[redirects]]
   from = "http://docs.dev.to"
   to = "https://docs.dev.to"
+[[redirects]]
+  from = "http://docs.dev.to/ruby-doc"
+  to = "https://docs.dev.to/ruby-doc/index.html"
+[[redirects]]
+  from = "http://docs.dev.to/ruby-doc/"
+  to = "https://docs.dev.to/ruby-doc/index.html"
 [[redirects]]
   from = "http://docs.dev.to/*"
   to = "https://docs.dev.to/:splat"