| 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. |