Dev guide: Website Deployment

This page documents how the JGraphT website gets deployed.

Website Source

The sources for the website are checked into the main JGraphT repository under the docs directory

These include:

• Gemfile and _config.yml for Jekyll Github Pages setup
• Markdown/HTML/CSS/JS/images for main page
• mathjax configuration Javascript (support for math formulas in Javadoc)
• guide: static resources for user guide
• guide-templates: template Markdown for user guide, with links to code examples

Website Target

We use the Github Pages Deployment action to update the website automatically after every successful commit on the master branch. The deployment target is the gh-pages branch, from which the site is served via Jekyll.

Note that site/doc updates should never be made directly on the gh-pages branch, since such changes will be overwritten and lost during the next automatic deployment.

Markdown Expansion

During deployment, we expand the Markdown files in the guide-templates directory using hercule for transclusion. As an example, this source template gets expanded to this final markdown. The example code gets extracted from the latest Java source code

Expanded markdown get written into the guide directory. We don't add any markdown source files directly under the guide directory; only static resources (e.g. images). Instead, all markdown files are added under guide-templates. making it easier to cross-link between generated and non-generated markdown.

When editing example Java code, be careful not to disturb the comments used for controlling extraction. And read the referencing templates to make sure that your changes will not lead to inconsistencies with the surrounding text.

Javadoc

During deployment, we also publish a number of javadoc directories:

• javadoc: latest release Javadoc
• javadoc-SNAPSHOT latest Javadoc for master branch corresponding to SNAPSHOT build
• javadoc-x.y.z: one for each version starting from 1.0.0 (including latest release)

The released Javadoc is obtained from the jgrapht-javadoc repository. When we make a release, we check in two copies of the javadoc for the new version: once in a new javadoc-x.y.z directory, and once overwriting the existing javadoc directory. Then we force a build on the master repository to republish the website.

The SNAPSHOT javadoc is built automatically as part of each deployment.

HTTPS

HTTPS is enabled for the entire site. Old HTTP links will automatically redirect to the corresponding HTTPS link.

Local Testing

When editing the website, you can test your changes via local deployment as follows.

Prerequisites:

• sed
• ruby
• nodejs

Install utilities:

gem install bundler
npm install -g hercule

Build JGraphT including SNAPSHOT Javadoc:

mvn clean install javadoc:aggregate

Expand markdown and javadoc:

export GITHUB_WORKSPACE=/path/to/your/clone/of/jgrapht
cd ${GITHUB_WORKSPACE}
etc/expandMarkdown.sh
etc/downloadJavadoc.sh
mv target/site/apidocs docs/javadoc-SNAPSHOT

Run:

cd ${GITHUB_WORKSPACE}/docs
bundle exec jekyll serve

Now you can browse your locally published site at http://localhost:4000

Note that if you have added or edited example code as part of your changes, your edits will not show up, since the example code is read from the master branch of the jgrapht/jgrapht github repository by default. (For new example code files, this will cause an error from expandMarkdown.sh due to the file not being found.) To address this, pass a parameter to expandMarkdown.sh like this:

etc/expandMarkdown.sh your-github-user-id/jgrapht/your-branch-name

This assumes you have already pushed your changes to your-branch-name up to github.