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.