From fb9a407b21de2381525321e7dce505131ecda1f7 Mon Sep 17 00:00:00 2001 From: rhymes Date: Thu, 2 May 2019 19:50:58 +0200 Subject: [PATCH] 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 | 3 +++ .yardopts | 1 + Gemfile | 3 +++ Gemfile.lock | 8 ++++++++ docs/.gitdocs.json | 5 +++++ docs/.ruby-version | 1 + docs/Gemfile | 10 ++++++++++ docs/Makefile | 10 ++++++++++ docs/faqs.md | 9 +++++++++ netlify.toml | 8 ++++++++ 10 files changed, 58 insertions(+) create mode 100644 .yardopts create mode 100644 docs/.ruby-version create mode 100644 docs/Gemfile create mode 100644 docs/Makefile diff --git a/.gitignore b/.gitignore index 0e3cba717..1ff4e03e2 100644 --- a/.gitignore +++ b/.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/ diff --git a/.yardopts b/.yardopts new file mode 100644 index 000000000..36c24e494 --- /dev/null +++ b/.yardopts @@ -0,0 +1 @@ +--no-cache --no-save --protected --private --charset utf-8 --plugin yard-activerecord --plugin yard-activesupport-concern diff --git a/Gemfile b/Gemfile index 5a3591a4b..3d271a7f8 100644 --- a/Gemfile +++ b/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 diff --git a/Gemfile.lock b/Gemfile.lock index 549f593c8..bd228a689 100644 --- a/Gemfile.lock +++ b/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 diff --git a/docs/.gitdocs.json b/docs/.gitdocs.json index 10212c94d..1d8bda248 100644 --- a/docs/.gitdocs.json +++ b/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" } ] } diff --git a/docs/.ruby-version b/docs/.ruby-version new file mode 100644 index 000000000..097a15a2a --- /dev/null +++ b/docs/.ruby-version @@ -0,0 +1 @@ +2.6.2 diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 000000000..c022a49e0 --- /dev/null +++ b/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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..165fec684 --- /dev/null +++ b/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 diff --git a/docs/faqs.md b/docs/faqs.md index 972e5b7ac..ada80d7b2 100644 --- a/docs/faqs.md +++ b/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 diff --git a/netlify.toml b/netlify.toml index 885275197..37a2b04a5 100644 --- a/netlify.toml +++ b/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"