Combine Brooklyn docs into single page/pdf - for review
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/cbdf51d1 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/cbdf51d1 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/cbdf51d1 Branch: refs/heads/master Commit: cbdf51d17705284d40736087fae2f3fd9eeec14c Parents: 7d24e76 Author: Duncan Godwin <[email protected]> Authored: Tue Feb 2 11:03:42 2016 +0000 Committer: Duncan Godwin <[email protected]> Committed: Thu Feb 25 14:50:25 2016 +0000 ---------------------------------------------------------------------- .gitignore | 1 + _build/build.sh | 28 +++++++++++++--- _build/buildPDF.sh | 25 ++++++++++++++ _includes/singlepage-content.html | 59 ++++++++++++++++++++++++++++++++++ _includes/singlepage-item.html | 46 ++++++++++++++++++++++++++ _layouts/singlePage.html | 15 +++++++++ _plugins/regex_filter.rb | 12 +++++++ guide/dev/index.md | 1 + guide/java/index.md | 1 + guide/misc/index.md | 1 + guide/ops/index.md | 1 + guide/start/index.md | 1 + singlePageManual.html | 26 +++++++++++++++ singlePageStarted.html | 26 +++++++++++++++ website/community/index.md | 2 ++ website/developers/index.md | 1 + website/documentation/index.md | 1 + website/learnmore/index.md | 1 + website/meta/sitemap.md | 1 + website/meta/versions.md | 1 + 20 files changed, 246 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore index 806a062..97a4608 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ brooklyn*.log.* ignored _site +_pdf _config_local.yml .sass-cache style/js/catalog/items.js http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_build/build.sh ---------------------------------------------------------------------- diff --git a/_build/build.sh b/_build/build.sh index b4c8f15..1438424 100755 --- a/_build/build.sh +++ b/_build/build.sh @@ -31,9 +31,10 @@ function help() { echo "* --skip-javadoc : to skip javadoc build" echo "* --quick-javadoc : to do a quick javadoc build (for testing)" echo "* --serve : serve files from _site after building (for testing)" - echo "* --install : install files from _site to the appropriate place in "'$'"BROOKLYN_SITE_DIR (or ../../brooklyn-site-public)" + echo "* --install : install files from _site to the appropriate place in "'$'"BROOKLYN_SITE_DIR (or ../../incubator-brooklyn-site-public)" echo "* --skip-htmlproof : skip the HTML Proof run on _site" echo "* --quick-htmlproof : do a fast HTML Proof run on _site (not checking external links)" + echo "* --skip-pdf : skip generation of the PDF Documentation" echo "" } @@ -156,6 +157,10 @@ function parse_arguments() { QUICK_HTMLPROOF=true shift ;; + "--skip-pdf") + SKIP_PDF=true + shift + ;; *) echo "ERROR: invalid argument '"$1"'" exit 1 @@ -165,12 +170,25 @@ function parse_arguments() { } # Runs htmlproof against _site +function build_pdf() { + if [ "$SKIP_PDF" == "true" ]; then + return + fi + echo "Running PDF Generation on _site/UserManual.html" + rm -rf _pdf + mkdir -p _pdf + PDF_MANUAL_LOG="_pdf/pdf_gen_manual.log" + PDF_STARTED_LOG="_pdf/pdf_gen_started.log" + _build/buildPDF.sh "_site/singlePageManual.html" "_pdf/UserManual.pdf" 2>&1 | tee $PDF_MANUAL_LOG + _build/buildPDF.sh "_site/singlePageStarted.html" "_pdf/GettingStarted.pdf" 2>&1 | tee $PDF_STARTED_LOG +} + +# Runs htmlproof against _site function test_site() { if [ "$SKIP_HTMLPROOF" == "true" ]; then return fi echo "Running htmlproof on _site" - mkdir -p _build/target HTMLPROOF_LOG="_build/target/htmlproof.log" if [ "$QUICK_HTMLPROOF" == "true" ]; then HTMLPROOF_OPTS="$HTMLPROOF_OPTS --disable_external" @@ -250,8 +268,8 @@ function make_install() { fi if [ ! -z ${QUICK_JAVADOC+SET} ]; then echo "ERROR: --install not permitted when doing quick javadoc" ; return 1 ; fi - SITE_DIR=${BROOKLYN_SITE_DIR-../../brooklyn-site-public} - ls $SITE_DIR/style/img/apache-brooklyn-logo-244px-wide.png > /dev/null || { echo "ERROR: cannot find brooklyn-site-public; set BROOKLYN_SITE_DIR" ; return 1 ; } + SITE_DIR=${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public} + ls $SITE_DIR/style/img/apache-brooklyn-logo-244px-wide.png > /dev/null || { echo "ERROR: cannot find incubator-brooklyn-site-public; set BROOKLYN_SITE_DIR" ; return 1 ; } if [ -z ${INSTALL_RSYNC_OPTIONS+SET} ]; then echo "ERROR: --install not supported for this build" ; return 1 ; fi if [ -z ${INSTALL_RSYNC_SUBDIR+SET} ]; then echo "ERROR: --install not supported for this build" ; return 1 ; fi @@ -304,6 +322,8 @@ make_jekyll || { echo ERROR: failed jekyll docs build in `pwd` ; exit 1 ; } make_javadoc || { echo ERROR: failed javadoc build ; exit 1 ; } +build_pdf + test_site # TODO build catalog http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_build/buildPDF.sh ---------------------------------------------------------------------- diff --git a/_build/buildPDF.sh b/_build/buildPDF.sh new file mode 100755 index 0000000..54ff597 --- /dev/null +++ b/_build/buildPDF.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# +# this generates A PDF from a HTML file + +if [ ! -x _build/build.sh ] ; then + echo "ERROR: script must be run in root of docs dir" + exit 1 +fi + +if [ "$#" -lt 2 ] ; then + echo "Usage: buildPDF.sh <source html> <target PDF>" + exit 1 +fi + +command -v wkhtmltopdf >/dev/null 2>&1 || { + echo "ERROR: script requires wkhtmltopdf but it's not installed." >&2; exit 1; + } + +# run the PDF build with wkhtmltopdf +wkhtmltopdf --page-size Letter --margin-top 0.75in --margin-right 0.75in --margin-bottom 0.75in --margin-left 0.75in --encoding UTF-8 $1 $2 +if [ $? -eq 1 ] ; then + echo "Note that ContentNotFoundError is usually because of the invalid relational path of a local resource such as an image" +else + echo "PDF Built successfully." +fi \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_includes/singlepage-content.html ---------------------------------------------------------------------- diff --git a/_includes/singlepage-content.html b/_includes/singlepage-content.html new file mode 100644 index 0000000..4b10bf8 --- /dev/null +++ b/_includes/singlepage-content.html @@ -0,0 +1,59 @@ +{% pop site_items item %} +{% if item[pageMask] != true %} + + {% set_hash_entry item path item_path %} + {% set_hash_entry item url item_url %} + {% set_hash_entry item content item_content %} + {% set_hash_entry item title item_title %} + {% set_hash_entry item id item_id %} + + {% unless item_path %} + {% unless item_url %} + {% puts error, null item_url %} + {% putp item %} + {% putv item_url %} + {% fail item missing path and url (jekyll block evaluation order can cause this) %} + {% endunless %} + {% endunless %} + + {% if visitedb contains item_title %} + {% comment %} <!-- ignore --> {% endcomment %} + {% elsif item['external'] %} + {% comment %} <!-- ignore --> {% endcomment %} + + {% else %} + {% capture pid %}{{ item.title | remove:'/' | replace:' ','-' | downcase }}{% endcapture %} + {% if item_content != null %} + <div id="contentsLink-{{pid}}" class="section p-{{item_id}}"> + <h1>{{ item_title }}</h1> + {% comment %} + <!-- + --This Section re-writes images so the base of their paths is the root docs directory. This allows the PDF to build properly. + --> + {% endcomment %} + + {% comment %}<!-- Build the page directory by removing the file name from the item url -->{% endcomment %} + {% capture page_url %}{{ item_url | replace_regex:'[^\/]*$', '' }}{% endcapture %} + {% capture new_var %}img src=".{{ page_url }}{% endcapture %} + + {% comment %}<!-- Build a regex which replaces the current path with an absolute one but leaves any sub folders such as /images -->{% endcomment %} + {% capture regex %}(img(.*)src="{{ page_url | replace:'/','\/' }})|(img(.*)src="){% endcapture %} + + {% comment %}<!-- Filter the content of the included page -->{% endcomment %} + {% capture content_filtered %}{{ item_content | replace_regex:regex, new_var }}{% endcapture %} + {{ content_filtered }} + </div> + {% endif %} + {% if item['menu'] %} + {% push visitedb item_title %} + {% push site_items item %} + {% assign last_item = site_items[-1] %} + {% for item in last_item['menu'] %} + {% push site_items item %} + {% include singlepage-content.html %} + {% endfor %} + {% pop site_items item %} + {% endif %} + {% endif %} + + {% endif %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_includes/singlepage-item.html ---------------------------------------------------------------------- diff --git a/_includes/singlepage-item.html b/_includes/singlepage-item.html new file mode 100644 index 0000000..803cf7e --- /dev/null +++ b/_includes/singlepage-item.html @@ -0,0 +1,46 @@ +{% pop site_items item %} +{% if item[pageMask] != true %} + + {% set_hash_entry item path item_path %} + {% set_hash_entry item url item_url %} + {% set_hash_entry item title item_title %} + {% set_hash_entry item content item_content %} + {% set_hash_entry item data item_data %} + + {% unless item_path %} + {% unless item_url %} + {% puts error, null item_url %} + {% putp item %} + {% putv item_url %} + {% fail item missing path and url (jekyll block evaluation order can cause this) %} + {% endunless %} + {% endunless %} + + {% capture pid %}{{ item.title | remove:'/' | replace:' ','-' | downcase }}{% endcapture %} + <a id="{{ item_path }}" name="{{ item_path }}" href="javascript:void(0);"></a> + <li> + {% if visited contains item_title %} + {{ item['title'] }} <a href="#link-{{pid}}"><span class="octicon octicon-link-external flip"></span></a> + {% elsif item['external'] %} + {{ item['title'] }} <a href="{{ item['url'] }}"><span class="octicon octicon-link-external"></span></a> + {% else %} + {% if item['content'] != null %} + <a href="#contentsLink-{{pid}}" id="link-{{pid}}">{{ item['title'] }}</a> + {% else %} + {{ item['title'] }} + {% endif %} + {% if item['menu'] %} + {% push visited item_title %} + <ul> + {% push site_items item %} + {% assign last_item = site_items[-1] %} + {% for item in last_item['menu'] %} + {% push site_items item %} + {% include singlepage-item.html %} + {% endfor %} + {% pop site_items item %} + </ul> + {% endif %} + {% endif %} + </li> +{% endif %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_layouts/singlePage.html ---------------------------------------------------------------------- diff --git a/_layouts/singlePage.html b/_layouts/singlePage.html new file mode 100644 index 0000000..6f45639 --- /dev/null +++ b/_layouts/singlePage.html @@ -0,0 +1,15 @@ +--- +--- +<!DOCTYPE html> +<html> +<head> + +</head> + + +<body> + +{{ content }} + +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/_plugins/regex_filter.rb ---------------------------------------------------------------------- diff --git a/_plugins/regex_filter.rb b/_plugins/regex_filter.rb new file mode 100644 index 0000000..4ece039 --- /dev/null +++ b/_plugins/regex_filter.rb @@ -0,0 +1,12 @@ +module Jekyll + module RegexFilter + def replace_regex(input, reg_str, repl_str) + re = Regexp.new reg_str, Regexp::MULTILINE + + # This will be returned + input.gsub re, repl_str + end + end +end + +Liquid::Template.register_filter(Jekyll::RegexFilter) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/guide/dev/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/index.md b/guide/dev/index.md index 79e22fd..f0cf45e 100644 --- a/guide/dev/index.md +++ b/guide/dev/index.md @@ -1,5 +1,6 @@ --- title: Developer Guide +started-pdf-exclude: true layout: website-normal menu_parent: /website/documentation/ breadcrumbs: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/guide/java/index.md ---------------------------------------------------------------------- diff --git a/guide/java/index.md b/guide/java/index.md index 279ca4b..e2b7984 100644 --- a/guide/java/index.md +++ b/guide/java/index.md @@ -2,6 +2,7 @@ title: Java Blueprints title_in_menu: Java Blueprints layout: website-normal +started-pdf-exclude: true children: - archetype.md - defining-and-deploying.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/guide/misc/index.md ---------------------------------------------------------------------- diff --git a/guide/misc/index.md b/guide/misc/index.md index fab2222..6463cf5 100644 --- a/guide/misc/index.md +++ b/guide/misc/index.md @@ -2,6 +2,7 @@ # BROOKLYN_VERSION_BELOW title: Other 0.9.0-SNAPSHOT Resources layout: website-normal +started-pdf-exclude: true children: - { title: Javadoc, path: javadoc/ } - download.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/guide/ops/index.md ---------------------------------------------------------------------- diff --git a/guide/ops/index.md b/guide/ops/index.md index 78644d9..192bc77 100644 --- a/guide/ops/index.md +++ b/guide/ops/index.md @@ -1,5 +1,6 @@ --- title: Operations +started-pdf-exclude: true layout: website-normal children: - server-cli-reference.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/guide/start/index.md ---------------------------------------------------------------------- diff --git a/guide/start/index.md b/guide/start/index.md index ea8c2a3..aa14f22 100644 --- a/guide/start/index.md +++ b/guide/start/index.md @@ -1,6 +1,7 @@ --- layout: website-normal title: Getting Started +usermanual-pdf-exclude: true children: - running.md - blueprints.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/singlePageManual.html ---------------------------------------------------------------------- diff --git a/singlePageManual.html b/singlePageManual.html new file mode 100644 index 0000000..98bd900 --- /dev/null +++ b/singlePageManual.html @@ -0,0 +1,26 @@ +--- +title: Apache Brooklyn Manual +layout: singlePage +--- + <div id="content_container" class="container"> + <header> + <h1>Apache Brooklyn: User Manual</h1> + </header> + <h1>Contents</h1> + + {% assign pageMask = "usermanual-pdf-exclude" %} + + <nav><ul><!-- site.pages --> + {% assign visited = "" | split: "|" %} + {% for node in site.data.menu %} + {% push site_items node %} + {% include singlepage-item.html %} + {% endfor %} + </ul></nav> + + {% assign visitedb = "" | split: "|" %} + {% for node in site.data.menu %} + {% push site_items node %} + {% include singlepage-content.html %} + {% endfor %} + </div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/singlePageStarted.html ---------------------------------------------------------------------- diff --git a/singlePageStarted.html b/singlePageStarted.html new file mode 100644 index 0000000..5598f55 --- /dev/null +++ b/singlePageStarted.html @@ -0,0 +1,26 @@ +--- +title: Apache Brooklyn Manual +layout: singlePage +--- + <div id="content_container" class="container"> + <header> + <h1>Apache Brooklyn: Getting Started Guide</h1> + </header> + <h1>Contents</h1> + + {% assign pageMask = "started-pdf-exclude" %} + + <nav><ul><!-- site.pages --> + {% assign visited = "" | split: "|" %} + {% for node in site.data.menu %} + {% push site_items node %} + {% include singlepage-item.html %} + {% endfor %} + </ul></nav> + + {% assign visitedb = "" | split: "|" %} + {% for node in site.data.menu %} + {% push site_items node %} + {% include singlepage-content.html %} + {% endfor %} + </div> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/community/index.md ---------------------------------------------------------------------- diff --git a/website/community/index.md b/website/community/index.md index 29fe46c..a046f3c 100644 --- a/website/community/index.md +++ b/website/community/index.md @@ -1,6 +1,8 @@ --- layout: website-normal title: Community +started-pdf-exclude: true +usermanual-pdf-exclude: true children: - mailing-lists.md - irc.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/developers/index.md ---------------------------------------------------------------------- diff --git a/website/developers/index.md b/website/developers/index.md index 5e07c87..4f0e605 100644 --- a/website/developers/index.md +++ b/website/developers/index.md @@ -1,6 +1,7 @@ --- layout: website-normal title: Developers +started-pdf-exclude: true children: - code/ - how-to-contribute.md http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/documentation/index.md ---------------------------------------------------------------------- diff --git a/website/documentation/index.md b/website/documentation/index.md index 5c07fa1..80f9555 100644 --- a/website/documentation/index.md +++ b/website/documentation/index.md @@ -1,6 +1,7 @@ --- layout: website-normal title: Documentation +started-pdf-exclude: true children: - /guide/ - /guide/dev/ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/learnmore/index.md ---------------------------------------------------------------------- diff --git a/website/learnmore/index.md b/website/learnmore/index.md index e3b84a4..42dfa69 100644 --- a/website/learnmore/index.md +++ b/website/learnmore/index.md @@ -1,6 +1,7 @@ --- layout: website-normal title: Learn More +started-pdf-exclude: true children: - blueprint-tour.md - features/ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/meta/sitemap.md ---------------------------------------------------------------------- diff --git a/website/meta/sitemap.md b/website/meta/sitemap.md index 7411976..38c66b3 100644 --- a/website/meta/sitemap.md +++ b/website/meta/sitemap.md @@ -1,5 +1,6 @@ --- layout: website-normal +usermanual-pdf-exclude: true title: Site Map --- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cbdf51d1/website/meta/versions.md ---------------------------------------------------------------------- diff --git a/website/meta/versions.md b/website/meta/versions.md index 4e704f4..f3941d7 100644 --- a/website/meta/versions.md +++ b/website/meta/versions.md @@ -1,5 +1,6 @@ --- layout: website-normal +usermanual-pdf-exclude: true title: Versions ---
