This directory contains the sources/templates for generating the Apache Calcite website, calcite.apache.org. The actual generated content of the website is present in the calcite-site repository.
We want to deploy project changes (for example, new committers, PMC members or upcoming talks) immediately, but we want to deploy documentation of project features only when that feature appears in a release.
The building and publishing of the website is completely automated using Github actions, so you should simply commit your changes to main. If you are committing a change to the website that needs to be published immediately, the Github action uses these rules.
Site generation currently works best with ruby-2.7.4.
cd site
git clone https://gitbox.apache.org/repos/asf/calcite-site.git target
sudo apt-get install rubygems ruby2.7-dev zlib1g-dev
(linux) Use RubyInstaller to install rubygems as recommended at https://www.ruby-lang.org/en/downloads/
(Windows)sudo gem install bundler
gem install bundler
(Windows)bundle install
cd ..
./gradlew javadocAggregate
rm -rf site/target/javadocAggregate
rmdir site\target\javadocAggregate /S /Q
(Windows)mkdir site/target
mkdir site\target
(Windows)mv build/docs/javadocAggregate site/target
for /d %a in (build\docs\javadocAggregate*) do move %a site\target
(Windows)Before opening a pull request, you can preview your contributions by running from within the directory:
bundle exec jekyll serve
cd site
docker compose run build-site
cd site
docker compose run generate-javadoc
You can preview your work while working on the site.
cd site
docker compose run --service-ports dev
The web server will be started on http://localhost:4000
As you make changes to the site, the site will automatically rebuild.
Publishing the website is usually simple, you just need to copy the newly generated site content to the calcite-site repository.
But sometimes, especially when we upgraded Jekyll version, the js
and css
files may be renamed or removed, copying will not remove these stale files in calcite-site.
Hence, a safer way is to remove the old files in calcite-site for the first step, then do the copying.