Merge branch '15823-dispatchcloud-api-docs'
[arvados.git] / doc / Rakefile
1 #!/usr/bin/env rake
2 # Copyright (C) The Arvados Authors. All rights reserved.
3 #
4 # SPDX-License-Identifier: CC-BY-SA-3.0
5
6 # As a convenience to the documentation writer, you can touch a file
7 # called 'no-sdk' in the 'doc' directory and it will suppress
8 # generating the documentation for the SDKs, which (the R docs
9 # especially) take a fair bit of time and slow down the edit-preview
10 # cycle.
11
12 require "rubygems"
13 require "colorize"
14
15 module Zenweb
16   class Site
17     @binary_files = %w[png jpg gif eot svg ttf woff2? ico pdf m4a t?gz xlsx]
18   end
19 end
20
21 task :generate => [ :realclean, 'sdk/python/arvados/index.html', 'sdk/R/arvados/index.html', 'sdk/java-v2/javadoc/index.html' ] do
22   vars = ['baseurl', 'arvados_cluster_uuid', 'arvados_api_host', 'arvados_workbench_host']
23   vars.each do |v|
24     if ENV[v]
25       website.config.h[v] = ENV[v]
26     end
27   end
28 end
29
30 file ["install/new_cluster_checklist_Azure.xlsx", "install/new_cluster_checklist_AWS.xlsx"] do |t|
31   cp(t, t)
32 end
33
34 file "sdk/python/arvados/index.html" do |t|
35   if ENV['NO_SDK'] || File.exists?("no-sdk")
36     next
37   end
38   `which epydoc`
39   if $? == 0
40     STDERR.puts `epydoc --html --parse-only -o sdk/python/arvados ../sdk/python/arvados/ 2>&1`
41     raise if $? != 0
42   else
43     puts "Warning: epydoc not found, Python documentation will not be generated".colorize(:light_red)
44   end
45 end
46
47 file "sdk/R/arvados/index.html" do |t|
48   if ENV['NO_SDK'] || File.exists?("no-sdk")
49     next
50   end
51   `which R`
52   if $? == 0
53     tgt = Dir.pwd
54     Dir.mkdir("sdk/R")
55     Dir.mkdir("sdk/R/arvados")
56     puts("tgt", tgt)
57     cp('css/R.css', 'sdk/R/arvados')
58     docfiles = []
59     Dir.chdir("../sdk/R/") do
60       STDERR.puts `Rscript createDoc.R README.Rmd #{tgt}/sdk/R/README.md 2>&1`
61       Dir.entries("man").each do |rd|
62         if rd[-3..-1] == ".Rd"
63           htmlfile = "#{rd[0..-4]}.html"
64           `R CMD Rdconv -t html man/#{rd} > #{tgt}/sdk/R/arvados/#{htmlfile}`
65           docfiles << htmlfile
66         end
67       end
68     end
69     raise if $? != 0
70
71     File.open("sdk/R/README.md", "r") do |rd|
72     File.open("sdk/R/index.html.md", "w") do |fn|
73       fn.write(<<-EOF
74 ---
75 layout: default
76 navsection: sdk
77 navmenu: R
78 title: "R SDK Overview"
79 ...
80
81 #{rd.read.gsub(/^```$/, "~~~").gsub(/^```(\w)$/, "~~~\\1")}
82 EOF
83               )
84       end
85     end
86
87     File.open("sdk/R/arvados/index.html.textile.liquid", "w") do |fn|
88       fn.write(<<-EOF
89 ---
90 layout: default
91 navsection: sdk
92 navmenu: R
93 title: "R Reference"
94 ...
95 {% comment %}
96 Copyright (C) The Arvados Authors. All rights reserved.
97
98 SPDX-License-Identifier: CC-BY-SA-3.0
99 {% endcomment %}
100
101 EOF
102               )
103
104       docfiles.sort.each do |d|
105         fn.write("* \"#{d[0..-6]}\":#{d}\n")
106       end
107
108     end
109   else
110     puts "Warning: R not found, R documentation will not be generated".colorize(:light_red)
111   end
112 end
113
114 file "sdk/java-v2/javadoc/index.html" do |t|
115   if ENV['NO_SDK'] || File.exists?("no-sdk")
116     next
117   end
118   `which java`
119   if $? == 0
120     `which gradle`
121     if $? != 0
122       puts "Warning: gradle not found, java sdk documentation will not be generated".colorize(:light_red)
123     else
124       tgt = Dir.pwd
125       docfiles = []
126       Dir.chdir("../sdk/java-v2") do
127         STDERR.puts `gradle javadoc 2>&1`
128         raise if $? != 0
129         puts `sed -i "s/@import.*dejavu.css.*//g" build/docs/javadoc/stylesheet.css`
130         raise if $? != 0
131       end
132       cp_r("../sdk/java-v2/build/docs/javadoc", "sdk/java-v2")
133       raise if $? != 0
134     end
135   else
136     puts "Warning: java not found, java sdk documentation will not be generated".colorize(:light_red)
137   end
138 end
139
140 task :linkchecker => [ :generate ] do
141   Dir.chdir(".site") do
142     `which linkchecker`
143     if $? == 0
144       system "linkchecker index.html --ignore-url='!file://'" or exit $?.exitstatus
145     else
146       puts "Warning: linkchecker not found, skipping run".colorize(:light_red)
147     end
148   end
149 end
150
151 task :clean do
152   rm_rf "sdk/python/arvados"
153   rm_rf "sdk/R"
154   rm_rf "sdk/java-v2/javadoc"
155 end
156
157 require "zenweb/tasks"
158 load "zenweb-textile.rb"
159 load "zenweb-liquid.rb"
160 load "zenweb-fix-body.rb"
161
162 task :extra_wirings do
163   $website.pages["sdk/python/python.html.textile.liquid"].depends_on("sdk/python/arvados/index.html")
164 end