Issue 320: add scripts for publishing new website to staging and apache

.gitignore

@@ -20,6 +20,3 @@ lib/
 log/
 target/
 dependency-reduced-pom.xml
-
-# Generated website
-docs/

pom.xml

@@ -163,7 +163,7 @@
         <version>${maven-javadoc-plugin.version}</version>
         <configuration>
           <!-- Prevent missing javadoc comments from being marked as errors -->
-          <additionalparam>-Xdoclint:none</additionalparam>
+          <additionalparam>-Xdoclint:none -notimestamp</additionalparam>
           <subpackages>org.apache.bookkeeper.client:org.apache.bookkeeper.common.annotation:org.apache.bookkeeper.conf:org.apache.bookkeeper.feature:org.apache.bookkeeper.stats</subpackages>
           <groups>
             <group>

site/.gitignore

@@ -5,3 +5,4 @@ vendor/bundle/
 .bundle/
 .sass-cache/
 local-generated/
+generated_site/

site/Makefile

@@ -8,7 +8,7 @@ dev:
 	make serve
 
 clean:
-	rm -rf _site
+	rm -rf _site local-generated generated_site
 
 setup:
 	gem install bundler \
@@ -22,12 +22,19 @@ build: clean
 	${JEKYLL} build \
 		--config _config.yml
 
-javadoc-gen:
+apache: clean
+	${JEKYLL} build \
+		--config _config.yml,_config.apache.yml
+
+javadoc:
 	scripts/javadoc-gen.sh
 
+staging: clean
+	${JEKYLL} build --config _config.yml,_config.staging.yml
+
 serve: build
 	${JEKYLL} serve \
 		--incremental \
-		--config _config.local.yml
+		--config _config.yml,_config.local.yml
 
 publish: javadoc-gen build

site/README.md

@@ -42,3 +42,18 @@ $ make serve
 ```
 
 Then navigate to `localhost:4000`. As you make changes, the browser will auto-update.
+
+## Staging website for reviews
+
+When you submit a pull request for modifying website or documentation, you are recommended to make your changes live for reviews.
+
+Here are a few steps to follow to stage your changes:
+
+1. You need to create a github repo called `bookkeeper-staging-site` under your github account. You can fork this [staging repo](https://github.com/sijie/bookkeeper-staging-site) as well.
+2. In your `bookeeper-staging-site` repo, go to `Settings > GitHub Pages`. Enable `GitHub Pages` on `master branch /docs folder`.
+3. Make changes to the website, follow the steps above to verify the changes locally.
+4. Once the changes are verified locally, you can run `make staging`. It will generate the files under `site/local-generated`.
+5. Run `scripts/staging-website.sh`. It would push the generated website to your `bookkeeper-staging-site`.
+6. Your changes will be live on `https://<your-github-id>.github.io/bookkeeper-staging-site`.
+
+If you have any ideas to improve the review process for website, please feel free to contact us at dev@bookkeeper.apache.org.

site/_config.apache.yml

@@ -0,0 +1,2 @@
+baseurl: /test/content/
+destination: generated_site/content

site/_config.local.yml

@@ -1,35 +1 @@
-title: Apache BookKeeper
-subtitle: A replicated log service
-github_repo: https://github.com/apache/bookkeeper
-permalink: pretty
-bk_version: "4.5.0"
 destination: local-generated
-baseurl: /
-
-livereload: true
-
-defaults:
-- scope:
-    path: docs
-  values:
-    layout: docs
-    toc: true
-- scope:
-    path: community
-  values:
-    layout: community
-- scope:
-    path: project
-  values:
-    layout: community
-
-gems:
-- jekyll-toc
-
-exclude:
-- Gemfile
-- Gemfile.lock
-- Makefile
-- vendor/bundle
-- scripts
-- overview

site/_config.staging.yml

@@ -0,0 +1,2 @@
+baseurl: /bookkeeper-staging-site/
+destination: local-generated

site/_config.yml

@@ -4,8 +4,8 @@ github_repo: https://github.com/apache/bookkeeper
 github_master: https://github.com/apache/bookkeeper/tree/master
 permalink: pretty
 bk_version: "4.5.0"
-baseurl: /bookkeeper/
-destination: ../docs
+baseurl: /
+destination: local-generated
 twitter_url: https://twitter.com/asfbookkeeper
 
 livereload: true
@@ -39,6 +39,7 @@ exclude:
 - Makefile
 - vendor/bundle
 - local-generated
+- generated_site
 - scripts
 - overview
 - README.md

site/scripts/common.sh

@@ -1,5 +1,9 @@
 #!/bin/bash
 
 ROOT_DIR=$(git rev-parse --show-toplevel)
-JAVADOC_GEN_DIR=target/site/apidocs
-JAVADOC_DEST_DIR=site/javadoc
+REVISION=$(git rev-parse --short HEAD)
+JAVADOC_GEN_DIR=${JAVADOC_GEN_DIR:-"target/site/apidocs"}
+JAVADOC_DEST_DIR=${JAVADOC_DEST_DIR:-"site/javadoc"}
+LOCAL_GENERATED_DIR=$ROOT_DIR/site/local-generated
+APACHE_GENERATED_DIR=$ROOT_DIR/site/generated_site
+TMP_DIR=/tmp/bookkeeper-site

site/scripts/publish-website.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+#
+# 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.
+#
+
+# NOTE: this is the script used by CI to push to apache. If you are looking for
+#       staging the changes, try the `staging-website.sh` script.
+
+source scripts/common.sh
+
+ORIGIN_REPO=$(git remote show origin | grep 'Push  URL' | awk -F// '{print $NF}')
+echo "ORIGIN_REPO: $ORIGIN_REPO"
+
+(
+  cd $APACHE_GENERATED_DIR
+
+  git init
+  git config user.name "Apache BookKeeper Site Updater"
+  git config user.email "dev@bookkeeper.apache.org"
+
+  git remote add upstream "https://$ORIGIN_REPO"
+  git fetch upstream
+  git reset upstream/asf-site
+
+  touch .
+
+  git add -A .
+  git commit -m "Updated site at revision $REVISION"
+  git push -q upstream HEAD:asf-site
+)

site/scripts/staging-website.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+#
+# 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.
+#
+
+source scripts/common.sh
+
+ORIGIN_REPO=$(git remote show origin | grep 'Push  URL' | awk -F// '{print $NF}')
+echo "ORIGIN_REPO: $ORIGIN_REPO"
+STAGING_REPO=`echo $ORIGIN_REPO | sed -e 's/bookkeeper\.git/bookkeeper-staging-site.git/g'`
+echo "STAGING_REPO: $STAGING_REPO"
+echo "GENERATE SITE DIR: $LOCAL_GENERATED_DIR"
+
+(
+  rm -rf $TMP_DIR
+  mkdir -p $TMP_DIR
+  cp -r $LOCAL_GENERATED_DIR $TMP_DIR/docs
+  cd $TMP_DIR
+
+  git init
+
+  git remote add upstream "https://$STAGING_REPO"
+  git fetch upstream
+  git reset upstream/master
+
+  touch .
+
+  git add -A .
+  git commit -m "Updated site at revision $REVISION"
+  git push -q upstream HEAD:master
+
+  rm -rf $TMP_DIR
+)