From fcbcba66c92871fe3936e5ca605017e9c2a2eb95 Mon Sep 17 00:00:00 2001 From: Deron Eriksson Date: Thu, 2 Jul 2015 13:55:53 -0700 Subject: [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 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 = '' + + 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("", javadoc_script_elements + "") + 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 ::", 'Alpha Component'); + addBadges(":: DeveloperApi ::", 'Developer API'); + addBadges(":: Experimental ::", 'Experimental'); +}); + +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); + } + }); +} -- cgit v1.2.3