This is an automated email from the ASF dual-hosted git repository. michaelsmith pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/impala.git
commit e1e92da796d27ce519e2919f8b6ae9d930561519 Author: Tamas Mate <[email protected]> AuthorDate: Mon Nov 14 13:03:26 2022 +0100 IMPALA-11676: Prettify asf-site docs This commit refactors and adds a new build option to the docs build script/Makefile, these options are: - plain-html: the plain html docs, without css and navigation bar, this was "the" html build before this change. - asf-site-html: html docs, with css and navigation bar. - pdf The css is comming from DITA project's documentation. Testing: - Built the docs and tested the pages manually. Change-Id: Ic9621cb0abaa7fd9bf445da08440c0f6a9788180 Reviewed-on: http://gerrit.cloudera.org:8080/19242 Reviewed-by: Impala Public Jenkins <[email protected]> Tested-by: Impala Public Jenkins <[email protected]> --- LICENSE.txt | 2 + bin/rat_exclude_files.txt | 2 + docs/Makefile | 15 ++- docs/build-doc.sh | 19 +++- docs/css/dita-ot-doc.css | 268 ++++++++++++++++++++++++++++++++++++++++++++++ docs/impala.ditamap | 4 +- docs/shared/header.xml | 15 +++ 7 files changed, 315 insertions(+), 10 deletions(-) diff --git a/LICENSE.txt b/LICENSE.txt index b6eb55aeb..cc865b4cd 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -672,6 +672,8 @@ be/src/thirdparty/pcg-cpp-0.98: Apache 2.0 license be/src/expr/hll-bias.h: Apache 2.0 license shell/ext-py/sasl-0.2.1: Apache 2.0 license shell/ext-py/thrift_sasl-0.4.2: Apache 2.0 license +docs/css/dita-ot-doc.css: Apache 2.0 license +docs/shared/header.xml: Apache 2.0 license -------------------------------------------------------------------------------- diff --git a/bin/rat_exclude_files.txt b/bin/rat_exclude_files.txt index f0d97e80e..ff1853c83 100644 --- a/bin/rat_exclude_files.txt +++ b/bin/rat_exclude_files.txt @@ -92,6 +92,8 @@ be/src/util/cache/cache-test.h be/src/util/cache/cache-test.cc be/src/util/cache/rl-cache.cc be/src/util/cache/rl-cache-test.cc +docs/css/dita-ot-doc.css +docs/shared/header.xml # http://www.apache.org/legal/src-headers.html: "Short informational text files; for # example README, INSTALL files. The expectation is that these files make it obvious which diff --git a/docs/Makefile b/docs/Makefile index 837a3368c..2904fd0ee 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,18 +15,23 @@ # specific language governing permissions and limitations # under the License. -.PHONY: all html pdf +.PHONY: all plain-html asf-site-html pdf -all: html pdf +all: plain-html asf-site-html pdf -html: build/html/index.html +plain-html: build/plain-html/index.html + +asf-site-html: build/asf-site-html/index.html pdf: build/impala.pdf ALL_DEPS=Makefile impala.ditamap shared/*.xml images/* topics/*.xml -build/html/index.html: impala_html.ditaval ${ALL_DEPS} - ./build-doc.sh xhtml $(dir $@) $< gen-html.log +build/plain-html/index.html: impala_html.ditaval ${ALL_DEPS} + ./build-doc.sh xhtml $(dir $@) $< gen-plain-html.log + +build/asf-site-html/index.html: impala_html.ditaval ${ALL_DEPS} + ./build-doc.sh html5 $(dir $@) $< gen-asf-site-html.log --pretty build/impala.pdf: impala_pdf.ditaval ${ALL_DEPS} ./build-doc.sh pdf $(dir $@) $< gen-pdf.log diff --git a/docs/build-doc.sh b/docs/build-doc.sh index 6153e1da6..e86b5bee3 100755 --- a/docs/build-doc.sh +++ b/docs/build-doc.sh @@ -20,17 +20,30 @@ set -euo pipefail function usage() { - echo "$0 <file_format> <output_file> <filter_file> <log_file>" + echo "$0 <file_format> <output_file> <filter_file> <log_file> [--pretty]" exit 1 } -[[ $# -eq 4 ]] || usage +[[ $# -eq 4 || $# -eq 5 ]] || usage FILE_FORMAT=$1 OUTPUT_FILE=$2 FILTER_FILE=$3 LOG_FILE=$4 -dita -i impala.ditamap -f ${FILE_FORMAT} -o ${OUTPUT_FILE} -filter ${FILTER_FILE} 2>&1 \ +if [[ $# -eq 4 || $5 != "--pretty" ]]; then + dita -i impala.ditamap -f ${FILE_FORMAT} -o ${OUTPUT_FILE} -filter ${FILTER_FILE} 2>&1 \ | tee ${LOG_FILE} +else + dita -i impala.ditamap -f ${FILE_FORMAT} -o ${OUTPUT_FILE} \ + -Dnav-toc=partial \ + -Dargs.copycss=yes \ + -Dargs.csspath=css \ + -Dargs.cssroot=$PWD/css \ + -Dargs.css=dita-ot-doc.css \ + -Dargs.hdr=$PWD/shared/header.xml \ + -filter ${FILTER_FILE} 2>&1 \ + | tee ${LOG_FILE} +fi + [[ -z $(grep "\[ERROR\]" ${LOG_FILE}) ]] || exit 1 diff --git a/docs/css/dita-ot-doc.css b/docs/css/dita-ot-doc.css new file mode 100644 index 000000000..a8114a4e7 --- /dev/null +++ b/docs/css/dita-ot-doc.css @@ -0,0 +1,268 @@ +/************************************************************* +The DITA Open Toolkit is licensed for use under the the Apache +Software Foundation License v2.0. + +A copy of the Apache Software Foundation License 2.0 is +available at http://opensource.org/licenses/apache2.0.php + +This statement must be included in any copies of DITA Open +Toolkit code. +*************************************************************/ + +/* DITA Open Toolkit documentation style */ + +/************************************************************* +Basic fonts and typography +*************************************************************/ + +article { + color: #333; +} + +body { + background-color: white; + background-image: -webkit-linear-gradient(left, #eee 0%, #fff 300px); /* Chrome10+,Safari5.1+ */ + background-image: -moz-linear-gradient(left, #eee 0%, #fff 300px); /* FF3.6+ */ + background-image: linear-gradient(left, #eee 0%, #fff 300px); /* W3C */ + color: #333; + margin: 0; + padding: 1em; +} + +div.header { + font-size: 18pt; + margin: 0; + padding: 0 12px; +} + +div.header p { + color: #777; + font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; + line-height: 1.3; + margin: 0; +} + +div.header hr { + border: 0; + border-bottom: 1px solid #eee; + height: 0; +} + +body, +caption, +td, +th { + font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; + font-size: 10pt; +} + +code, +pre, +.cmdname, +.filepath, +.msgnum, +.option, +.parmname { + color: #777; + font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; + font-size: 90%; +} + +/************************************************************* +Headings +*************************************************************/ + +h1, +h2, +h3 { + color: #1d365d; + font-size: 12pt; + font-weight: bold; + margin-bottom: 0.75em; + margin-left: 0; + margin-right: 0; + margin-top: 1em; + padding: 0; +} + +h1 .filepath, +h2 .filepath, +h3 .filepath { + font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; + font-size: 12pt; + font-weight: bold; +} + +h1 .filepath { + color: #1d365d; +} + +.sectiontitle { + color: #1d365d; + font-weight: bold; +} + +.topictitle1 { + margin-top: 1em; +} + +/************************************************************* +Basic identation, padding, and margins +*************************************************************/ + +main { + margin-left: 300px; +} + +blockquote, +li, +p { + line-height: 125%; + margin-bottom: 0.75em; + margin-left: 0; + margin-right: 0; + margin-top: 0.75em; + padding: 0; +} + +dd { + line-height: 125%; + margin-bottom: 0.75em; + margin-top: 0.75em; +} + +dl { + line-height: 125%; + margin-bottom: 0.75em; + margin-left: 2em; + margin-right: 0; + margin-top: 0.75em; + padding: 0; +} + +ol, +ul { + margin-bottom: 0.75em; + margin-left: 2em; + margin-right: 0; + margin-top: 0.75em; + padding: 0; +} + +pre { + margin-bottom: 0.75em; + margin-left: 2em; + margin-top: 0.75em; + padding: 0; +} + +/************************************************************* +Block elements +*************************************************************/ + +.codeblock, +.screen { + background-color: #eee; + border: 1px solid #ccc; + border-radius: 4px; + padding: 6px; +} + +/************************************************************* +Figures +*************************************************************/ + +figcaption { + font-style: italic; +} + +/************************************************************* +In-line elements +*************************************************************/ + +.cmdname, +.msgnum { + font-weight: bold; +} + +/************************************************************* +Links +*************************************************************/ + +a:link { + color: #3563ab; + text-decoration: none; +} + +a:visited { + color: #3563ab; +} + +a:active, +a:hover { + color: #1d365d; + text-decoration: underline; +} + +.related-links { + color: #555; +} + +.linklist { + margin-top: 1em; +} + +/************************************************************* +Notes +*************************************************************/ + +.note { + line-height: 125%; + margin-left: 2em; + margin-right: 0; + padding: 0; +} + +.caution, +.notelisttitle, +.note__title { + font-weight: bold; +} + +/************************************************************* +Tables +*************************************************************/ + +table { + border-color: Silver; + border-style: solid; + border-width: 1px; + margin-bottom: 1em; + margin-top: 1em; + padding: 1px; +} + +tr { + border-color: Silver; +} + +td { + border-color: Silver; +} + +th { + background-color: #eee; +} + +/************************************************************* +Navigation +*************************************************************/ + +nav[role=toc] { + float: left; + width: 300px; +} + +nav[role=toc] li.active > a { + font-weight: bold; +} diff --git a/docs/impala.ditamap b/docs/impala.ditamap index 6d046e132..7eac4c329 100644 --- a/docs/impala.ditamap +++ b/docs/impala.ditamap @@ -46,11 +46,11 @@ under the License. <topicref href="topics/impala_hadoop.xml"/> </topicref> <topicref href="topics/impala_planning.xml"> - <topicref href="topics/impala_prereqs.xml#prereqs"/> + <topicref href="topics/impala_prereqs.xml"/> <!-- Removed per Alan Choi's request on 4/18/2018 <topicref href="topics/impala_cluster_sizing.xml"/> --> <topicref href="topics/impala_schema_design.xml"/> </topicref> - <topicref audience="standalone" href="topics/impala_install.xml#install"> + <topicref audience="standalone" href="topics/impala_install.xml"> <!-- Removed when Hue docs were removed from main library. Might be worth resurrecting someday as general Impala+Hue topic. --> <!-- <topicref href="impala_hue_xi20559.xml"/> --> </topicref> diff --git a/docs/shared/header.xml b/docs/shared/header.xml new file mode 100644 index 000000000..fbc8d0e91 --- /dev/null +++ b/docs/shared/header.xml @@ -0,0 +1,15 @@ +<!-- +The DITA Open Toolkit is licensed for use under the the Apache +Software Foundation License v2.0. + +A copy of the Apache Software Foundation License 2.0 is +available at http://opensource.org/licenses/apache2.0.php + +This statement must be included in any copies of DITA Open +Toolkit code. +--> + +<div class="header"> + <p>Apache Impala</p> + <hr/> +</div>
