Repository: incubator-brooklyn Updated Branches: refs/heads/0.7.0-M2-incubating-docs 8560033dc -> c6ab6c9cb
backport of recent master doc changes, mainly more version fixes Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/c6ab6c9c Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/c6ab6c9c Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/c6ab6c9c Branch: refs/heads/0.7.0-M2-incubating-docs Commit: c6ab6c9cb95c311ce3ab490f0f2138e330eeb004 Parents: 8560033 Author: Alex Heneveld <[email protected]> Authored: Tue Jan 20 17:20:56 2015 +0000 Committer: Alex Heneveld <[email protected]> Committed: Tue Jan 20 17:20:56 2015 +0000 ---------------------------------------------------------------------- docs/_build/build.sh | 33 ++++++++++++++------ docs/_build/htmlproof-brooklyn.sh | 6 ++-- docs/guide/dev/env/maven-build.md | 18 +++++------ .../guide/dev/tips/debugging-remote-brooklyn.md | 2 +- docs/style/css/javadoc.scss | 2 +- docs/style/css/website.scss | 2 +- .../website/community/how-to-contribute-docs.md | 2 +- docs/website/download/index.md | 13 ++++++-- 8 files changed, 52 insertions(+), 26 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/_build/build.sh ---------------------------------------------------------------------- diff --git a/docs/_build/build.sh b/docs/_build/build.sh index 7af75cf..8d0f6b3 100755 --- a/docs/_build/build.sh +++ b/docs/_build/build.sh @@ -51,6 +51,7 @@ function parse_mode() { INSTALL_RSYNC_OPTIONS="--exclude v" INSTALL_RSYNC_SUBDIR="" SUMMARY="website files in the root" + HTMLPROOF_OPTS=--ignore-v-refs ;; guide-latest) JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-all-but-guide.yml,_build/config-guide-latest.yml,_build/config-style-latest.yml @@ -63,6 +64,7 @@ function parse_mode() { INSTALL_RSYNC_SUBDIR=${DIRS_TO_MOVE_TARGET[0]}/ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/ SUMMARY="user guide files in /${DIRS_TO_MOVE_TARGET[0]}" + HTMLPROOF_OPTS=--v-only ;; guide-version) JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-all-but-guide.yml,_build/config-guide-version.yml @@ -77,6 +79,7 @@ function parse_mode() { INSTALL_RSYNC_SUBDIR=${DIRS_TO_MOVE_TARGET[0]}/ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/ SUMMARY="user guide files in /${DIRS_TO_MOVE_TARGET[0]}" + HTMLPROOF_OPTS=--v-only ;; test-guide-root) JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-all-but-guide.yml,_build/config-guide-root.yml @@ -95,6 +98,7 @@ function parse_mode() { STYLE_SUBDIR=style JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/ SUMMARY="all files, website in root and guide in /${DIRS_TO_MOVE_TARGET[0]}" + HTMLPROOF_OPTS=--ignore-v-refs ;; test-both-sub) JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-root-index.yml,_build/config-subpath-brooklyn.yml @@ -107,11 +111,13 @@ function parse_mode() { DIRS_TO_MOVE_TARGET[2]=$STYLE_SUBDIR JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/ SUMMARY="all files in /brooklyn" + HTMLPROOF_OPTS=--ignore-v-refs ;; original) JEKYLL_CONFIG=_config.yml,_build/config-production.yml STYLE_SUBDIR=style SUMMARY="all files in their original place" + HTMLPROOF_OPTS=--ignore-v-refs ;; "") echo "ERROR: mode is required; try 'help'" @@ -143,11 +149,11 @@ function parse_arguments() { shift ;; "--skip-htmlproof") - SKIP_TEST=true + SKIP_HTMLPROOF=true shift ;; "--quick-htmlproof") - QUICK_TEST=true + QUICK_HTMLPROOF=true shift ;; *) @@ -160,17 +166,16 @@ function parse_arguments() { # Runs htmlproof against _site function test_site() { - if [ "$SKIP_TEST" == "true" ]; then + if [ "$SKIP_HTMLPROOF" == "true" ]; then return fi echo "Running htmlproof on _site" mkdir -p target - LOG="_build/target/htmlproof.log" - HTMLPROOF_OPTS="" - if [ "$QUICK_TEST" == "true" ]; then + HTMLPROOF_LOG="_build/target/htmlproof.log" + if [ "$QUICK_HTMLPROOF" == "true" ]; then HTMLPROOF_OPTS="$HTMLPROOF_OPTS --disable_external" fi - _build/htmlproof-brooklyn.sh $HTMLPROOF_OPTS 2>&1 | tee $LOG + _build/htmlproof-brooklyn.sh $HTMLPROOF_OPTS 2>&1 | tee $HTMLPROOF_LOG } function make_jekyll() { @@ -249,8 +254,18 @@ function make_install() { RSYNC_COMMAND="$RSYNC_COMMAND_BASE $INSTALL_RSYNC_OPTIONS ./_site/$INSTALL_RSYNC_SUBDIR $SITE_DIR/$INSTALL_RSYNC_SUBDIR" echo INSTALLING to local site svn repo with: $RSYNC_COMMAND - $RSYNC_COMMAND || return 1 - + $RSYNC_COMMAND | tee _build/target/rsync.log || return 1 + + echo RSYNC changed files: + grep -v f\\.\\.T\\.\\.\\.\\.\\.\\.\\. _build/target/rsync.log || echo "(none)" + echo + + if [ ! -z "$HTMLPROOF_LOG" ]; then + echo HTMLPROOF log: + cat $HTMLPROOF_LOG + echo + fi + SUMMARY="$SUMMARY, installed to $SITE_DIR" } http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/_build/htmlproof-brooklyn.sh ---------------------------------------------------------------------- diff --git a/docs/_build/htmlproof-brooklyn.sh b/docs/_build/htmlproof-brooklyn.sh index ae07065..5fa6b1b 100755 --- a/docs/_build/htmlproof-brooklyn.sh +++ b/docs/_build/htmlproof-brooklyn.sh @@ -1,6 +1,6 @@ #!/usr/bin/env ruby_executable_hooks -# supports --disable_external +# supports --disable_external, --ignore-v-refs, --v-only require 'html/proofer' @@ -8,12 +8,14 @@ HTML::Proofer.new("./_site", { :href_ignore => [ /https?:\/\/127.*/, /https?:\/\/github.com\/apache\/incubator-brooklyn\/edit.*/, + ((ARGV.include? "--ignore-v-refs") ? /.*\/v\/.*/ : /ignore/), + ((ARGV.include? "--v-only") ? /\/(|[^v].*|.[^\/].*)/ : /ignore/) ], :alt_ignore => [/.*/], # don't scan javadoc files (too many errors) # or autogen catalog items (their style files are wrong in some modes; reinstate when cleaner) :disable_external => (ARGV.include? "--disable_external"), - :file_ignore => [ /.*\/(javadoc|apidoc|learnmore\/catalog)\/.*/ ] + :file_ignore => [ /.*\/(javadoc|apidoc|learnmore\/catalog)\/.*/ ] # bug - must do above - see https://github.com/gjtorikian/html-proofer/issues/145 # :file_ignore => [ /.*\/javadoc\/.*/, /.*\/learnmore\/catalog\/.*/ ] }).run http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/guide/dev/env/maven-build.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/env/maven-build.md b/docs/guide/dev/env/maven-build.md index e9b0f2e..febc66e 100644 --- a/docs/guide/dev/env/maven-build.md +++ b/docs/guide/dev/env/maven-build.md @@ -10,7 +10,7 @@ To build the code, you need Maven (v3) installed and Java (1.6). With that in place, you should be able to build everything with a: {% highlight bash %} -brooklyn% mvn clean install +% mvn clean install {% endhighlight %} Key things to note if you're new to Maven: @@ -80,7 +80,7 @@ understand to be benign and hard to get rid of them, although we'd love to if anyone can help!): {% highlight bash %} -brooklyn% mvn clean install +% mvn clean install [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Build Order: @@ -98,23 +98,23 @@ brooklyn% mvn clean install ... -[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar +[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in ~/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar ... [INFO] â maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist â [INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist -[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment. +{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-M2-incubating; it doesn't have an associated file or directory. +[INFO] Copying files to ~/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist +[WARNING] Assembly file: ~/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment. ... [INFO] â maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist â [INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. +{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-M2-incubating; it doesn't have an associated file or directory. +{% comment %}BROOKLYN_VERSION{% endcomment %}[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-M2-incubating-dist.tar.gz +{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-M2-incubating; it doesn't have an associated file or directory. ... http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/guide/dev/tips/debugging-remote-brooklyn.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/debugging-remote-brooklyn.md b/docs/guide/dev/tips/debugging-remote-brooklyn.md index 4d14e5f..d7d7969 100644 --- a/docs/guide/dev/tips/debugging-remote-brooklyn.md +++ b/docs/guide/dev/tips/debugging-remote-brooklyn.md @@ -25,7 +25,7 @@ This should return details of the build as a JSON string similar to the followin {% highlight json %} { - "version": "0.7.0-SNAPSHOT", + "version": "0.7.0-M2-incubating", {% comment %}BROOKLYN_VERSION{% endcomment %} "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224", "buildBranch": "UNKNOWN" } http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/style/css/javadoc.scss ---------------------------------------------------------------------- diff --git a/docs/style/css/javadoc.scss b/docs/style/css/javadoc.scss index 204c8a9..a9ca9be 100644 --- a/docs/style/css/javadoc.scss +++ b/docs/style/css/javadoc.scss @@ -116,4 +116,4 @@ code { } .header .subTitle .block { font-weight: 300; -} \ No newline at end of file +} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/style/css/website.scss ---------------------------------------------------------------------- diff --git a/docs/style/css/website.scss b/docs/style/css/website.scss index 0698d46..c653fee 100644 --- a/docs/style/css/website.scss +++ b/docs/style/css/website.scss @@ -3,7 +3,7 @@ {% include base-scss.scss %} -$style_dir: {{ site.path.style }}; +$style_dir: "{{ site.path.style }}"; @import 'util'; @import 'basic'; http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/website/community/how-to-contribute-docs.md ---------------------------------------------------------------------- diff --git a/docs/website/community/how-to-contribute-docs.md b/docs/website/community/how-to-contribute-docs.md index 2e29b6b..1d45f2e 100644 --- a/docs/website/community/how-to-contribute-docs.md +++ b/docs/website/community/how-to-contribute-docs.md @@ -27,7 +27,7 @@ The Brooklyn documentation is split into two parts: - **Version-specific user guide**. These pages have a URL with a path that begins /v/*version-number*: for example, - https://brooklyn.incubator.apache.org/v/0.7.0-SNAPSHOT and <!-- BROOKLYN-VERSION --> + https://brooklyn.incubator.apache.org/v/0.7.0-M2-incubating and {% comment %}BROOKLYN_VERSION{% endcomment %} the special *latest* set at https://brooklyn.incubator.apache.org/v/latest . Content for this is in the `guide` directory. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/c6ab6c9c/docs/website/download/index.md ---------------------------------------------------------------------- diff --git a/docs/website/download/index.md b/docs/website/download/index.md index 3008502..f997b92 100644 --- a/docs/website/download/index.md +++ b/docs/website/download/index.md @@ -19,7 +19,14 @@ We do not yet have an official binary package for Apache Brooklyn. We plan to ad However, it is relatively easy to create the binary package from source code, if you have a working recent JDK and Maven 3. -Unpack `apache-brooklyn-{{ site.brooklyn-stable-version }}.tar.gz` and then execute this command in the `apache-brooklyn-{{ site.brooklyn-stable-version }}` folder: +**1)** Unpack `apache-brooklyn-{{ site.brooklyn-stable-version }}.tar.gz` and go into this directory: + +{% highlight bash %} +tar xvfz apache-brooklyn-{{ site.brooklyn-stable-version }}.tar.gz +cd apache-brooklyn-{{ site.brooklyn-stable-version }} +{% endhighlight %} + +**2)** Run this command in the `apache-brooklyn-{{ site.brooklyn-stable-version }}` folder: {% highlight bash %} mvn clean install -DskipTests @@ -27,7 +34,9 @@ mvn clean install -DskipTests You should then find the binary distribution in the folder `usage/dist/target/brooklyn-dist`, or archived as `usage/dist/target/brooklyn-{{ site.brooklyn-stable-version }}-dist.tar.gz`. +**Problems?** More information on building is [here]({{ site.path.guide }}/dev/env/maven-build.html). + ## Get Started! -Take a look at the [Get Started]({{ site.path.guide }}/start/running.html) page! +Take a look at the **[Get Started]({{ site.path.guide }}/start/running.html)** page.
