Apache Thrift's website is generated from Markdown source (specifically, kramdown style) with Jekyll, using Bundler to manage its gem dependencies.
Ruby and RubyGems are required to use Jekyll and Bundler, so first make sure you have those on your machine.
If you are using an OS packaged version of Ruby, you may also need to install the ruby-dev (Ubuntu) or ruby-devel (Fedora) package as well to build any native code for gems that are installed later. Installing these will also ensure your system's RubyGems package is installed. Depending on your OS, you may also need other packages to install/build gems, such as ruby-full, make, gcc, nodejs, build-essentials, or patch.
Once Ruby, RubyGems, and any necessary native tools are installed, you are ready to install Bundler to manage the remaining RubyGem dependencies. Bundler is included in Ruby 2.6 and later as a default gem, so installing it may not be needed.
Because we use Bundler to install specific versions of gems, it
is not recommended to use an OS packaged version of gems other
than what comes built-in. If you are using an OS packaged version
of Ruby, it is strongly recommended to avoid sudo when
installing additional gems, in order to avoid conflicting with
your system's package-managed installation. Instead, you can
specify a GEM_HOME directory for installing gems locally in
your home directory. You can do this in your $HOME/.bashrc file
or other appropriate place for your environment:
# in .bashrc
export GEM_HOME=$HOME/.gem/rubyWith Ruby installed on your machine, you can install Bundler using the command below:
# not necessary in Ruby >2.6, since it is a default gem since 2.6
gem install bundlerNext, use Bundler to install Jekyll and other dependencies
needed to run the website (this command assumes your current
working directory is your clone of this repository with the
main branch checked out, because that's where the Gemfile
dependency list exists).
bundle installThe command to serve the site contents using Jekyll's built-in webserver is as follows (this webserver may behave differently than apache.org's servers).
bundle exec jekyll serve -wYou do NOT need to execute a bundle exec jekyll build
command first, as the serve command is sufficient to both build
the site and serve its contents. By default, it will also try to
re-build any pages you change while running the webserver, which
can be quite useful if trying to get some CSS or HTML styled
"just right".
Jekyll will print a local URL where the site can be viewed (usually, http://0.0.0.0:4000/).
Changes pushed to our main branch will automatically trigger
Jekyll to build our site from that branch and push the result to
our asf-staging branch, where they will be served on our
default staging site.
First, add our repository as a remote in your local clone, if you haven't already done so (these commands assume the name of that remote is 'upstream').
Example:
git clone https://github.com/<yourusername>/thrift-website
cd thrift-website
git remote add upstream https://github.com/apache/thrift-websiteNext, publish the staging site to production by updating the
asf-site branch to match the contents in the asf-staging
branch:
# Step 0: stay in main branch; you never need to switch
git checkout main
# Step 1: update your upstream remote
git remote update upstream
# Step 2: push upstream/asf-staging to upstream/asf-site
# run next command with --dry-run first to see what it will do without making changes
git push upstream upstream/asf-staging:asf-siteA convenience script can be found that performs these steps for
you, after asking which remote you want to use. It is located in
the main branch at _scripts/publish.sh
Note that Step 2 should always be a fast-forward merge. That is,
there should never be any reason to force-push it if everything
is done correctly. If extra commits are ever added to asf-site
that are not present in asf-staging, then those branches will
need to be sync'd back up in order to continue avoiding force
pushes.
The final site can be viewed here.