The website is build with Jekyll - a static site generator. The content is created and updated on branch jekyll, then the static pages are generated with Jekyll and stored in the branch master.

⚠️ Please do not update files directly in master. ⚠️

The documentation is automatically built and deployed to the marian-nmt website using GitHub Actions.

This covers:

• Generation of CLI version/help markdown pages
• Generation of API documentation (developer docs)
• Building of the Jekyll source
• Deployment to website

The CLI and API document content is determined by the pinned version of the marian-dev submodule.

This pipeline is triggered by pushes on the source branch jekyll, and, on success, the resulting site is pushed to the GitHub pages branch (master).

Caution! When new CLI documentation is produced, an automated commit is pushed onto the source branch (message: Update CLI options:).

For pull requests against the source branch, the resulting site is available as an artifact and should be reviewed before approval.

To review a downloaded jekyll artifact, you can serve it locally with, for example:

python3 -m http.server -d /path/to/downloaded/artifact/

For development and test purposes, you can also build the site locally.

If cloning the repository for the first time, download the remote branch:

git clone https://github.com/marian-nmt/marian-nmt.github.io
cd marian-nmt.github.io
git fetch origin jekyll
git checkout jekyll

To build the website locally you need to install ruby with gem bundler.

On Ubuntu you can run:

[sudo] apt-get install ruby-dev
[sudo] gem install bundler

Then, install gem dependencies:

make install

Finally, build the website (it will be generated in _site folder) and run a local development server:

make run

The website should be available at http://127.0.0.1:4000.

Documentation in this repository is built from the Jekyll source, with two exceptions:

1. The developer API documentation is built on the marian-nmt/marian-dev repository.
2. The CLI documentation is generated from the marian command, and is ran locally as described below.

Pages with command-line options for Marian tools have are generated using the provided Makefile:

make -B update-cmds
make -B update-datafile

The first command generates the version, and help output. The second generates a data file containing the version and commit of Marian used. This compiles Marian, so a GPU is required.

Put a logo image into assets/logos/ and update _data/logos.yml. Use a PNG image with transparent background.