Updating the Website

As part of the release process we generate and publish the website. An (intentional) side-effect of this process is to create a branch for the release (that is, 2.0.1). This branch can then be used for documentation updates.

Update docs

Prereqs:

jdk 11
mvn 3.x
groovy 3.x
pandoc 2.x
dos2unix

In the regular causeway repo:

Check out the branch:
```
git checkout 2.0.1
```
make documentation updates, and commit changes

make sure the tooling is built:

#TODO this is outdated info
mvn -D module-tooling -D skip.essential install -DskipTests

generate the website:
```
sh preview.sh
```
This now runs updates the config properties automatically (unless suppressed by a flag)

mvn clean install -pl core/config

This updated website is written to antora/target/site; we’ll use the results in the next section.

Publish website

We now copy the results of the Antora website generation over to the causeway-site repo:

in the causeway-site repo, check out the asf-site branch:

cd ../causeway-site

git checkout asf-site
git pull --ff-only

still in the causeway-site repo, run the copyover.sh script:

sh copyover.sh

This deletes all the files in content/ except for the schema and versions directories, and copies the generated Antora site to causeway-site repo’s contents directory:

#!/usr/bin/env bash
pushd content
for a in $(ls -1 | grep -v schema | grep -v versions)
do
    rm -rf $a
done
popd

pushd ../causeway
cp -Rf antora/target/site/* ../causeway-site/content/.
popd

git add .

Commit the changes and preview:

git commit -m "updates website"

sh preview.sh

If everything looks ok, then push the changes to make live, and switch back to the causeway repo:
```
git push origin asf-site
```

Update the Algolia search index

We use Algolia to build our search index.

If required, create a algolia.env file holding the APP_ID and the admin API_KEY, in the root of causeway-site:
algolia.env
```
APPLICATION_ID=...
API_KEY=...
```
This file should not be checked into the repo, because the API_KEY allows the index to be modified or deleted.
If required, update the algolia-config.json file

For example, update the stop_urls property with any paths that should not be crawled.
Use the Algolia-provided docker image to crawl the web pages and create the search index:
```
pushd content
docker run -it --env-file=../algolia.env -e "CONFIG=$(cat ../algolia-config.json | jq -r tostring)" algolia/docsearch-scraper:v1.16.0
popd
```
This posts the index up to the Algolia site.

Further documentation on the crawler can be found link:as per here; additional config options for the crawler can be found here.