Google Git
Sign in
apache / calcite / refs/heads/stage / . / site
tree: 62c6249e36c91363528c982d2a80caba47a460b9 [path history] [tgz]
  1. _data/
  2. _docs/
  3. _includes/
  4. _layouts/
  5. _plugins/
  6. _posts/
  7. _sass/
  8. community/
  9. css/
  10. develop/
  11. downloads/
  12. fonts/
  13. img/
  14. news/
  15. .asf.yaml
  16. .gitignore
  17. .htaccess
  18. _config.yml
  19. doap_calcite.rdf
  20. docker-compose.yml
  21. favicon.ico
  22. Gemfile
  23. Gemfile.lock
  24. index.html
  25. README.md
site/README.md

Apache Calcite docs site

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.

Previewing the website locally

Manually

Setup your environment

Site generation currently works best with ruby-2.7.4.

  1. cd site
  2. git clone https://gitbox.apache.org/repos/asf/calcite-site.git target
  3. 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)
  4. sudo gem install bundler gem install bundler (Windows)
  5. bundle install

Add javadoc

  1. cd ..
  2. ./gradlew javadocAggregate
  3. rm -rf site/target/javadocAggregate rmdir site\target\javadocAggregate /S /Q (Windows)
  4. mkdir site/target mkdir site\target (Windows)
  5. mv build/docs/javadocAggregate site/target for /d %a in (build\docs\javadocAggregate*) do move %a site\target (Windows)

Running locally

Before opening a pull request, you can preview your contributions by running from within the directory:

  1. bundle exec jekyll serve
  2. Open http://localhost:4000

Using docker

Setup your environment

  1. Install docker
  2. Install docker compose v2

Build site

  1. cd site
  2. docker compose run build-site

Generate javadoc

  1. cd site
  2. docker compose run generate-javadoc

Running development mode locally

You can preview your work while working on the site.

  1. cd site
  2. 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

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.