You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2018/02/15 15:03:16 UTC

[trafficserver] branch master updated: Doc: Add java/plantuml dependency to building the documentation.

This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new e459667  Doc: Add java/plantuml dependency to building the documentation.
e459667 is described below

commit e459667aad1756bad55db88235e8aa6dd229da61
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Tue Feb 13 15:05:49 2018 -0600

    Doc: Add java/plantuml dependency to building the documentation.
---
 configure.ac                             | 15 +++++++-
 doc/.gitignore                           |  3 ++
 doc/Makefile.am                          |  2 ++
 doc/checkvers.py                         |  8 +++++
 doc/conf.py                              |  4 +++
 doc/ext/local-config.py.in               | 18 ++++++++++
 doc/plantuml_fetch.sh                    | 60 ++++++++++++++++++++++++++++++++
 doc/sbuild                               | 13 ++++++-
 doc/uml/{Makefile => Makefile.am}        | 32 +++++++++++++----
 doc/uml/images/.gitignore                |  5 ---
 doc/uml/images/l4-basic-sequence.svg     | 30 ----------------
 doc/uml/images/l4-example-cdn-layout.svg | 27 --------------
 doc/uml/images/l4-sni-routing-seq.svg    | 34 ------------------
 13 files changed, 146 insertions(+), 105 deletions(-)

diff --git a/configure.ac b/configure.ac
index 1a68f69..5da6e0c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -285,10 +285,21 @@ AM_CONDITIONAL([BUILD_TESTS], [test 0 -ne $has_tests])
 # Build documentation?
 #
 
+# Java needed only for documentation building, but making it conditional
+# makes the diagnostic output ugly and hard to follow.
+AC_ARG_VAR(JAVA, [path to java executor])
+AC_CHECK_PROG(JAVA, java, java)
 AC_MSG_CHECKING([whether to build documentation])
 AC_ARG_ENABLE([docs],
   [AS_HELP_STRING([--enable-docs],[enable documentation building])],
-  [],
+  [
+    enable_doc_build=yes
+    AS_IF([test -z "$JAVA"],
+      [
+        enable_doc_build=no
+	AC_ERROR([Doc building disabled, java required but not found])
+      ])
+  ],
   [enable_doc_build=no]
 )
 AC_MSG_RESULT([$enable_doc_build])
