You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@daffodil.apache.org by sl...@apache.org on 2020/07/15 19:39:18 UTC
[incubator-daffodil] branch master updated: Use sbt-unidoc plugin
for generating public API documentation
This is an automated email from the ASF dual-hosted git repository.
slawrence pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-daffodil.git
The following commit(s) were added to refs/heads/master by this push:
new c7d08c2 Use sbt-unidoc plugin for generating public API documentation
c7d08c2 is described below
commit c7d08c2de7d72aaef18097a2ad87b6eca1c609c1
Author: Steve Lawrence <sl...@apache.org>
AuthorDate: Tue Jul 14 10:25:49 2020 -0400
Use sbt-unidoc plugin for generating public API documentation
Rather than running Javadoc/Scaladoc commands separately to build our
public API documentation, we can now just run "sbt unidoc". That
generates both Java and Scala documentation in the root target
directory, including docs combined from the japi, sapi, and udf
subprojects. This also allows for easily adding new public API
documentation for other features, such as planned DSOM walker, by just
creating a new subproject and adding it to the unidocProjectFilter sbt
setting.
DAFFODIL-2368
---
.github/workflows/main.yml | 2 +-
build.sbt | 23 +++++++++++++++++-
.../release-candidate/daffodil-release-candidate | 7 +++---
daffodil-japi/build.sbt | 27 +++++-----------------
daffodil-sapi/build.sbt | 21 -----------------
daffodil-sapi/root-doc.txt | 7 +++---
project/plugins.sbt | 2 ++
7 files changed, 37 insertions(+), 52 deletions(-)
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 0648f69..ce75e07 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -64,7 +64,7 @@ jobs:
shell: bash
- name: Build Documentation
- run: $SBTNOCOV daffodil-japi/genjavadoc:doc daffodil-sapi/doc
+ run: $SBTNOCOV unidoc
shell: bash
- name: Package Zip & Tar
diff --git a/build.sbt b/build.sbt
index d41a95f..12090db 100644
--- a/build.sbt
+++ b/build.sbt
@@ -20,8 +20,9 @@ lazy val genProps = taskKey[Seq[File]]("Generate properties scala source")
lazy val genSchemas = taskKey[Seq[File]]("Generated DFDL schemas")
lazy val daffodil = Project("daffodil", file(".")).configs(IntegrationTest)
+ .enablePlugins(JavaUnidocPlugin, ScalaUnidocPlugin)
.aggregate(macroLib, propgen, lib, io, runtime1, runtime1Unparser, core, japi, sapi, tdmlLib, tdmlProc, cli, udf, test, testIBM1, tutorials, testStdLayout)
- .settings(commonSettings, nopublish, ratSettings)
+ .settings(commonSettings, nopublish, ratSettings, unidocSettings)
lazy val macroLib = Project("daffodil-macro-lib", file("daffodil-macro-lib")).configs(IntegrationTest)
.settings(commonSettings, nopublish)
@@ -241,6 +242,26 @@ lazy val ratSettings = Seq(
ratExcludes := Rat.excludes
)
+lazy val unidocSettings = Seq(
+ unidocProjectFilter in (ScalaUnidoc, unidoc) := inProjects(sapi, udf),
+ scalacOptions in (ScalaUnidoc, unidoc) := Seq(
+ "-doc-title", "Apache Daffodil (incubating) " + version.value + " Scala API",
+ "-doc-root-content", (baseDirectory in sapi).value + "/root-doc.txt"
+ ),
+
+ unidocProjectFilter in (JavaUnidoc, unidoc) := inProjects(japi, udf),
+ javacOptions in (JavaUnidoc, unidoc) := Seq(
+ "-windowtitle", "Apache Daffodil (incubating) " + version.value + " Java API",
+ "-doctitle", "<h1>Apache Daffodil (incubating) " + version.value + " Java API</h1>",
+ "-notimestamp"
+ ),
+ unidocAllSources in (JavaUnidoc, unidoc) := (unidocAllSources in (JavaUnidoc, unidoc)).value.map { sources =>
+ sources.filterNot { source =>
+ source.toString.contains("$") || source.toString.contains("packageprivate")
+ }
+ },
+)
+
//
// To create a set of eclipse projects (one for each subproject of daffodil), you
diff --git a/containers/release-candidate/daffodil-release-candidate b/containers/release-candidate/daffodil-release-candidate
index fc312a7..8ab7409 100755
--- a/containers/release-candidate/daffodil-release-candidate
+++ b/containers/release-candidate/daffodil-release-candidate
@@ -168,8 +168,7 @@ sbt \
"daffodil-cli/windows:packageBin" \
"daffodil-cli/universal:packageBin" \
"daffodil-cli/universal:packageZipTarball" \
- "daffodil-japi/genjavadoc:doc" \
- "daffodil-sapi/doc" \
+ "unidoc" \
echo "Removing old release candidates..."
find $DAFFODIL_DIST_DIR -maxdepth 1 -name $VERSION-\* -exec svn delete --force {} \;
@@ -202,8 +201,8 @@ done
echo "Installing Site Docs..."
rm -rf $DAFFODIL_DOCS_DIR
mkdir -p $DAFFODIL_DOCS_DIR/{javadoc,scaladoc}/
-cp -R daffodil-japi/target/scala-2.12/genjavadoc-api/* $DAFFODIL_DOCS_DIR/javadoc/
-cp -R daffodil-sapi/target/scala-2.12/api/* $DAFFODIL_DOCS_DIR/scaladoc/
+cp -R target/javaunidoc/* $DAFFODIL_DOCS_DIR/javadoc/
+cp -R target/scala-2.12/unidoc/* $DAFFODIL_DOCS_DIR/scaladoc/
echo "Installing Site Tutorials..."
rm -rf $DAFFODIL_TUTORIALS_DIR
diff --git a/daffodil-japi/build.sbt b/daffodil-japi/build.sbt
index 14d02d9..9aa5c7d 100644
--- a/daffodil-japi/build.sbt
+++ b/daffodil-japi/build.sbt
@@ -15,26 +15,11 @@
* limitations under the License.
*/
-addCompilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.16" cross CrossVersion.full)
+enablePlugins(GenJavadocPlugin)
+enablePlugins(PublishJavadocPlugin)
+unidocGenjavadocVersion := "0.16"
-lazy val JavaDoc = config("genjavadoc") extend Compile
-
-configs(JavaDoc)
-
-inConfig(JavaDoc)(Defaults.configSettings)
-
-scalacOptions += "-P:genjavadoc:out=" + target.value + "/java"
-
-packageDoc in Compile := (packageDoc in JavaDoc).value
-
-sources in JavaDoc :=
- (target.value / "java" ** "*.java").get.filterNot(f => f.toString.contains("$") || f.toString.contains("packageprivate")) ++
- (sources in Compile).value.filter(_.getName.endsWith(".java"))
-
-javacOptions in JavaDoc := Seq(
- "-windowtitle", "Apache Daffodil (incubating) " + version.value + " Java API",
- "-doctitle", "<h1>Apache Daffodil (incubating) " + version.value + " Java API</h1>"
-)
-
-artifactName in packageDoc in JavaDoc := ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar")
+sources in Genjavadoc := (sources in Genjavadoc).value.filterNot { source =>
+ source.toString.contains("$") || source.toString.contains("packageprivate")
+}
diff --git a/daffodil-sapi/build.sbt b/daffodil-sapi/build.sbt
deleted file mode 100644
index 48347bf..0000000
--- a/daffodil-sapi/build.sbt
+++ /dev/null
@@ -1,21 +0,0 @@
-/*
- * 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.
- */
-
-scalacOptions in (Compile, doc) := Seq(
- "-doc-title", "Apache Daffodil (incubating) " + version.value + " Scala API",
- "-doc-root-content", baseDirectory.value + "/root-doc.txt"
-)
diff --git a/daffodil-sapi/root-doc.txt b/daffodil-sapi/root-doc.txt
index 70d9fc2..3bc21ba 100644
--- a/daffodil-sapi/root-doc.txt
+++ b/daffodil-sapi/root-doc.txt
@@ -1,9 +1,8 @@
-== Apache Daffodil (incubating) Scala API ==
+This is the documentation for the Apache Daffodil (incubating) Scala API.
-=== Packages ===
+=== Package structure ===
[[org.apache.daffodil.sapi]] - Provides the classes necessary to compile DFDL schemas, parse and unparse files using the compiled objects, and retrieve results and parsing diagnostics
-[[org.apache.daffodil.sapi.logger]] - Provides the classes necessary to receive logging messages from Daffodil.
+[[org.apache.daffodil.udf]] - Provides the classes necessary to create User Defined Functions to extend the DFDL expression language
-[[org.apache.daffodil.sapi.debugger]] - Provides the classes necessary to perform parse tracing or create a custom debugger
diff --git a/project/plugins.sbt b/project/plugins.sbt
index 3423950..35a50b1 100644
--- a/project/plugins.sbt
+++ b/project/plugins.sbt
@@ -21,6 +21,8 @@ addSbtPlugin("org.musigma" % "sbt-rat" % "0.6.0")
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.6.1")
+addSbtPlugin("com.eed3si9n" % "sbt-unidoc" % "0.4.3")
+
// Both sbt and the sbt-native-pacakger plugin have transitive dependencies to
// different versions of plexus-utils and guava, but with different major
// version numbers. SBT interprets this major version number difference as