You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by vi...@apache.org on 2016/05/25 18:31:52 UTC
mesos git commit: Updated the website generation and development
workflows with docker.
Repository: mesos
Updated Branches:
refs/heads/master 42e5126f5 -> d9b369459
Updated the website generation and development workflows with docker.
In this change, we include below items to make it more convenient to
develop and generate the website.
* Added `doxygen` and `javadoc` to `rake` default target.
* Added `build.sh` as the wrapper for the website generation to make
sure we clean up generated documents when exiting.
* Switched the `Dockerfile` to use `centos:7` because the default
`doxygen` version in `ubuntu:14.04` doesn't include `jquery.js`
correctly when generating `doxygen` documents.
* Adjusted the `Dockerfile` and `README.md` locations to make it
easy to find the website generation document.
* Updated `release-guide.md` with the new website generation and
development workflows.
Review: https://reviews.apache.org/r/47695/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/d9b36945
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/d9b36945
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/d9b36945
Branch: refs/heads/master
Commit: d9b3694597d5e271886c912ca1bb978d3e69f92c
Parents: 42e5126
Author: haosdent huang <ha...@gmail.com>
Authored: Wed May 25 11:29:46 2016 -0700
Committer: Vinod Kone <vi...@gmail.com>
Committed: Wed May 25 11:29:46 2016 -0700
----------------------------------------------------------------------
docs/release-guide.md | 9 +--
site/.gitignore | 1 +
site/Dockerfile | 15 +++++
site/Gemfile | 4 +-
site/Gemfile.lock | 9 +++
site/README.md | 113 +++++++++++++++++++++---------------
site/Rakefile | 19 ++++--
site/build.sh | 28 +++++++++
support/site-docker/Dockerfile | 17 ------
support/site-docker/README.md | 27 ---------
10 files changed, 139 insertions(+), 103 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/docs/release-guide.md
----------------------------------------------------------------------
diff --git a/docs/release-guide.md b/docs/release-guide.md
index 36e7979..dbe6d20 100644
--- a/docs/release-guide.md
+++ b/docs/release-guide.md
@@ -181,17 +181,14 @@ Update the wiki entry, [Mesos Release Planning](https://cwiki.apache.org/conflue
2. Update the [Getting Started](getting-started.md) guide to use the latest release link.
-3. See our [website README](https://github.com/apache/mesos/blob/master/site/README.md/) for details on how to build the website.
- Note that we need to generate the doxygen and javadoc pages when building it.
-
-4. Check out the website from svn and update it with the new version of the website pages just generated.
+3. Check out the website from svn.
$ svn co https://svn.apache.org/repos/asf/mesos/site mesos-site
- $ rm -r mesos-site/publish && cp -r <path-to-mesos-source>/site/publish mesos-site/
+ See our [website README](https://github.com/apache/mesos/blob/master/site/README.md/) for details on how to build the website.
See the general [Apache project website guide](https://www.apache.org/dev/project-site.html) for details on how to publish the website.
-5. Write a blog post announcing the new release and its features and major bug fixes. Include a link to the updated website.
+4. Write a blog post announcing the new release and its features and major bug fixes. Include a link to the updated website.
## Remove old releases from svn
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/.gitignore
----------------------------------------------------------------------
diff --git a/site/.gitignore b/site/.gitignore
index 987a5d3..e180964 100644
--- a/site/.gitignore
+++ b/site/.gitignore
@@ -1,3 +1,4 @@
+source/api
source/documentation
source/assets/img/documentation
publish
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/Dockerfile
----------------------------------------------------------------------
diff --git a/site/Dockerfile b/site/Dockerfile
new file mode 100644
index 0000000..80e28e9
--- /dev/null
+++ b/site/Dockerfile
@@ -0,0 +1,15 @@
+FROM centos:7
+MAINTAINER "dev@mesos.apache.org"
+
+LABEL Description="This image is used for generating Mesos web site from local sources and serving it on port 4567."
+
+RUN yum install -y gcc-c++ make ruby ruby-devel rake doxygen java-1.7.0-openjdk-devel
+RUN gem install bundler
+
+ENV LANG en_US.UTF-8
+ENV LC_ALL en_US.UTF-8
+
+EXPOSE 4567
+
+WORKDIR /mesos/site
+CMD bash build.sh
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/Gemfile
----------------------------------------------------------------------
diff --git a/site/Gemfile b/site/Gemfile
index 14c5034..4dcd0a5 100644
--- a/site/Gemfile
+++ b/site/Gemfile
@@ -7,4 +7,6 @@ gem 'middleman-blog', '3.5.1'
gem "rdiscount", '2.1.7'
-gem "htmlentities"
\ No newline at end of file
+gem "htmlentities"
+
+gem "therubyracer"
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/Gemfile.lock
----------------------------------------------------------------------
diff --git a/site/Gemfile.lock b/site/Gemfile.lock
index 065107e..1393246 100644
--- a/site/Gemfile.lock
+++ b/site/Gemfile.lock
@@ -30,6 +30,7 @@ GEM
http_parser.rb (0.5.3)
i18n (0.6.5)
kramdown (1.2.0)
+ libv8 (3.16.14.15)
listen (1.3.1)
rb-fsevent (>= 0.9.3)
rb-inotify (>= 0.9)
@@ -82,6 +83,7 @@ GEM
rb-kqueue (0.2.0)
ffi (>= 0.5.0)
rdiscount (2.1.7)
+ ref (2.0.0)
rouge (0.3.10)
thor
sass (3.2.12)
@@ -95,6 +97,9 @@ GEM
sprockets-sass (1.0.2)
sprockets (~> 2.0)
tilt (~> 1.1)
+ therubyracer (0.12.2)
+ libv8 (~> 3.16.14.0)
+ ref
thor (0.18.1)
thread_safe (0.1.3)
atomic
@@ -115,3 +120,7 @@ DEPENDENCIES
middleman-livereload (= 3.1.0)
middleman-syntax (= 1.2.1)
rdiscount (= 2.1.7)
+ therubyracer
+
+BUNDLED WITH
+ 1.12.4
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/README.md
----------------------------------------------------------------------
diff --git a/site/README.md b/site/README.md
index 468021e..91bfd5f 100644
--- a/site/README.md
+++ b/site/README.md
@@ -1,61 +1,82 @@
# Apache Mesos website generator
-This will generate the site available at http://mesos.apache.org. The content
-within the publish folder will be the actual deployed site.
+This will generate the site available at http://mesos.apache.org. We use docker
+to simplify our generation and development workflows.
-## Setup
+## Build the docker image
- gem install bundler
- bundle install
+Under the root of your local Mesos git repository, run the following command
+to build the docker image.
+```
+docker build -t mesos/website site
+```
## Generating the site
-Running `rake` will download the latest Apache Mesos documentation contained
-in the `docs` folder, integrate them into the site, and generate all other
-files within the source folder.
- # First generate the help endpoint documentation. Running
- # `make check` is needed to generate the latest version of
- # the master and slave binaries.
- make check -jN GTEST_FILTER=""
- ../support/generate-endpoint-help.py
- rake
-
-The doxygen and javadoc pages must be generated _after_ running `rake`.
-
-### Generating doxygen pages
-Doxygen pages can be generated using:
-
- rake doxygen
-
-### Generating javadoc pages
-Javadoc pages can be generated using:
-
- rake javadoc
+Before we start the docker container, we need to generate the help endpoint
+documentation. Running `make` is needed to generate the latest version of
+the master and agent binaries.
+
+```
+make -jN
+../support/generate-endpoint-help.py
+```
+
+To build and run the website inside a docker container please substitute
+*<path-to-mesos-source>* with the actual location of Mesos source code tree
+and *<path-to-mesos-website-svn-source>* with the actual location of Mesos
+website svn source code tree in the command below and run it.
+
+```
+sudo docker run -it --rm \
+ -p 4567:4567 \
+ -v <path-to-mesos-source>:/mesos \
+ -v <path-to-mesos-website-svn-source>/publish:/mesos/site/publish \
+ mesos/website
+```
+
+If you don't intend to update the svn source code of the Mesos website, you
+could run the command below under the root of Mesos source code instead.
+
+```
+sudo docker run -it --rm \
+ -p 4567:4567 \
+ -v `pwd`:/mesos \
+ mesos/website
+```
+
+This will start a container, generate the website from your local Mesos git
+repository, and make it available:
+ - On Linux, the site will be available at http://localhost:4567.
+ - On OS X, run `docker-machine ls` to find the IP address of your
+ boot-to-docker VM; the site will be available at that IP, port 4567.
+
+If you are running the container on a remote machine and need to tunnel it to
+localhost, you can run the following command to make the site available locally:
+
+```
+ssh -NT -L 4567:localhost:4567 <remote-machine>
+```
+
+The generation includes `doxygen` and `javadoc` as well. We could check out them
+under `/api/latest/c++/index.html` and `/api/latest/java/index.html` endpoints
+once the generation finishs.
## Development
-To live edit the site run `rake dev` and then open a browser window to
-http://localhost:4567/ . Any change you make to the sources dir will
-be shown on the local dev site immediately. Errors will be shown in the
-console you launched `rake dev` within.
-
-There is also a Dockerfile to simplify local website development. Please see
-[support/site-docker/README.md](../support/site-docker/README.md) for
-instructions.
+Any changes to the `site/source` directory will cause middleman to reload and
+regenerate the website, so you can just edit, save, refresh. When you are done
+with the webserver, hit Ctrl-C in the docker terminal to kill the middleman
+webserver, clean up generation documents under the `site/source` directory and
+destroy/remove the container.
## Publishing the Site
-The website uses svnpubsub. The publish folder contains the websites content
-and when committed to the svn repository it will be automatically deployed to
-the live site.
+Because we mount the `publish` folder under Mesos website svn source code into
+the docker container we launched above, all website contents would be ready
+under the `publish` folder when the generation finishs.
-## Other available tasks
-
- rake build # Build the website from source
- rake clean # Remove any temporary products
- rake clobber # Remove any generated file
- rake dev # Run the site in development mode
- rake update_docs # Update the latest docs from the Apache Mesos codebase
- rake doxygen # Update doxygen from C++ source files
- rake javadoc # Update javadocs from java source files
+The website uses svnpubsub. The `publish` folder contains the websites content
+and when committed to the svn repository it will be automatically deployed to
+the live site.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/Rakefile
----------------------------------------------------------------------
diff --git a/site/Rakefile b/site/Rakefile
index 845ec3f..aa777bd 100644
--- a/site/Rakefile
+++ b/site/Rakefile
@@ -2,7 +2,7 @@ require 'rubygems'
require 'rake/clean'
require 'fileutils'
-task :default => [:update_docs, :build, :clean]
+task :default => [:update_docs, :doxygen, :javadoc, :build, :clean]
CLEAN.include("**/.DS_Store")
@@ -72,18 +72,25 @@ end
desc "Generate javadoc from the Java source files in the codebase"
task :javadoc do
proto_java_folder = "../build/src/java/generated"
- if File.directory?(proto_java_folder)
+ if not File.directory?(proto_java_folder)
raise "Please make sure Java proto files are generated in #{proto_java_folder} folder."
end
# TODO: add version to the path. Uses 'current' for now.
- system("javadoc -d publish/api/latest/java -sourcepath ../src/java/src:#{proto_java_folder} org.apache.mesos")
+ system("javadoc -d source/api/latest/java -sourcepath ../src/java/src:#{proto_java_folder} org.apache.mesos")
end
desc "Generate doxygen from the C++ source files in the codebase"
task :doxygen do
- FileUtils.rm_rf(Dir.glob("publish/api/latest/c++"))
- FileUtils.mkdir_p("publish/api/latest")
- system("doxygen ../Doxyfile && mv doxygen/html publish/api/latest/c++ && rm -rf doxygen")
+ FileUtils.rm_rf(Dir.glob("source/api/latest/c++"))
+ FileUtils.mkdir_p("source/api/latest")
+ system("doxygen ../Doxyfile && mv doxygen/html source/api/latest/c++ && rm -rf doxygen")
+end
+
+desc "Clean up generated documents"
+task :clean_docs do
+ FileUtils.rm_rf(Dir.glob("source/api"))
+ FileUtils.rm_rf(Dir.glob("source/documentation"))
+ FileUtils.rm_rf(Dir.glob("source/assets/img/documentation"))
end
desc "Run the site in development mode. Preview available at http://localhost:4567/"
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/site/build.sh
----------------------------------------------------------------------
diff --git a/site/build.sh b/site/build.sh
new file mode 100755
index 0000000..11f15e1
--- /dev/null
+++ b/site/build.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env 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.
+
+# This is a wrapper for building Mesos website locally.
+
+function exit_hook {
+ # Remove generated documents when exit.
+ rake clean_docs
+}
+
+trap exit_hook EXIT
+
+bundle install && rake && rake dev
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/support/site-docker/Dockerfile
----------------------------------------------------------------------
diff --git a/support/site-docker/Dockerfile b/support/site-docker/Dockerfile
deleted file mode 100644
index 8ea3d5c..0000000
--- a/support/site-docker/Dockerfile
+++ /dev/null
@@ -1,17 +0,0 @@
-FROM ubuntu:14.04
-MAINTAINER "dev@mesos.apache.org"
-
-LABEL Description="This image is used for generating Mesos web site from local sources and serving it on port 4567."
-
-RUN apt-get update
-RUN apt-get install -y subversion g++ ruby ruby-dev make rake nodejs git
-RUN gem install bundler
-
-ENV LANG C.UTF-8
-ENV LANGUAGE C.UTF08
-ENV LC_ALL C.UTF-8
-
-EXPOSE 4567
-
-WORKDIR /mesos/site
-CMD bundle install && rake && rake dev
http://git-wip-us.apache.org/repos/asf/mesos/blob/d9b36945/support/site-docker/README.md
----------------------------------------------------------------------
diff --git a/support/site-docker/README.md b/support/site-docker/README.md
deleted file mode 100644
index 957117e..0000000
--- a/support/site-docker/README.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# mesos-website-container
-Docker build scripts for generating mesos.apache.org from the local repo.
-
-To build the docker image:
-
-```
-docker build -t mesos/website support/site-docker
-```
-
-To build and run the website inside a docker container please substitute *<path-to-mesos-source>* with the actual location of Mesos source code tree in the command below and run it.
-
-```
-sudo docker run -it --rm -p 4567:4567 -v <path-to-mesos-source>:/mesos mesos/website
-```
-
-This will start a container, generate the website from your local Mesos Git repository, and make it available:
- - On Linux, the site will be available at http://localhost:4567.
- - On OS X, run `docker-machine ls` to find the IP address of your boot-to-docker VM; the site will be available at that IP, port 4567.
-
-If you are running the container on a remote machine and need to tunnel it to localhost, you can run the following command to make the site available locally:
-
-```
-ssh -NT -L 4567:localhost:4567 <remote-machine>
-```
-
-Any changes to the `site/source` directory will cause middleman to reload and regenerate the website, so you can just edit, save, refresh.
-When you are done with the webserver, hit Ctrl-C in the docker terminal to kill the middleman webserver and destroy/remove the container.