src/README

Apache Cassandra website sources
================================

Prerequisite
------------

The site depends on Jekyll (https://jekyllrb.com/) which should be installed.

Please use Jekyll 3.4.x for compiling the html pages, so we get identical results for everyone.

You may need to add the ruby executable that ends up being installed to your firewall on MacOS otherwise
the web server started by 'make serve' will be unreachable.

Installing Jekyll independently from the version shipped with your OS can be done as follows:

# Use rbenv to use a specific Ruby version with Jekyll:
# See: https://github.com/rbenv/rbenv/#installation
git clone -b v1.1.1 https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$HOME/.rbenv/shims:$HOME/.rbenv/versions/2.4.2/bin:$PATH"' >> ~/.zshrc # change to bashrc if needed
# Install ruby-build plugin
mkdir ~/.rbenv/plugins
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

# Install ruby
# See: https://github.com/rbenv/rbenv/#installing-ruby-versions
rbenv install 2.4.2

# Associate with Cassandra svn directory
cd ~/svn/cassandra-site/src # change as needed
rbenv local 2.4.2
which rbenv # should point to shim
ruby --version

# Install bundler with local rbenv version
gem install bundler

# Install needed gems
bundle install

# Confirm things are working
jekyll --version


Updating the site
-----------------

Updates to the "core" website are done by simply:

1. editing whatever local files needs to be edited (see layout below too)
2. testing the change locally using `make serve`
3. building for real using: `make`
4. committing.

One exception is the documentation which is automatically built and imported from the Cassandra sources. If you need to
update the documentation, you need to:
1. checkout the proper branch (the one for which you want to build and import the doc) in your local checkout of the
   cassandra git sources
2. set the CASSANDRA_DIR environment variable to that git source checkout (pro-tip: it's a good idea to export that
   variable in your bashrc/zshrc/whatev).
3. use `make add-doc` (or `make add-latest-doc` or `add-stable-doc`) from this repository. 
   The `add-stable-doc` target should be used when you want the generated doc replace the "default" documentation, 
   the one you get when you click "documentation" on the website.  Use `add-latest-doc` for trunk. 
   You should use `add-doc` when you want to rebuild the doc for an old version.

Layout
------

Outside of the documentation, the website is mostly only a few pages that are at top-level. The `index.html` file is the
landing page, and other pages are markdown processed by Jekyll (the index page isn't markdown because it's layout is
slightly more fancy).

Further, the `_data/` directory contains "data" used by the pages. Mainly, the `_data/releases.yaml` file contains the
versions and release dates of the currently released version. It's the file to edit when a new release is published.

The documentation is in the doc/ directory. It mostly contains sub-directories for each version for which we have a doc,
and those sub-directories are automatically imported by `make add-doc`/`make add-lastest-doc` (so don't edit any file
withing those version sub-directories). The doc/ directory also contains a `lastest` symlink pointing to the last
version, the one the website documentation actually points to (that symlink is automatically updated when you use `make
add-latest-doc`), as well as a few "static" files used by the doc (as of this writing, only links to legacy CQL doc).

The rest of the layout is standard to Jekyll:

* `_layout/` contains the page (full) layouts.
* `_includes/` contains fragments used by the different layouts (that's where the header, navigation and footer are).
* `css/`, `js/` and `img/` are what ones would expect (they are included as-is by Jekyll).
* `_sass/` is to `css/` what `_includes` is to `_layout`; it contains sass fragments imported by the main css files
  (currently only the pygments theme for syntax highligthing in the documentation).
* `_plugins/` contains a tiny plugin that make it easier to input download links in the `download.md` file.

How this work
-------------

Most of the site is a simple Jekyll installation and you should refer to the Jekyll documentation for detail. The site
however includes the in-tree Sphinx documentation and this section attemps to provide more detail on that "integration".

That doc integration is somewhat simplistic, which has both pros and cons. The pros is that there isn't really any
complex mechanism involved, the cons is that it's a bit of a hack. The in-tree doc uses Sphinx, which normally generates
complete (standalone) html files (from the textile source), while Jekyll generates it's pages from Liquid templates
(https://jekyllrb.com/docs/templates/). The intregation between the 2 works by having a special Sphinx theme (that theme
is in doc/source/_theme/cassandra_theme in the Cassandra git repository) which, instead of creating standalone html
files, creates liquid template (that reuse the elements of the website). Note that this means in particular that this
special theme is only ever useful for the website. In other words, the processus of integration of the doc in the
website is:
 1) the in-tree doc is compiled by sphinx using the special theme.
 2) the generated files, which thanks to the theme are Liquid templates (mainly, if you look at the theme files, they
    simply have a proper Jekyll yaml 'Front Matter'), are copied to the website doc.
 3) Jekyl is run normally. It then simply picks up the copied doc file and process them as any normal file.

And there is just a bit of automation to make that process easier:
 - the in-tree sphinx doc Makefile has a 'website' target that simply trigger the use of the special website Sphinx
   theme.
 - the website Makefile has the 'add-doc' and 'add-latest-doc' targets mentioned above to automate the generation and
   copy of the doc files.

And that's mostly what there is to it. I'll note however the following technical gotchas:
 - once copied and processed by Jekyll, the doc files uses the website html header and navigation. Sphinx has a bunch of
   custom css class that can be styled, as well as a few js files, and those are in the website css/ and js/
   directories. In particular, most doc specific styling is in the css/sphinx.css (some of it have been simply copied
   for the css of the default sphinx theme), and the sphinx js files have been manually copied into js/. Those aren't
   updated by the integration process described above, and in particular, the sphinx generation puts a bunch of css/js
   files in a _static/ directory of the generated files (see src/doc/latest/_static for instance) and those are
   completely ignored (they are not even copied by Jekyll due to my next point).
 - sphinx uses underscores at the start of some of the directories that have special meaning, like the _images directory
   where it puts images, but Jekyll have the same convention for its own special directories and won't (by default) copy
   any such directory when generated its result. In practice, this means we have to force manually force the inclusion
   of those sphinx directories we want to include so Jekyll doesn't skip them, which is done in the _config.yml Jekyll
   configuration file (the only sphinx dir we care about so far is _images).

Contributing a Blog Post
------------------------
To contribute a new blog post, create a new Markdown file in /_posts, using
_templates/2018-06-22-blog_post_template.markdown as a template. Follow the YYYY-MM-DD-blog-post-slug.markdown filename
convention, and annotate your post using the yaml frontmatter of the Markdown file (this functionality is provided by
Jekyll).

Follow the instructions above during development -- `make serve` for local development, and `make` to generate the final
product.