diff --git a/Rakefile b/Rakefile
index 5b859aa33c1..37eb1d9dd97 100644
--- a/Rakefile
+++ b/Rakefile
@@ -2,7 +2,7 @@ require 'html-proofer'
require 'kramdown'
require 'find'
require 'launchy'
-
+require 'colorator'
task default: %w[preview]
@@ -10,47 +10,60 @@ task test: %w[test:links:report]
### Preview
-desc "Previewing the devdocs locally"
-task preview: %w[bundle_install cleanup] do
-
- print "Generating devdocs locally ... "
- preview unless File.exists?('_config.local.yml')
+desc "Preview the devdocs locally"
+task preview: %w[install cleanup] do
- puts "enabled additional configuration parameters from _config.local.yml"
- preview_local
+ print "Generating devdocs locally ... ".magenta
+ if File.exists?('_config.local.yml')
+ print "enabled the additional configuration parameters from _config.local.yml: $ ".magenta
+ preview_local
+ else
+ print "enabled the default configuration; generating the entire devdocs $ ".magenta
+ preview
+ end
end
namespace :preview do
- task all: %w[bundle_install cleanup] do
- puts "Generating the entire devdocs locally ... "
+ task all: %w[install cleanup] do
+ puts "Generating the entire devdocs locally ... ".magenta
preview
end
end
-desc "Removing the generated content"
+desc "Remove the generated content"
task :cleanup do
- jekyll('clean')
+ print "Cleaning after the last site generation: $ ".magenta
+ jekyll 'clean'
+ puts "Clean!".green
end
-desc "Bundle install"
-task :bundle_install do
- print "Running Bundler to check if all required gems installed ... "
- system('bundle install')
- puts "Done"
+desc "Install gems listed in the Gemfile"
+task :install do
+ print "Install gems listed in the Gemfile: $ ".magenta
+ sh 'bundle install'
+ puts "Installed!".green
end
-# Build the site
-desc "build the site"
+desc "Build the entire web site"
task build: %w[cleanup] do
- puts 'Building the site with Jekyll...'
- jekyll('build')
+ print 'Building the site with Jekyll: $ '.magenta
+ jekyll 'build'
+ puts 'Built!'.green
end
-
+namespace :update do
+ desc "Update the devdocs theme"
+ task :theme do
+ print 'Updating the devdocs theme gem dependency: $ '.magenta
+ sh 'bundle update devdocs --conservative'
+ print 'Updated! Here is the Gemfile.lock diff: $ '.green
+ sh 'git diff Gemfile.lock'
+ end
+end
## Run Jekyll
def jekyll(options)
- system('bundle exec jekyll ' + options)
+ sh "bundle exec jekyll #{options}"
end
## Jekyll preview
@@ -63,6 +76,12 @@ def preview_local
preview('--config _config.yml,_config.local.yml')
end
+desc "Checkout to the master branch"
+task :to_master do
+ print 'Checking out the branch to master: $'.magenta
+ sh 'git checkout master'
+end
+
namespace :test do
################
@@ -70,129 +89,163 @@ namespace :test do
################
# Run htmlproofer to check for broken links
- desc "Validate links"
+ desc "Check for broken links"
task links: %w[build] do
-
- # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the transform task (https://stackoverflow.com/a/10048406).
- # Wrapping task in a begin-rescue block prevents rake from aborting.
- # Seems to prevent printing an error count though.
begin
-
- puts 'Checking links with htmlproofer...'
-
- # If you're running this for the first time, create the tmp/.htmlproofer directory first or the script fails.
- mkdir_p 'tmp/.htmlproofer' unless File.exists?('tmp/.htmlproofer')
-
- # Write console output (stderr only) to a file.
- # Use this if you need to also capture stdout: https://stackoverflow.com/a/2480439
- $stderr.reopen("tmp/.htmlproofer/bad-links.md", "w")
-
- # Configure htmlproofer parameters:
- options = {
- log_level: :info,
- only_4xx: true,
- # external_only: true, # Check external links only
- checks_to_ignore: ["ScriptCheck", "ImageCheck"],
- allow_hash_ref: true,
- alt_ignore: [/.*/],
- file_ignore: [/videos/, /swagger/, /guides\/m1x/, /search.html/, /404.html/, /codelinks/, /magento-third-party.html/, /magento-techbull.html/, /magento-release-notes.html/, /magento-release-information.html/, /index.html/, /template.html/, /magento-devdocs-whatsnew.html/],
- url_ignore: [/guides\/v2.0/],
- error_sort: :desc, # Sort by invalid link instead of affected file path (default). This makes it easier to see how many files the bad link affects.
- parallel: { :in_processes => 6 },
- typhoeus: { :followlocation => true, :connecttimeout => 10, :timeout => 30 },
- hydra: { :max_concurrency => 50 },
- cache: { :timeframe => '30d' }
- }
- HTMLProofer.check_directory("./_site", options).run
-
- # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the transform task (https://stackoverflow.com/a/10048406).
- # Wrapping task in a begin-rescue block prevents rake from aborting.
+ # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the convert task (https://stackoverflow.com/a/10048406).
+ # Wrapping task in a begin-rescue block prevents rake from aborting.
+ # Seems to prevent printing an error count though.
+
+ puts 'Checking links with htmlproofer...'.magenta
+
+ # If you're running this for the first time, create the tmp/.htmlproofer directory first or the script fails.
+ mkdir_p dir_name unless Dir.exists?(dir_name)
+
+ # Write console output (stderr only) to a file.
+ # Use this if you need to also capture stdout: https://stackoverflow.com/a/2480439
+ $stderr.reopen(md_report_path, "w")
+
+ # Configure htmlproofer parameters:
+ options = {
+ log_level: :info,
+ only_4xx: true,
+ # external_only: true, # Check external links only
+ checks_to_ignore: ["ScriptCheck", "ImageCheck"],
+ allow_hash_ref: true,
+ alt_ignore: [/.*/],
+ file_ignore: [/videos/, /swagger/, /guides\/m1x/, /search.html/, /404.html/, /codelinks/, /magento-third-party.html/, /magento-techbull.html/, /magento-release-notes.html/, /magento-release-information.html/, /index.html/, /template.html/, /magento-devdocs-whatsnew.html/],
+ url_ignore: [/guides\/v2.0/],
+ error_sort: :desc, # Sort by invalid link instead of affected file path (default). This makes it easier to see how many files the broken link affects.
+ parallel: { :in_processes => 3 },
+ typhoeus: { :followlocation => true, :connecttimeout => 10, :timeout => 30 },
+ hydra: { :max_concurrency => 50 },
+ cache: { :timeframe => '30d' }
+ }
+ HTMLProofer.check_directory("./_site", options).run
+
+ # We're expecting link validation errors, but unless we rescue from StandardError, rake will abort and won't run the convert task (https://stackoverflow.com/a/10048406).
+ # Wrapping task in a begin-rescue block prevent rake from aborting.
# Seems to prevent printing an error count though.
- rescue StandardError => e
- #lifeboats
+ rescue
+ size_in_lines(md_report_path)
end
end
+ # Count the number of lines in the given file
+ def size_in_lines(filepath)
+ f = File.new(filepath)
+ f.readlines[-1]
+ count = f.lineno.to_s
+
+ puts "#{count} lines in the #{File.basename(filepath)} file.".blue
+ end
+
+ # Read the current git branch
+ def current_branch
+ `git symbolic-ref --short HEAD`.strip
+ end
+
+ # Name the directory for the link checker reports
+ def dir_name
+ 'tmp/.htmlproofer/'
+ end
+
+ # Name the file for the link checker report
+ def file_name
+ "broken-links-in-#{current_branch}"
+ end
+
+ # Relative path for the link checker report
+ def file_path
+ dir_name + file_name
+ end
+
+ def md_report_path
+ file_path + '.md'
+ end
+
+ namespace :links do
+ desc "Checkout to the master branch and check the links"
+ task on_master: %w[to_master links]
+ end
+
#################
- # Transform #
+ # convert #
#################
- # Make 'tmp/.htmlproofer/bad-links.md' easier to read by transforming it to HTML and applying some CSS.
+ # Make 'tmp/.htmlproofer/broken-links-in.md' easier to read by converting it to HTML and applying some CSS.
# We created this task to help us resolve the initial set of errors on the devdocs site.
# It shouldn't be necessary after we resolve all outstanding errors because we shouldn't expect a large number of errors after initial clean up.
- desc "transform link validation error output to HTML"
- task :transform do
-
- # Define the output directory.
- SITE_PATH = './tmp/.htmlproofer'
-
- # Create the output directory if it doesn't already exist.
- Dir.mkdir( SITE_PATH ) unless File.exist?( SITE_PATH )
+ desc "Convert the link check reports to HTML"
+ task :convert do
+ puts 'Converting the link check reports to HTML...'.magenta
# Define the Kramdown method to convert markdown to HTML.
- def markdown( text )
+ def kramdown( text )
Kramdown::Document.new( text ).to_html
end
- # Locate the output directory, iterate over markdown files inside it, and convert those files to HTML.
- Find.find('./tmp/.htmlproofer') do |path|
- if File.extname(path) == '.md' # e.g. ./index.md => .md
- basename = File.basename(path, '.md') # e.g. ./index.md => index
- File.open( "#{SITE_PATH}/#{basename}.html", 'w') do |file|
- file.write markdown( File.read( path ) )
- end
- end
+ # Read content in the given path
+ def content(path)
+ File.read(path)
end
- # Automatically open the HTML report in a browser.
- uri = './tmp/.htmlproofer/bad-links.html'
- Launchy.open( uri ) do |exception|
- puts "Attempted to open #{uri} and failed because #{exception}"
+ # The CSS to append to the HTML report with broken links
+ def css
+ <<-CSS.gsub(/[[:blank:]]+/, " ")
+
+
+ CSS
end
- # Open the report and append CSS.
- # When I try prepending it using the r+ mode (https://stackoverflow.com/a/3682374), which is where CSS content should go, it trucates part of the top error.
- # This is good enough for now.
- File.open('./tmp/.htmlproofer/bad-links.html', 'a') { |file| file.write('
- ') }
+ # Automatically open the HTML report in a browser.
+ def open_in_browser(path)
+ Launchy.open( path ) do |exception|
+ puts "Attempted to open #{path} and failed because #{exception}".red
+ end
+ end
+ # Locate the output directory, iterate over markdown files inside it, and convert those files to HTML.
+ Find.find(dir_name) do |path|
+ if File.extname(path) == '.md' # e.g. ./index.md => .md
+ html_file = path.ext('html')
+ File.open( html_file , 'w') do |file|
+ file.write kramdown( content(path) )
+ file.write css
+ end
+ open_in_browser(html_file)
+ end
+ end
end
namespace :links do
- ###############
- # Report #
- ###############
-
- # Generate an HTML report of all link validation errors.
- desc "generate link validation html report"
- task report: %w[links transform] do
- puts "generating link validation HTML report..."
- end
+ desc "Report about broken links in HTML"
+ task report: %w[links convert]
end
end
\ No newline at end of file