From fcbcba66c92871fe3936e5ca605017e9c2a2eb95 Mon Sep 17 00:00:00 2001
From: Deron Eriksson <deron@us.ibm.com>
Date: Thu, 2 Jul 2015 13:55:53 -0700
Subject: [PATCH] [SPARK-1564] [DOCS] Added Javascript to Javadocs to create
badges for tags like :: Experimental ::
Modified copy_api_dirs.rb and created api-javadocs.js and api-javadocs.css files in order to add badges to javadoc files for :: Experimental ::, :: DeveloperApi ::, and :: AlphaComponent :: tags
Author: Deron Eriksson <deron@us.ibm.com>
Closes #7169 from deroneriksson/SPARK-1564_JavaDocs_badges and squashes the following commits:
a8353db [Deron Eriksson] added license headers to api-docs.css and api-javadocs.css
07feb07 [Deron Eriksson] added linebreaks to make jquery more readable when adding html badge tags
65b4930 [Deron Eriksson] Modified copy_api_dirs.rb and created api-javadocs.js and api-javadocs.css files in order to add badges to javadoc files for :: Experimental ::, :: DeveloperApi ::, and :: AlphaComponent :: tags
---
docs/_plugins/copy_api_dirs.rb | 45 +++++++++++++++++++++++++
docs/css/api-docs.css | 17 ++++++++++
docs/css/api-javadocs.css | 52 +++++++++++++++++++++++++++++
docs/js/api-javadocs.js | 60 ++++++++++++++++++++++++++++++++++
4 files changed, 174 insertions(+)
create mode 100644 docs/css/api-javadocs.css
create mode 100644 docs/js/api-javadocs.js
diff --git a/docs/_plugins/copy_api_dirs.rb b/docs/_plugins/copy_api_dirs.rb
index 6073b3626c..15ceda11a8 100644
--- a/docs/_plugins/copy_api_dirs.rb
+++ b/docs/_plugins/copy_api_dirs.rb
@@ -63,6 +63,51 @@ if not (ENV['SKIP_API'] == '1')
puts "cp -r " + source + "/. " + dest
cp_r(source + "/.", dest)
+
+ # Begin updating JavaDoc files for badge post-processing
+ puts "Updating JavaDoc files for badge post-processing"
+ js_script_start = '<script defer="defer" type="text/javascript" src="'
+ js_script_end = '.js"></script>'
+
+ javadoc_files = Dir["./" + dest + "/**/*.html"]
+ javadoc_files.each do |javadoc_file|
+ # Determine file depths to reference js files
+ slash_count = javadoc_file.count "/"
+ i = 3
+ path_to_js_file = ""
+ while (i < slash_count) do
+ path_to_js_file = path_to_js_file + "../"
+ i += 1
+ end
+
+ # Create script elements to reference js files
+ javadoc_jquery_script = js_script_start + path_to_js_file + "lib/jquery" + js_script_end;
+ javadoc_api_docs_script = js_script_start + path_to_js_file + "lib/api-javadocs" + js_script_end;
+ javadoc_script_elements = javadoc_jquery_script + javadoc_api_docs_script
+
+ # Add script elements to JavaDoc files
+ javadoc_file_content = File.open(javadoc_file, "r") { |f| f.read }
+ javadoc_file_content = javadoc_file_content.sub("</body>", javadoc_script_elements + "</body>")
+ File.open(javadoc_file, "w") { |f| f.puts(javadoc_file_content) }
+
+ end
+ # End updating JavaDoc files for badge post-processing
+
+ puts "Copying jquery.js from Scala API to Java API for page post-processing of badges"
+ jquery_src_file = "./api/scala/lib/jquery.js"
+ jquery_dest_file = "./api/java/lib/jquery.js"
+ mkdir_p("./api/java/lib")
+ cp(jquery_src_file, jquery_dest_file)
+
+ puts "Copying api_javadocs.js to Java API for page post-processing of badges"
+ api_javadocs_src_file = "./js/api-javadocs.js"
+ api_javadocs_dest_file = "./api/java/lib/api-javadocs.js"
+ cp(api_javadocs_src_file, api_javadocs_dest_file)
+
+ puts "Appending content of api-javadocs.css to JavaDoc stylesheet.css for badge styles"
+ css = File.readlines("./css/api-javadocs.css")
+ css_file = dest + "/stylesheet.css"
+ File.open(css_file, 'a') { |f| f.write("\n" + css.join()) }
end
# Build Sphinx docs for Python
diff --git a/docs/css/api-docs.css b/docs/css/api-docs.css
index b2d1d7f869..7cf222aad2 100644
--- a/docs/css/api-docs.css
+++ b/docs/css/api-docs.css
@@ -1,3 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
/* Dynamically injected style for the API docs */
.developer {
diff --git a/docs/css/api-javadocs.css b/docs/css/api-javadocs.css
new file mode 100644
index 0000000000..832e92609e
--- /dev/null
+++ b/docs/css/api-javadocs.css
@@ -0,0 +1,52 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* Dynamically injected style for the API docs */
+
+.badge {
+ font-family: Arial, san-serif;
+ float: right;
+ margin: 4px;
+ /* The following declarations are taken from the ScalaDoc template.css */
+ display: inline-block;
+ padding: 2px 4px;
+ font-size: 11.844px;
+ font-weight: bold;
+ line-height: 14px;
+ color: #ffffff;
+ text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);
+ white-space: nowrap;
+ vertical-align: baseline;
+ background-color: #999999;
+ padding-right: 9px;
+ padding-left: 9px;
+ -webkit-border-radius: 9px;
+ -moz-border-radius: 9px;
+ border-radius: 9px;
+}
+
+.developer {
+ background-color: #44751E;
+}
+
+.experimental {
+ background-color: #257080;
+}
+
+.alphaComponent {
+ background-color: #bb0000;
+}
diff --git a/docs/js/api-javadocs.js b/docs/js/api-javadocs.js
new file mode 100644
index 0000000000..ead13d6e5f
--- /dev/null
+++ b/docs/js/api-javadocs.js
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* Dynamically injected post-processing code for the API docs */
+
+$(document).ready(function() {
+ addBadges(":: AlphaComponent ::", '<span class="alphaComponent badge">Alpha Component</span>');
+ addBadges(":: DeveloperApi ::", '<span class="developer badge">Developer API</span>');
+ addBadges(":: Experimental ::", '<span class="experimental badge">Experimental</span>');
+});
+
+function addBadges(tag, html) {
+ var tags = $(".block:contains(" + tag + ")")
+
+ // Remove identifier tags
+ tags.each(function(index) {
+ var oldHTML = $(this).html();
+ var newHTML = oldHTML.replace(tag, "");
+ $(this).html(newHTML);
+ });
+
+ // Add html badge tags
+ tags.each(function(index) {
+ if ($(this).parent().is('td.colLast')) {
+ $(this).parent().prepend(html);
+ } else if ($(this).parent('li.blockList')
+ .parent('ul.blockList')
+ .parent('div.description')
+ .parent().is('div.contentContainer')) {
+ var contentContainer = $(this).parent('li.blockList')
+ .parent('ul.blockList')
+ .parent('div.description')
+ .parent('div.contentContainer')
+ var header = contentContainer.prev('div.header');
+ if (header.length > 0) {
+ header.prepend(html);
+ } else {
+ contentContainer.prepend(html);
+ }
+ } else if ($(this).parent().is('li.blockList')) {
+ $(this).parent().prepend(html);
+ } else {
+ $(this).prepend(html);
+ }
+ });
+}
--
GitLab