Skip to content
Permalink
Browse files
CASSANDRA-16066: Add website generation tooling
This commit replaces the existing Docker website generation tool. The original
website generation tool was Jekyll. It has been replaced with Antora which
is purpose built for handling different document versions in a repository.

A Docker container has been added which renders the site using Antora. Unlike
other Antora configurations which have a site.yaml file committed, this
implementaiton uses a site.yaml template and python script to generate the
final site.yaml. The Docker container is responsible for calling the script
to generate the site.yaml file using the template. The generated file is then
passed to Antora to render the final site. This has been done so that different
document sources can be passed to Antora and newly released Cassandra versions
will automatically appear in the Downloads page.

The source content and styling which Antora uses to generate the site can be
controlled via the container environment variables.

The container includes a preview mode which monitors the content directories
and runs Antora when any file changes in the content directories.

By default, only the cassandra-website will be used as the source for Antora.
That is unless the Cassandra document generation is specified via the
generate-docs command, the container will only generate the website HTML.

patch by Anthony Grasso; reviewed by Mick Semb Wever, Lorina Poland, Melissa Logan, Paul Au for CASSANDRA-16066
  • Loading branch information
ossarga authored and michaelsembwever committed Sep 2, 2021
1 parent e833a5d commit 56a532993af73f1f5ddf548cfd3da48831473d50
Showing 9 changed files with 773 additions and 131 deletions.
@@ -1,6 +1,9 @@
.DS_Store
/.idea/

.env*

/site-content/site.yaml
/site-content/build/

/site-ui/build/

This file was deleted.

116 README.md
@@ -1,8 +1,8 @@
Apache Cassandra website
========================
# Apache Cassandra website

Development Cycle
-----------------
TODO: Add notes about the repository structure

## Development Cycle

Making changes to the website content can be done using the following steps.

@@ -14,52 +14,87 @@ Making changes to the website content can be done using the following steps.
5. Merge `asf-staging` to `asf-site`.
6. View the rendered site on https://cassandra.apache.org/.

# Developer Quickstart

To test changes before committing, it is a requirement that you build the website locally. Building the Apache Cassandra website takes a number of steps. To make things easier we have provided a Docker container which can build the full website in two simple commands and have it ready to commit via git.
To test changes before committing, it is a requirement that you build the website locally. Building the Apache Cassandra website takes a number of steps. To make things easier we have provided a Docker container which can build the full website in a few simple commands and have it ready to commit via git.

Building Prerequisites
----------------------
## Building Prerequisites

To build and run the Docker container you will need `Docker` version 2.0.0.0 or greater. If you need a copy of the site code you will need `git` as well.


# WARNING: The content below is incorrect and needs to be updated.


Building the site
-----------------
## Building the Website

If you need a copy of the site code run this command:

```bash
$ git clone https://github.com/apache/cassandra-website.git
$ cd ./cassandra-website
```

To build the website run the following commands from within the `./cassandra-website` directory (assuming you used the above clone command):

```bash
$ docker-compose build cassandra-website
$ docker-compose run cassandra-website
$ export BUILD_USER=build
$ docker-compose build website
$ docker-compose run website
```

:warning: *Tip:* In order to prevent root-owned modified files in your repository, the container user, `build`, is set up with a default UID=1000:GID=1000, which is usually the first user configured on a linux machine. If your local user is different you should set up the container user with your local host user's UID:GID, replace the above with:

:warning: *Tip:* Building cassandra-website may fail if the `CLOUDSDK_PYTHON` environment variable is not set on your machine. For example, set the environment variable to export `CLOUDSDK_PYTHON=/usr/bin/python2`.

```bash
$ docker-compose build --build-arg UID=$(id -u) --build-arg GID=$(id -g) cassandra-website
$ docker-compose run cassandra-website
$ export BUILD_USER=build
$ docker-compose build --build-arg UID_ARG=$(id -u) --build-arg GID_ARG=$(id -g) website
$ docker-compose run website
```

Go make yourself a cup of coffee, this will take a while...

Once building has completed, the site content will be in the `./cassandra-website/site-content/build` directory ready to be tested.

### Customising the Website Build for Development

#### You can use your own Cassandra fork

The container contains a local copy of the Apache Cassandra repository. The document generation process commits the generated AsciiDoc to the local repository. This is done to allow Antora to render to HTML the versioned documentation and website using the committed AsciiDoc in each branch.

If you have a Cassandra fork you would like to use instead, you can override the repository used when building the container:

```
$ export BUILD_USER=build
$ docker-compose build --build-arg CASSANDRA_REPOSITORY_URL_ARG=<git_url_to_your_fork> website
$ docker-compose run website
```

Note that you can specify multiple `--build-arg` options when calling `docker-compose build`. So if you wanted to use a different user ID, group ID and repository you could run the following command:

```
$ export BUILD_USER=build
$ docker-compose build \
--build-arg CASSANDRA_REPOSITORY_URL_ARG=<git_url_to_your_fork> \
--build-arg UID_ARG=$(id -u) \
--build-arg GID_ARG=$(id -g) \
website
$ docker-compose run website
```

In addition to customising the container build, you can customise the environment variables used inside the container. These can be used to influence Antora's rending of the site. For example, Antora will generate documentation for all Cassandra releases starting at 3.11.5. Hence, if you have a specific branch in your fork of Cassandra that you would like to render, you can override the variable the specifies the branches to render.

TODO: Explain that you need an env.dev file with variables in it and to run `docker-compose run website-dev`

Below is a select list of environment variables that can be overridden to control Antora's rendering of the site and why you would want to override them.

TODO: Add reason why you would override these
`CASSANDRA_REPOSITORY_URL`
`CASSANDRA_VERSIONS`
`CASSANDRA_WEBSITE_REPOSITORY_URL`
`CASSANDRA_WEBSITE_VERSIONS`
`UI_BUNDLE_ZIP_URL`

Previewing the site
-------------------


# WARNING: From here on is all wrong!!!!

### Previewing the Website Build

The fastest way to preview the site is to run the following:

@@ -106,3 +141,40 @@ Updating the main website, after verifying the staged website, involves copying
git switch asf-site
git reset --hard origin/asf-staging
git push -f origin asf-site


## Building the Site UI

### Executing Tasks

To get a list of the tasks that can be executed run the following commands:

```
$ export BUILD_USER=build
$ docker-compose build website-ui:
$ docker-compose run website-ui
```

A task can be executed using the following commands:

```bash
$ export BUILD_USER=build
$ docker-compose build website-ui:
$ docker-compose run website-ui <task>
```

### Building Bundle

TODO: Add info

### Releasing Bundle

TODO: Add info

### Preview UI

```bash
$ export BUILD_USER=build
$ docker-compose build website-ui-preview
$ docker-compose up website-ui-preview
```
@@ -0,0 +1,15 @@
version: "3.8"
services:
website-ui:
build: ./site-ui/
volumes:
- ./site-ui/:/home/site-ui

website-ui-preview:
build: ./site-ui/
ports:
- "5252:5252"
volumes:
- ./site-ui/:/home/site-ui
command:
- preview

This file was deleted.

0 comments on commit 56a5329

Please sign in to comment.