Development Setup

This page documents the local installations and repository settings needed to build, preview, and deploy the Just the Docs site.

Required Tools

  • Git
  • Ruby 3.3
  • Bundler
  • Jekyll, installed through the repository Gemfile
  • A C/C++ build toolchain for native Ruby gems
  • Optional: R, if you want to run scripts/simulate_ehr_data.R

Do not rely on a global Jekyll executable. This repository pins Jekyll and the Just the Docs theme through Bundler.

macOS Installation

Install Ruby 3.3 with Homebrew:

brew install ruby@3.3

Add Ruby 3.3 to your shell path:

export PATH="/opt/homebrew/opt/ruby@3.3/bin:$PATH"

Confirm the expected Ruby version:

ruby -v

Install the project dependencies from the repository root:

bundle install

Linux Installation

Install Ruby 3.3 and build tools using your system package manager or a Ruby version manager such as rbenv. Then install dependencies from the repository root:

bundle install

The GitHub Pages workflow uses ruby/setup-ruby with Ruby 3.3, so local Ruby 3.3 is the closest match to CI.

Conda And Miniforge Notes

If Conda or Miniforge sets compiler variables, native Ruby gem installation can fail. In that case, run Bundler or Jekyll with those variables unset:

env -u CC -u CXX -u LD -u LDFLAGS -u CPPFLAGS -u CFLAGS PATH=/opt/homebrew/opt/ruby@3.3/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin bundle install

Use the same pattern for builds:

env -u CC -u CXX -u LD -u LDFLAGS -u CPPFLAGS -u CFLAGS PATH=/opt/homebrew/opt/ruby@3.3/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin bundle exec jekyll build

Local Build

Build the static site:

bundle exec jekyll build

Preview the site locally:

bundle exec jekyll serve --host 127.0.0.1 --port 4000

With the configured base URL, the local preview is available at:

http://127.0.0.1:4000/practical-genai-coding-guide/

GitHub Pages Deployment

The repository is configured to deploy from GitHub Actions through .github/workflows/pages.yml.

The workflow:

  • Checks out the repository.
  • Uses Ruby 3.3.
  • Installs gems through Bundler cache.
  • Builds the site with bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}".
  • Uploads the generated site artifact.
  • Deploys to GitHub Pages.

Repository settings must use GitHub Actions as the Pages source:

  1. Open the repository on GitHub.
  2. Go to Settings > Pages.
  3. Set Build and deployment > Source to GitHub Actions.
  4. Push to main or run the Pages workflow manually.

Expected public URL:

https://FritscheLab.github.io/practical-genai-coding-guide/

Optional R Setup

The documentation site does not require R. R is only needed to run the synthetic EHR data script.

Install R and the script dependencies before running:

Rscript scripts/simulate_ehr_data.R --help

If the script reports missing R packages, install the reported packages in your preferred R environment.

Troubleshooting

  • jekyll: command not found: run Jekyll through Bundler with bundle exec jekyll build.
  • Ruby version mismatch: confirm that ruby -v reports Ruby 3.3 and that your shell path points to the intended Ruby.
  • Native gem compilation failures: unset Conda or Miniforge compiler variables as shown above.
  • Site builds but links look wrong locally: use the configured base URL path, /practical-genai-coding-guide/.
  • GitHub Pages does not deploy: confirm the Pages source is set to GitHub Actions and inspect the Deploy Jekyll site to Pages workflow logs.