Skip to content

Commit d850686

Browse files
zzakzzak
committed
Add preview_docs rake task for generating API and Guides static site
1 parent 0f9aaa5 commit d850686

File tree

4 files changed

+217
-0
lines changed

4 files changed

+217
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
/dist/
1010
/doc/
1111
/guides/output/
12+
/preview/
1213
Brewfile.lock.json
1314
debug.log*
1415
node_modules/

‎Rakefile

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ require "net/http"
55
$:.unshift __dir__
66
require "tasks/release"
77
require "railties/lib/rails/api/task"
8+
require "tools/preview_docs"
89

910
desc "Build gem files for all projects"
1011
task build: "all:build"
@@ -50,6 +51,20 @@ else
5051
Rails::API::StableTask.new("rdoc")
5152
end
5253

54+
desc "Generate documentation for previewing"
55+
task :preview_docs do
56+
FileUtils.mkdir_p("preview")
57+
PreviewDocs.new.render("preview")
58+
59+
require "guides/rails_guides"
60+
Rake::Task[:rdoc].invoke
61+
62+
FileUtils.cp_r("doc/rdoc", "preview/api")
63+
FileUtils.cp_r("guides/output", "preview/guides")
64+
65+
system("tar -czf preview.tar.gz preview")
66+
end
67+
5368
desc "Bump all versions to match RAILS_VERSION"
5469
task update_versions: "all:update_versions"
5570

‎tools/preview_docs.rb

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# frozen_string_literal: true
2+
3+
require "erb"
4+
require "cgi"
5+
6+
puts "required tools/preview_docs"
7+
8+
# How to test:
9+
#
10+
# export BUILDKITE_COMMIT="c8b601a225"
11+
# export BUILDKITE_BUILD_CREATOR="zzak"
12+
# export BUILDKITE_REPO="https://github.com/rails/rails.git"
13+
# export BUILDKITE_BUILD_NUMBER="60"
14+
# export BUILDKITE_BUILD_URL="https://buildkite.com/rails/docs-preview/builds/60"
15+
# export BUILDKITE_BRANCH="preview_docs"
16+
# export BUILDKITE_MESSAGE="commit message"
17+
# export BUILDKITE_PULL_REQUEST="42"
18+
# bundle exec rake preview_docs
19+
# open preview/index.html
20+
class PreviewDocs
21+
attr_reader :commit, :author, :build, :repo, :branch
22+
23+
def initialize
24+
@commit = link_to(EnvVars.sha[0, 7], "#{EnvVars.repo}/commit/#{EnvVars.sha}")
25+
@author = EnvVars.actor
26+
@build = link_to(EnvVars.build_number, EnvVars.build_url)
27+
@repo = link_to(EnvVars.repo_slug, "#{EnvVars.repo}")
28+
@branch = link_to(EnvVars.branch, "#{EnvVars.repo}/tree/#{EnvVars.branch}")
29+
@message = EnvVars.message || "n/a"
30+
@pull_request = EnvVars.pull_request ? link_to("##{EnvVars.pull_request}", "#{EnvVars.repo}/pull/#{EnvVars.pull_request}") : "n/a"
31+
end
32+
33+
def render(outdir)
34+
template = File.open("tools/preview_docs/index.html.erb").read
35+
result = ERB.new(template).result(binding)
36+
File.open("#{outdir}/index.html", "w") do |f|
37+
f.write result
38+
end
39+
end
40+
41+
def link_to(name, url)
42+
"<a href=\"#{escape(url)}\">#{escape(name)}</a>"
43+
end
44+
45+
def escape(str)
46+
CGI.escapeHTML(str)
47+
end
48+
end
49+
50+
module EnvVars
51+
def self.sha
52+
fetch "BUILDKITE_COMMIT"
53+
end
54+
55+
def self.actor
56+
fetch "BUILDKITE_BUILD_CREATOR"
57+
end
58+
59+
def self.repo
60+
fetch("BUILDKITE_REPO").gsub(".git", "")
61+
end
62+
63+
def self.repo_slug
64+
repo.slice(/\w+\/\w+\Z/)
65+
end
66+
67+
def self.build_number
68+
fetch "BUILDKITE_BUILD_NUMBER"
69+
end
70+
71+
def self.build_url
72+
fetch "BUILDKITE_BUILD_URL"
73+
end
74+
75+
def self.branch
76+
fetch "BUILDKITE_BRANCH"
77+
end
78+
79+
def self.message
80+
ENV.fetch "BUILDKITE_MESSAGE"
81+
end
82+
83+
def self.pull_request
84+
pr = ENV.fetch("BUILDKITE_PULL_REQUEST")
85+
pr == "false" ? false : pr
86+
end
87+
88+
private
89+
def self.fetch(env)
90+
ENV.fetch(env) { raise "#{env} env var undefined!" }
91+
end
92+
end

‎tools/preview_docs/index.html.erb

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
<!doctype html>
2+
<html lang="en">
3+
4+
<head>
5+
<title></title>
6+
<meta charset="utf-8" />
7+
8+
<style>
9+
body {
10+
font-family: monospace;
11+
12+
& a {
13+
color: #D30001;
14+
}
15+
}
16+
17+
.layout {
18+
width: 500px;
19+
margin: 0 auto;
20+
}
21+
22+
.metadata table {
23+
width: 500px;
24+
border-bottom: 1px dotted #000;
25+
padding-bottom: 15px;
26+
margin-bottom: 15px;
27+
28+
& th {
29+
text-align: left;
30+
}
31+
}
32+
33+
.links {
34+
& .left {
35+
float: left;
36+
width: 40%;
37+
margin: 2px 3%;
38+
}
39+
40+
& .card {
41+
padding: 0px 5px;
42+
border-left: 3px solid #cbcb;
43+
}
44+
45+
& h1, h2 {
46+
margin: 5px;
47+
}
48+
}
49+
</style>
50+
</head>
51+
52+
<body>
53+
54+
<div class="layout">
55+
56+
<div class="container">
57+
<div class="metadata">
58+
<table>
59+
<tr>
60+
<th>Author</th>
61+
<th>Build</th>
62+
<th>Commit</th>
63+
<th>PR</th>
64+
</tr>
65+
<tr>
66+
<td><%= @author %></td>
67+
<td><%= @build %></td>
68+
<td><%= @commit %></td>
69+
<td><%= @pull_request %></td>
70+
<tr>
71+
<th>Repo</th>
72+
<th colspan=2>Branch</th>
73+
</tr>
74+
<tr>
75+
<td><%= @repo %></td>
76+
<td colspan=2><%= @branch %></td>
77+
</tr>
78+
<tr>
79+
<th colspan=3>Message</th>
80+
</tr>
81+
<tr>
82+
<td colspan=3><%= @message %></td>
83+
</tr>
84+
</table>
85+
</div>
86+
</div>
87+
88+
<div class="container">
89+
<div class="links">
90+
<div class="left">
91+
<div class="card">
92+
<h1><a href="api">/api</a></h1>
93+
<h2>Reference documentation</h2>
94+
</div>
95+
</div>
96+
97+
<div class="left">
98+
<div class="card">
99+
<h1><a href="guides">/guides</a></h1>
100+
<h2>In-depth tutorials</h2>
101+
</div>
102+
</div>
103+
</div>
104+
</div>
105+
106+
</div>
107+
108+
</body>
109+
</html>

0 commit comments

Comments
 (0)