Development

Set up a source checkout

git clone https://github.com/noxdea/okab.git
cd okab
bundle install
bundle exec rake

The default Rake task runs RSpec. Development dependencies include the optional Zaniah integration; requiring okab at runtime does not load Zaniah. CI runs across Linux, macOS, and Windows with the Ruby versions declared in the CI workflow.

Validate PDF output and signatures

Install Poppler for pdftotext, pdffonts, and pdftoppm, and qpdf for structural validation. Tests using those tools skip when they are unavailable. To exercise TrueType embedding and Japanese extraction, supply a font with Japanese glyphs:

OKAB_TEST_FONT=/path/to/japanese-font.ttf bundle exec rake

Validate RBS signatures against the installed Alhena signatures:

bundle exec rbs -I sig -I "$(bundle info --path alhena)/sig" validate

Run only the optional bridge tests with:

bundle exec rspec spec/zaniah_vector_spec.rb

Those tests compare rasterized output when pdftoppm is installed and verify searchable glyph runs when pdftotext is installed.

Rebuild the sample report

The README and website show a real PDF generated by examples/report.rb. The example accepts a font path and an optional output path. From the repository root, use the bundled Source Sans 3 fixture to regenerate the published assets:

bundle exec ruby examples/report.rb spec/fixtures/SourceSans3-Regular.otf docs/media/report.pdf
pdftoppm -singlefile -scale-to-x 595 -scale-to-y 842 -png docs/media/report.pdf docs/media/report
qpdf --check docs/media/report.pdf
pdftotext docs/media/report.pdf -

The font is licensed under the SIL Open Font License. The chart uses illustrative data. Update the PDF and its PNG preview together after changing the example.

Preview the website

The landing page uses plain HTML and CSS. User guide pages are Markdown, rendered by GitHub Pages’ Jekyll build with a shared layout. No site dependency is added to the gem’s runtime or development bundle.

With Docker installed, run the same build image as the Pages workflow from the repository root:

docker run --rm --platform linux/amd64 \
  -v "$PWD:/github/workspace" \
  -e GITHUB_WORKSPACE=/github/workspace \
  -e GITHUB_REPOSITORY=noxdea/okab \
  -e INPUT_SOURCE=. -e INPUT_DESTINATION=_site \
  ghcr.io/actions/jekyll-build-pages:v1.0.13

Serve the built site so its /okab base path matches production:

mkdir -p tmp/preview
ln -sfn ../../_site tmp/preview/okab
ruby -run -e httpd tmp/preview -p 4000

Open http://localhost:4000/okab/ and http://localhost:4000/okab/docs/. The preview server uses Ruby’s WEBrick gem, which can be installed separately with gem install webrick if needed. Generated site and preview files are ignored by Git.

Edit and publish documentation

Edit index.html for the landing page, styles.css for shared styling, and docs/*.md for the guide. Each guide page has a title and description in YAML front matter. _config.yml defines the navigation; _layouts/guide.html defines its shared HTML. Use relative Markdown links to other guide sources; GitHub Pages converts them to their published HTML paths.

The Pages workflow builds documentation changes on pull requests and deploys changes on main. In repository Settings → Pages → Build and deployment, select GitHub Actions as the source to use this workflow. The canonical website is https://noxdea.github.io/okab/ and the guide starts at /okab/docs/.

Contribute

Open an issue or pull request on GitHub. Include a small reproduction for bugs and run the relevant checks before submitting a code change. For documentation changes, preview the page and verify its examples against the current API.