2 # Copyright (C) The Arvados Authors. All rights reserved.
4 # SPDX-License-Identifier: CC-BY-SA-3.0
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
12 # To generate and view the documentation locally, run this command
14 # rake && sensible-browser .site/index.html
18 # baseurl=http://localhost:8000 rake && rake run
20 # and then visit http://localhost:8000 in a browser.
25 def can_run?(*command, **options)
28 :out => [File::NULL, "w"],
30 system(*command, **options)
35 can_run?("gradle", "--version")
41 can_run?("./pysdk_pdoc.py", "--version")
47 can_run?("R", "--version")
52 no_sdk_env = ENV.fetch("NO_SDK", "")
53 sdks_env = ENV.fetch("sdks", "")
54 all_sdks = Hash[[JavaSDK, PythonSDK, RSDK].map { |c| [c.name, c] }]
56 if no_sdk_env != "" and sdks_env != ""
57 fail "both NO_SDK and sdks defined in environment"
60 elsif no_sdk_env != "" or File.exist?("no-sdk")
65 all_sdks.each_pair.filter_map do |name, sdk|
69 puts "Warning: cannot build #{name.replace(/SDK$/, ' SDK')} documentation, skipping".colorize(:light_red)
74 sdks_env.split(/\s*[,\s]\s*/).each do |key|
75 key = "#{key.capitalize}SDK"
77 wanted_sdks = all_sdks.values
78 elsif key == "NoneSDK"
80 elsif sdk = all_sdks[key]
83 fail "cannot build documentation for unknown #{key}"
92 @binary_files = %w[png jpg gif eot svg ttf woff2? ico pdf m4a t?gz xlsx]
96 task :generate => [ :realclean, 'sdk/python/arvados.html', 'sdk/R/arvados/index.html', 'sdk/java-v2/javadoc/index.html' ] do
97 vars = ['baseurl', 'arvados_cluster_uuid', 'arvados_api_host', 'arvados_workbench_host']
98 if ! ENV.key?('baseurl') || ENV['baseurl'] == ""
99 if !ENV.key?('WORKSPACE') || ENV['WORKSPACE'] == ""
100 puts "The `baseurl` variable was not specified and the `WORKSPACE` environment variable is not set. Defaulting `baseurl` to file://#{pwd}/.site"
101 ENV['baseurl'] = "file://#{pwd}/.site/"
103 puts "The `baseurl` variable was not specified, defaulting to a value derived from the `WORKSPACE` environment variable"
104 ENV['baseurl'] = "file://#{ENV['WORKSPACE']}/doc/.site/"
109 website.config.h[v] = ENV[v]
114 file ["install/new_cluster_checklist_Azure.xlsx", "install/new_cluster_checklist_AWS.xlsx"] do |t|
118 file "sdk/python/arvados.html" do |t|
119 next unless $build_sdks.include?(PythonSDK)
120 raise unless system("python3", "setup.py", "build",
121 chdir: "../sdk/python", out: :err)
122 raise unless system("python3", "pysdk_pdoc.py",
126 file "sdk/R/arvados/index.html" do |t|
127 next unless $build_sdks.include?(RSDK)
130 Dir.mkdir("sdk/R/arvados")
132 cp('css/R.css', 'sdk/R/arvados')
134 Dir.chdir("../sdk/R/") do
135 Dir.entries("man").each do |rd|
136 if rd[-3..-1] == ".Rd"
137 htmlfile = "#{rd[0..-4]}.html"
138 `R CMD Rdconv -t html man/#{rd} > #{tgt}/sdk/R/arvados/#{htmlfile}`
145 File.open("../sdk/R/README.md", "r") do |rd|
146 File.open("sdk/R/index.html.md", "w") do |fn|
152 title: "R SDK Overview"
161 File.open("sdk/R/arvados/index.html.textile.liquid", "w") do |fn|
170 Copyright (C) The Arvados Authors. All rights reserved.
172 SPDX-License-Identifier: CC-BY-SA-3.0
177 docfiles.sort.each do |d|
178 fn.write("* \"#{d[0..-6]}\":#{d}\n")
183 file "sdk/java-v2/javadoc/index.html" do |t|
184 next unless $build_sdks.include?(JavaSDK)
187 Dir.chdir("../sdk/java-v2") do
188 STDERR.puts `gradle javadoc 2>&1`
190 puts `sed -i "s/@import.*dejavu.css.*//g" build/docs/javadoc/stylesheet.css`
193 cp_r("../sdk/java-v2/build/docs/javadoc", "sdk/java-v2")
197 task :linkchecker => [ :generate ] do
198 if !can_run?("linkchecker", "--version")
199 puts "Warning: linkchecker not found, skipping run".colorize(:light_red)
202 # we need --check-extern to check relative links, weird but true
204 "linkchecker", "index.html", "--check-extern", "--ignore-url=!file://",
206 ) or exit $?.exitstatus
209 task :import_vscode_training do
211 rm_rf "arvados-vscode-cwl-training"
212 `git clone https://github.com/arvados/arvados-vscode-cwl-training`
213 githash = `git --git-dir arvados-vscode-cwl-training/.git log -n1 --format=%H HEAD`
214 File.open("cwl/arvados-vscode-training.html.md.liquid", "w") do |fn|
215 File.open("arvados-vscode-cwl-training/README.md", "r") do |rd|
219 navsection: userguide
220 title: "Developing CWL Workflows with VSCode"
223 Copyright (C) The Arvados Authors. All rights reserved.
225 SPDX-License-Identifier: CC-BY-SA-3.0
227 Imported from https://github.com/arvados/arvados-vscode-cwl-training
236 rm_rf "arvados-vscode-cwl-training"
241 rm_rf "sdk/python/arvados"
242 rm_f "sdk/python/arvados.html"
243 rm_f "sdk/python/index.html"
245 rm_rf "sdk/java-v2/javadoc"
248 require "zenweb/tasks"
249 load "zenweb-textile.rb"
250 load "zenweb-liquid.rb"
251 load "zenweb-fix-body.rb"
253 task :extra_wirings do
254 $website.pages["sdk/python/python.html.textile.liquid"].depends_on("sdk/python/arvados.html")