Skip to content
This repository has been archived by the owner on Nov 19, 2024. It is now read-only.

Commit

Permalink
Extended and refactored
Browse files Browse the repository at this point in the history
  • Loading branch information
@dshevtsov
dshevtsov committed Aug 23, 2018
1 parent 596eef3 commit 1b8cf1c
Showing 1 changed file with 175 additions and 122 deletions.
297 changes: 175 additions & 122 deletions Rakefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,55 +2,68 @@ require 'html-proofer'
require 'kramdown'
require 'find'
require 'launchy'

require 'colorator'

task default: %w[preview]

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
Expand All @@ -63,136 +76,176 @@ 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

################
# Validate #
################

# 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:]]+/, " ")
<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<style>
/* Lists
–––––––––––––––––––––––––––––––––––––––––––––––––– */
ul {
list-style: disc;
font-family: \'Roboto\', sans-serif;
color: red; }
ol {
list-style: decimal inside; }css
ol, ul {
padding-left: 0;
margin-top: 0; }
ul ul,
ul ol,
ol ol,
ol ul {
margin: 1.5rem 0 1.5rem 3rem;
font-size: 90%;
color: black;}
li {
margin-bottom: 1rem;
font-weight: bold;}
</style>
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('<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<style>
/* Lists
–––––––––––––––––––––––––––––––––––––––––––––––––– */
ul {
list-style: disc;
font-family: \'Roboto\', sans-serif;
color: red; }
ol {
list-style: decimal inside; }
ol, ul {
padding-left: 0;
margin-top: 0; }
ul ul,
ul ol,
ol ol,
ol ul {
margin: 1.5rem 0 1.5rem 3rem;
font-size: 90%;
color: black;}
li {
margin-bottom: 1rem;
font-weight: bold;}
</style>') }
# 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

0 comments on commit 1b8cf1c

Please sign in to comment.