fc78384704
I used the sbt-unidoc plugin (https://github.com/sbt/sbt-unidoc) to create a unified Scaladoc of our public packages, and generate Javadocs as well. One limitation is that I haven't found an easy way to exclude packages in the Javadoc; there is a SBT task that identifies Java sources to run javadoc on, but it's been very difficult to modify it from outside to change what is set in the unidoc package. Some SBT-savvy people should help with this. The Javadoc site also lacks package-level descriptions and things like that, so we may want to look into that. We may decide not to post these right now if it's too limited compared to the Scala one. Example of the built doc site: http://people.csail.mit.edu/matei/spark-unified-docs/ Author: Matei Zaharia <matei@databricks.com> This patch had conflicts when merged, resolved by Committer: Patrick Wendell <pwendell@gmail.com> Closes #457 from mateiz/better-docs and squashes the following commits: a63d4a3 [Matei Zaharia] Skip Java/Scala API docs for Python package 5ea1f43 [Matei Zaharia] Fix links to Java classes in Java guide, fix some JS for scrolling to anchors on page load f05abc0 [Matei Zaharia] Don't include java.lang package names 995e992 [Matei Zaharia] Skip internal packages and class names with $ in JavaDoc a14a93c [Matei Zaharia] typo 76ce64d [Matei Zaharia] Add groups to Javadoc index page, and a first package-info.java ed6f994 [Matei Zaharia] Generate JavaDoc as well, add titles, update doc site to use unified docs acb993d [Matei Zaharia] Add Unidoc plugin for the projects we want Unidoced
82 lines
2.5 KiB
Ruby
82 lines
2.5 KiB
Ruby
#
|
|
# 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.
|
|
#
|
|
|
|
require 'fileutils'
|
|
include FileUtils
|
|
|
|
if not (ENV['SKIP_API'] == '1' or ENV['SKIP_SCALADOC'] == '1')
|
|
# Build Scaladoc for Java/Scala
|
|
|
|
puts "Moving to project root and building API docs."
|
|
curr_dir = pwd
|
|
cd("..")
|
|
|
|
puts "Running 'sbt/sbt compile unidoc' from " + pwd + "; this may take a few minutes..."
|
|
puts `sbt/sbt compile unidoc`
|
|
|
|
puts "Moving back into docs dir."
|
|
cd("docs")
|
|
|
|
# Copy over the unified ScalaDoc for all projects to api/scala.
|
|
# This directory will be copied over to _site when `jekyll` command is run.
|
|
source = "../target/scala-2.10/unidoc"
|
|
dest = "api/scala"
|
|
|
|
puts "Making directory " + dest
|
|
mkdir_p dest
|
|
|
|
# From the rubydoc: cp_r('src', 'dest') makes src/dest, but this doesn't.
|
|
puts "cp -r " + source + "/. " + dest
|
|
cp_r(source + "/.", dest)
|
|
|
|
# Append custom JavaScript
|
|
js = File.readlines("./js/api-docs.js")
|
|
js_file = dest + "/lib/template.js"
|
|
File.open(js_file, 'a') { |f| f.write("\n" + js.join()) }
|
|
|
|
# Append custom CSS
|
|
css = File.readlines("./css/api-docs.css")
|
|
css_file = dest + "/lib/template.css"
|
|
File.open(css_file, 'a') { |f| f.write("\n" + css.join()) }
|
|
|
|
# Copy over the unified JavaDoc for all projects to api/java.
|
|
source = "../target/javaunidoc"
|
|
dest = "api/java"
|
|
|
|
puts "Making directory " + dest
|
|
mkdir_p dest
|
|
|
|
puts "cp -r " + source + "/. " + dest
|
|
cp_r(source + "/.", dest)
|
|
|
|
# Build Epydoc for Python
|
|
puts "Moving to python directory and building epydoc."
|
|
cd("../python")
|
|
puts `epydoc --config epydoc.conf`
|
|
|
|
puts "Moving back into docs dir."
|
|
cd("../docs")
|
|
|
|
puts "Making directory api/python"
|
|
mkdir_p "api/python"
|
|
|
|
puts "cp -r ../python/docs/. api/python"
|
|
cp_r("../python/docs/.", "api/python")
|
|
|
|
cd("..")
|
|
end
|