@@ -2010,6 +2021,8 @@ AC_CONFIG_FILES([
   cmd/traffic_via/Makefile
   cmd/traffic_wccp/Makefile
   doc/Makefile
+  doc/ext/local-config.py
+  doc/uml/Makefile
   example/Makefile
   iocore/Makefile
   iocore/aio/Makefile
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..518a1af
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,3 @@
+uml/images
+ext/local-config.py
+ext/plantuml*
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7ccf838..59d3b5b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -29,6 +29,7 @@ $(man1_MANS) $(man3_MANS) $(man5_MANS) $(man8_MANS): man
 # to "make install". If we leave it to "make install" time, then the man pages are likely
 # to me generated as root.
 if BUILD_DOCS
+SUBDIRS = uml
 all-am: $(man1_MANS) $(man3_MANS) $(man5_MANS) $(man8_MANS)
 endif
 
@@ -60,6 +61,7 @@ I18NSPHINXOPTS  = $(SPHINXOPTS)
 # The PAPER setting variables requires recursive make variable expansion, which automake
 # detects as non-portable. We bounce this through a shell script and do the expansion there.
 SBUILD = PAPEROPT_a4="$(PAPEROPT_a4)" PAPEROPT_letter="$(PAPEROPT_letter)" PAPER="$(PAPER)" \
+         PLANTUML_JAR="$(shell ./plantuml_fetch.sh | tail -1)" \
 	 $(srcdir)/sbuild $(SPHINXBUILD) \
 	 -c $(srcdir) \
 	 $(ALLSPHINXOPTS)
diff --git a/doc/checkvers.py b/doc/checkvers.py
index fbb5c1e..68fb390 100644
--- a/doc/checkvers.py
+++ b/doc/checkvers.py
@@ -57,3 +57,11 @@ if __name__ == '__main__':
         except Exception as e:
             print e
             sys.exit(1)
+
+        print 'checking for sphinxcontrib.plantuml...',
+        try:
+            import sphinxcontrib.plantuml
+            print 'yes'
+        except Exception as e:
+            print e;
+            sys.exit(1)
diff --git a/doc/conf.py b/doc/conf.py
index c4ad9a9..55e5f5c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -55,9 +55,13 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.plantuml',
     'traffic-server',
 ]
 
+# Contains values that are dependent on configure.ac.
+execfile('ext/local-config.py')
+
 if version_info >= (1, 4):
     extensions.append('sphinx.ext.imgmath')
 else:
diff --git a/doc/ext/local-config.py.in b/doc/ext/local-config.py.in
new file mode 100644
index 0000000..5851686
--- /dev/null
+++ b/doc/ext/local-config.py.in
@@ -0,0 +1,18 @@
+# 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.
+
+plantuml='@JAVA@ -jar ${PLANTUML_JAR}'
+plantuml_output_format='svg'
diff --git a/doc/plantuml_fetch.sh b/doc/plantuml_fetch.sh
new file mode 100755
index 0000000..0990f2a
--- /dev/null
+++ b/doc/plantuml_fetch.sh
@@ -0,0 +1,60 @@
+#! /usr/bin/env bash
+#
+#  Fetch the plantuml JAR file from bintray.
+#
+#  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.
+
+# Version tag.
+PKGDATE="1.2018.1"
+PKG_EXT="tar.bz2"
+TMPDIR=${TMPDIR:-/tmp}
+
+function main() {
+  set -e # exit on error
+  PACKAGE="plantuml-${PKGDATE}"
+  JAR="plantuml.jar"
+  ROOT=${ROOT:-$(cd $(dirname $0) && git rev-parse --show-toplevel)/.git/doc-tools}
+
+  URL=${URL:-https://ci.trafficserver.apache.org/bintray/${PACKAGE}.${PKG_EXT}}
+  TAR=${TAR:-tar}
+  CURL=${CURL:-curl}
+
+  mkdir -p ${ROOT}
+  cd ${ROOT}
+
+  if [ ! -e ${PACKAGE} ] ; then
+    # default to using native sha1sum command when available
+    if [ $(which sha1sum) ] ; then
+      SHASUM=${SHASUM:-sha1sum}
+    else
+      SHASUM=${SHASUM:-shasum}
+    fi
+
+    DL="${TMPDIR}/${PACKAGE}.${PKG_EXT}"
+    rm -rf ${DL}
+    ${CURL} -L --progress-bar -o ${DL} ${URL}
+    cat > ${TMPDIR}/plantuml-sha-checksum << EOF
+4dbf218641a777007f9bc72ca8017a41a23e1081  ${DL}
+EOF
+    ${SHASUM} -c ${TMPDIR}/plantuml-sha-checksum
+    ${TAR} xf ${DL}
+    cd ${PACKAGE}
+  fi
+  echo ${ROOT}/${PACKAGE}/${JAR}
+}
+
+main "$@"
diff --git a/doc/sbuild b/doc/sbuild
index ee1a62c..e8535b6 100755
--- a/doc/sbuild
+++ b/doc/sbuild
@@ -21,7 +21,18 @@
 SPHINXBUILD="$1"
 shift
 
+if [ -z "${PLANTUML_JAR}" ] ; then
+  echo 'PLANTUML_JAR' not set.
+  exit 1;
+elif [ ! -r "${PLANTUML_JAR}" ] ; then
+  echo plantuml jar \'${PLANTUML_JAR}\' not readable.
+  exit 1;
+elif [ ! -f "${PLANTUML_JAR}" ] ; then
+  echo plantuml jar \'${PLANTUML_JAR}\' is not actually a jar.
+  exit 1;
+fi
+
+
 exec $SPHINXBUILD \
   `eval echo \\$PAPEROPT_$PAPER` \
   "$@"
-
diff --git a/doc/uml/Makefile b/doc/uml/Makefile.am
similarity index 55%
rename from doc/uml/Makefile
rename to doc/uml/Makefile.am
index 0f387a9..901f60c 100644
--- a/doc/uml/Makefile
+++ b/doc/uml/Makefile.am
@@ -1,5 +1,3 @@
-# doc/uml Makefile
-#
 #  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
@@ -16,8 +14,28 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-# This is exlicitly not tied in to the general make setup. It is intended
-# to be run manually only as needed so that only people who need to update
-# diagrams must install Java support for plantuml.
-all:
-	java -jar ~/bin/plantuml.jar -o images -tsvg *.uml
+.PHONY: jar-check
+
+if BUILD_DOCS
+images := $(patsubst %.uml,images/%.svg,$(wildcard *.uml))
+PLANTUML_JAR := $(shell ../plantuml_fetch.sh | tail -1)
+
+all-am: jar-check $(images)
+endif
+
+images/%.svg : %.uml
+	$(JAVA) -jar $(PLANTUML_JAR) -o images -tsvg $<
+
+clean-local: rm images/*.svg
+
+jar-check:
+	@if [ -z "$(PLANTUML_JAR)" ] ; then \
+	  echo plantuml jar file variable not set.; \
+	  exit 1; \
+	elif [ ! -r "$(PLANTUML_JAR)" ] ; then \
+	  echo plantuml jar \'${PLANTUML_JAR}\' not readable.; \
+	  exit 1; \
+	elif [ -d "${PLANTUML_JAR}" ] ; then \
+	  echo plantuml jar not downloaded to \'${PLANTUML_JAR}\'.; \
+	  exit 1; \
+	fi
diff --git a/doc/uml/images/.gitignore b/doc/uml/images/.gitignore
deleted file mode 100644
index 85efa6a..0000000
--- a/doc/uml/images/.gitignore
+++ /dev/null
@@ -1,5 +0,0 @@
-## Directory for images generated from UML diagrams.
-# Ignore everything - files are only checked in / updated here manually using `git add -f`.
-# That may change if requiring Java to build the docs for plantuml is approved.
-*
-!.gitignore
diff --git a/doc/uml/images/l4-basic-sequence.svg b/doc/uml/images/l4-basic-sequence.svg
deleted file mode 100644
index 6a0c687..0000000
--- a/doc/uml/images/l4-basic-sequence.svg
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="496px" preserveAspectRatio="none" style="width:428px;height:496px;" version="1.1" viewBox="0 0 428 496" width="428px" zoomAndPan="magnify"><defs><filter height="300%" id="fsmtqap5irkzc" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMa [...]
-@startuml
-
-actor Inbound
-participant "Traffic\nServer" as TS
-participant Outbound
-
-Inbound <-[#green]> TS : <font color="green">//TCP//</font> Handshake
-Inbound -[#blue]> TS : <font color="blue">//initial data//</font>
-note over TS : Examine initial data\nselect Outbound
-TS <-[#green]> Outbound : <font color="green">//TCP//</font> Handshake
-note over TS, Outbound : Additional Setup\n(in some cases)
-TS -[#blue]> Outbound : <font color="blue">//initial data//</font>
-note left : Duplicate of data from Inbound.
-note over TS : Forward bytes\nInbound <&arrow-thick-left> <&arrow-thick-right> Outbound
-Inbound <- -> Outbound
-
-@enduml
-
-PlantUML version 1.2017.18(Fri Oct 06 11:56:32 CDT 2017)
-(GPL source distribution)
-Java Runtime: OpenJDK Runtime Environment
-JVM: OpenJDK 64-Bit Server VM
-Java Version: 1.8.0_151-b12
-Operating System: Linux
-OS Version: 4.13.13-200.fc26.x86_64
-Default Encoding: UTF-8
-Language: en
-Country: US
---></g></svg>
\ No newline at end of file
diff --git a/doc/uml/images/l4-example-cdn-layout.svg b/doc/uml/images/l4-example-cdn-layout.svg
deleted file mode 100644
index 14a0e2f..0000000
--- a/doc/uml/images/l4-example-cdn-layout.svg
+++ /dev/null
@@ -1,27 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="109px" preserveAspectRatio="none" style="width:513px;height:109px;" version="1.1" viewBox="0 0 513 109" width="513px" zoomAndPan="magnify"><defs><filter height="300%" id="f18p37jwo5ssms" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorM [...]
-@startuml
-hide empty members
-
-node Client
-cloud "Untrusted\nNetworks" as Cloud
-node "Edge TS"
-package "Corporate Net" {
-    node Service
-}
-
-[Client] <-> [Cloud]
-[Cloud] <-> [Edge TS]
-[Edge TS] <-> [Service]
-@enduml
-
-PlantUML version 1.2017.18(Fri Oct 06 11:56:32 CDT 2017)
-(GPL source distribution)
-Java Runtime: OpenJDK Runtime Environment
-JVM: OpenJDK 64-Bit Server VM
-Java Version: 1.8.0_151-b12
-Operating System: Linux
-OS Version: 4.13.13-200.fc26.x86_64
-Default Encoding: UTF-8
-Language: en
-Country: US
---></g></svg>
\ No newline at end of file
diff --git a/doc/uml/images/l4-sni-routing-seq.svg b/doc/uml/images/l4-sni-routing-seq.svg
deleted file mode 100644
index 8a965be..0000000
--- a/doc/uml/images/l4-sni-routing-seq.svg
+++ /dev/null
@@ -1,34 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="613px" preserveAspectRatio="none" style="width:596px;height:613px;" version="1.1" viewBox="0 0 596 613" width="596px" zoomAndPan="magnify"><defs><filter height="300%" id="fz7842w3qribd" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMa [...]
-@startuml
-
-actor Inbound
-participant "Traffic\nServer" as TS
-entity "app-server-56:4443" as Outbound
-
-Inbound <-[#green]> TS : <font color="green">//TCP//</font> Handshake
-Inbound -[#blue]> TS : <font color="blue">//TLS//</font> Client HELLO\nSNI=service-2.example.com
-note over TS : Examine SNI value\nSelect Outbound
-TS <-[#green]> Outbound : <font color="green">//TCP//</font> Handshake
-TS -> Outbound : <font color="red">//HTTP//</font> ""CONNECT"" app-server-56:4443
-Outbound -> TS : ""200 OK""
-TS -[#blue]> Outbound : <font color="blue">//TLS//</font> Client HELLO\nSNI=service-2.example.com
-note left : Duplicate of Inbound HELLO
-note over TS : Forward bytes\nInbound <&arrow-thick-left> <&arrow-thick-right> Outbound
-note over Inbound, Outbound : <font color="blue">TLS negotiation</font>
-Inbound <-[#blue]-> Outbound
-note over Inbound, Outbound : Transactions
-Inbound <-[#black]-> Outbound
-
-@enduml
-
-PlantUML version 1.2017.18(Fri Oct 06 11:56:32 CDT 2017)
-(GPL source distribution)
-Java Runtime: OpenJDK Runtime Environment
-JVM: OpenJDK 64-Bit Server VM
-Java Version: 1.8.0_151-b12
-Operating System: Linux
-OS Version: 4.13.13-200.fc26.x86_64
-Default Encoding: UTF-8
-Language: en
-Country: US
---></g></svg>
\ No newline at end of file

-- 
To stop receiving notification emails like this one, please contact
amc@apache.org.