Skip to content

Commit 9039532

Browse files
sonupreetamjpower432eddie-knight
authored
docs: add Gemara documentation site (#191)
* docs: add Gemara documentation site Introduces foundational documentation infrastructure for Gemara: - Jekyll-based documentation site (docs/) - GitHub Actions workflow for automated deployment - Makefile targets for local development - Dependabot bundler configuration Partially resolves #155 Signed-off-by: sonupreetam <[email protected]> * Apply suggestions from code review Co-authored-by: Jennifer Power <[email protected]> Co-authored-by: Eddie Knight <[email protected]> Signed-off-by: t_hat <[email protected]> --------- Signed-off-by: sonupreetam <[email protected]> Signed-off-by: t_hat <[email protected]> Co-authored-by: Jennifer Power <[email protected]> Co-authored-by: Eddie Knight <[email protected]>
1 parent 41e020d commit 9039532

38 files changed

+1469
-1
lines changed

‎.github/dependabot.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,16 @@ updates:
2727
update-types:
2828
- "minor"
2929
- "patch"
30+
- package-ecosystem: "bundler"
31+
directory: "/docs"
32+
schedule:
33+
interval: "weekly"
34+
commit-message:
35+
prefix: "chore(deps)"
36+
labels: ["ruby", "dependencies"]
37+
groups:
38+
dependencies:
39+
applies-to: version-updates
40+
update-types:
41+
- "minor"
42+
- "patch"

‎.github/workflows/jekyll-site.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Jekyll Site CI/CD
2+
3+
on:
4+
# Test on pull requests
5+
pull_request:
6+
paths:
7+
- 'docs/**'
8+
- 'schemas/**'
9+
- '.github/workflows/jekyll-site.yml'
10+
11+
# Deploy on pushes to main
12+
push:
13+
branches:
14+
- main
15+
paths:
16+
- 'docs/**'
17+
- 'schemas/**'
18+
- '.github/workflows/jekyll-site.yml'
19+
20+
# Allow manual workflow dispatch
21+
workflow_dispatch:
22+
23+
# Sets permissions of the GITHUB_TOKEN to minimum required
24+
permissions:
25+
contents: read
26+
pages: write
27+
id-token: write
28+
29+
# Allow only one concurrent deployment
30+
concurrency:
31+
group: ${{ github.event_name == 'push' && 'pages' || format('pr-{0}', github.event.pull_request.number) }}
32+
cancel-in-progress: false
33+
34+
jobs:
35+
# Build and test job
36+
build:
37+
runs-on: ubuntu-latest
38+
steps:
39+
- name: Checkout
40+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
41+
with:
42+
persist-credentials: false
43+
44+
- name: Setup Pages
45+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
46+
id: pages
47+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
48+
49+
- name: Build with Jekyll
50+
uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
51+
with:
52+
source: ./docs
53+
destination: ./docs/_site
54+
55+
- name: Test HTML
56+
run: |
57+
# Check that key pages were generated
58+
echo "Verifying generated pages..."
59+
test -f docs/_site/index.html || { echo "Error: Missing index.html"; exit 1; }
60+
echo "Success: All expected pages generated successfully"
61+
62+
- name: Upload artifact for GitHub Pages
63+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
64+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
65+
with:
66+
path: docs/_site
67+
68+
# Deployment job (only runs on push to main)
69+
deploy:
70+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
71+
environment:
72+
name: github-pages
73+
url: ${{ steps.deployment.outputs.page_url }}
74+
runs-on: ubuntu-latest
75+
needs: build
76+
steps:
77+
- name: Deploy to GitHub Pages
78+
id: deployment
79+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎Makefile‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,4 +71,52 @@ lintinsights:
7171
@rm schema.cue
7272
@echo " > Linting security-insights.yml complete."
7373

74-
PHONY: tidy test testcov lintcue cuegen dirtycheck lintinsights
74+
# Documentation site targets
75+
CONTAINER_CMD := $(shell command -v podman 2> /dev/null || command -v docker 2> /dev/null)
76+
VOLUME_FLAGS := $(shell [ "$$(uname -s)" = "Linux" ] && echo ":Z" || echo "")
77+
78+
check-container:
79+
@if [ -z "$(CONTAINER_CMD)" ]; then \
80+
echo "ERROR: Neither podman nor docker found."; \
81+
exit 1; \
82+
fi
83+
84+
serve: check-container
85+
@echo " > Starting Jekyll documentation site..."
86+
@echo " > Using container runtime: $(CONTAINER_CMD)"
87+
@$(CONTAINER_CMD) stop gemara-docs 2>/dev/null || true
88+
@$(CONTAINER_CMD) rm gemara-docs 2>/dev/null || true
89+
@echo " > Site will be available at: http://localhost:4000"
90+
@echo ""
91+
@$(CONTAINER_CMD) run --rm \
92+
--name gemara-docs \
93+
--volume="$$PWD/docs:/srv/jekyll$(VOLUME_FLAGS)" \
94+
--publish 4000:4000 \
95+
--publish 35729:35729 \
96+
docker.io/jekyll/jekyll:latest \
97+
jekyll serve --host 0.0.0.0 --livereload --force_polling
98+
99+
build: check-container
100+
@echo " > Building Jekyll documentation site..."
101+
@$(CONTAINER_CMD) run --rm \
102+
--volume="$$PWD/docs:/srv/jekyll$(VOLUME_FLAGS)" \
103+
docker.io/jekyll/jekyll:latest \
104+
jekyll build
105+
106+
clean: check-container
107+
@echo " > Cleaning generated files..."
108+
@rm -rf docs/_site docs/.jekyll-cache docs/.jekyll-metadata
109+
@echo " > Stopping and removing any running containers..."
110+
@$(CONTAINER_CMD) stop gemara-docs 2>/dev/null || true
111+
@$(CONTAINER_CMD) rm gemara-docs 2>/dev/null || true
112+
@echo " > Clean complete!"
113+
114+
stop: check-container
115+
@echo " > Stopping documentation server..."
116+
@$(CONTAINER_CMD) stop gemara-docs 2>/dev/null || true
117+
@$(CONTAINER_CMD) rm gemara-docs 2>/dev/null || true
118+
@echo " > Server stopped!"
119+
120+
restart: stop serve
121+
122+
.PHONY: tidy test testcov lintcue cuegen dirtycheck lintinsights serve build clean stop restart check-container

‎docs/Gemfile‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
source "https://rubygems.org"
2+
3+
# Specify minimum Ruby version
4+
ruby ">= 3.0.0"
5+
6+
# Jekyll version
7+
gem "jekyll", "~> 4.3.0"
8+
9+
# Theme
10+
gem "minima", "~> 2.5"
11+
12+
# Jekyll plugins
13+
group :jekyll_plugins do
14+
gem "jekyll-feed", "~> 0.12"
15+
gem "jekyll-seo-tag", "~> 2.8"
16+
gem "jekyll-remote-theme", "~> 0.4"
17+
end
18+
19+
# Platform-specific gems
20+
platforms :mingw, :x64_mingw, :mswin, :jruby do
21+
gem "tzinfo", ">= 1", "< 3"
22+
gem "tzinfo-data"
23+
end
24+
25+
# Performance-booster for watching directories on Windows
26+
gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
27+
28+
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds
29+
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

‎docs/Gemfile.lock‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
GEM
2+
remote: https://rubygems.org/
3+
specs:
4+
addressable (2.8.7)
5+
public_suffix (>= 2.0.2, < 7.0)
6+
colorator (1.1.0)
7+
concurrent-ruby (1.3.5)
8+
em-websocket (0.5.3)
9+
eventmachine (>= 0.12.9)
10+
http_parser.rb (~> 0)
11+
eventmachine (1.2.7)
12+
ffi (1.17.2)
13+
forwardable-extended (2.6.0)
14+
google-protobuf (3.23.4)
15+
http_parser.rb (0.8.0)
16+
i18n (1.14.7)
17+
concurrent-ruby (~> 1.0)
18+
jekyll (4.3.4)
19+
addressable (~> 2.4)
20+
colorator (~> 1.0)
21+
em-websocket (~> 0.5)
22+
i18n (~> 1.0)
23+
jekyll-sass-converter (>= 2.0, < 4.0)
24+
jekyll-watch (~> 2.0)
25+
kramdown (~> 2.3, >= 2.3.1)
26+
kramdown-parser-gfm (~> 1.0)
27+
liquid (~> 4.0)
28+
mercenary (>= 0.3.6, < 0.5)
29+
pathutil (~> 0.9)
30+
rouge (>= 3.0, < 5.0)
31+
safe_yaml (~> 1.0)
32+
terminal-table (>= 1.8, < 4.0)
33+
webrick (~> 1.7)
34+
jekyll-feed (0.17.0)
35+
jekyll (>= 3.7, < 5.0)
36+
jekyll-remote-theme (0.4.3)
37+
addressable (~> 2.0)
38+
jekyll (>= 3.5, < 5.0)
39+
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
40+
rubyzip (>= 1.3.0, < 3.0)
41+
jekyll-sass-converter (3.0.0)
42+
sass-embedded (~> 1.54)
43+
jekyll-seo-tag (2.8.0)
44+
jekyll (>= 3.8, < 5.0)
45+
jekyll-watch (2.2.1)
46+
listen (~> 3.0)
47+
kramdown (2.5.1)
48+
rexml (>= 3.3.9)
49+
kramdown-parser-gfm (1.1.0)
50+
kramdown (~> 2.0)
51+
liquid (4.0.4)
52+
listen (3.9.0)
53+
rb-fsevent (~> 0.10, >= 0.10.3)
54+
rb-inotify (~> 0.9, >= 0.9.10)
55+
mercenary (0.4.0)
56+
minima (2.5.1)
57+
jekyll (>= 3.5, < 5.0)
58+
jekyll-feed (~> 0.9)
59+
jekyll-seo-tag (~> 2.1)
60+
pathutil (0.16.2)
61+
forwardable-extended (~> 2.6)
62+
public_suffix (5.1.1)
63+
rake (13.3.1)
64+
rb-fsevent (0.11.2)
65+
rb-inotify (0.11.1)
66+
ffi (~> 1.0)
67+
rexml (3.4.4)
68+
rouge (3.30.0)
69+
rubyzip (2.4.1)
70+
safe_yaml (1.0.5)
71+
sass-embedded (1.58.3)
72+
google-protobuf (~> 3.21)
73+
rake (>= 10.0.0)
74+
terminal-table (3.0.2)
75+
unicode-display_width (>= 1.1.1, < 3)
76+
unicode-display_width (2.6.0)
77+
webrick (1.9.1)
78+
79+
PLATFORMS
80+
ruby
81+
82+
DEPENDENCIES
83+
http_parser.rb (~> 0.6.0)
84+
jekyll (~> 4.3.0)
85+
jekyll-feed (~> 0.12)
86+
jekyll-remote-theme (~> 0.4)
87+
jekyll-seo-tag (~> 2.8)
88+
minima (~> 2.5)
89+
tzinfo (>= 1, < 3)
90+
tzinfo-data
91+
wdm (~> 0.1)
92+
93+
RUBY VERSION
94+
ruby 3.1.1p18
95+
96+
BUNDLED WITH
97+
1.17.2

‎docs/_config.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Gemara Documentation Site Configuration
2+
3+
title: Gemara
4+
description: >-
5+
GRC Engineering Model for Automated Risk Assessment - A logical model to describe
6+
compliance activities, their interactions, and schemas for automated interoperability.
7+
8+
baseurl: ""
9+
url: ""
10+
11+
titles_from_headings:
12+
enabled: true
13+
strip_title: true
14+
15+
# Author/Project info (displayed in footer)
16+
author:
17+
name: Gemara Authors
18+
email: [email protected]
19+
20+
# Build settings
21+
theme: minima
22+
plugins:
23+
- jekyll-remote-theme
24+
- jekyll-feed
25+
- jekyll-seo-tag
26+
27+
# Navigation
28+
header_pages:
29+
- docs/index.md
30+
31+
# Exclude from processing
32+
exclude:
33+
- docs/Gemfile
34+
- docs/Gemfile.lock
35+
- docs/node_modules
36+
- docs/vendor/bundle/
37+
- docs/vendor/cache/
38+
- docs/vendor/gems/
39+
- docs/vendor/ruby/
40+
41+
# Collections for better organization
42+
collections:
43+
layers:
44+
output: true
45+
permalink: /:collection/:name/
46+
47+
# Defaults
48+
defaults:
49+
- scope:
50+
path: ""
51+
type: "pages"
52+
values:
53+
layout: "page"
54+
- scope:
55+
path: ""
56+
type: "layers"
57+
values:
58+
layout: "page"
59+
60+
# GitHub metadata
61+
repository: ossf/gemara
62+
github:
63+
is_project_page: true
64+
65+
# Set to `true` to show excerpts on the homepage.
66+
show_excerpts: false
67+
68+
# Social Media Links.
69+
# Renders icons via Font Awesome Free web fonts CDN, based on ordered list of
70+
# entries. Valid entry keys:
71+
# * title Tooltip rendered on hovering over icon.
72+
# * icon Font Awesome icon id. `github` corresponds to `fa-github`.
73+
# * url Full URL of social profile.
74+
social_links:
75+
- icon: github
76+
url: "https://github.com/ossf"
77+
- icon: x-twitter
78+
url: "https://x.com/openssf"
79+
- icon: bluesky
80+
url: "https://bsky.app/profile/openssf.org"
81+
- icon: linkedin
82+
url: "https://www.linkedin.com/company/openssf/"
83+
84+
# Markdown settings
85+
markdown: kramdown
86+
kramdown:
87+
input: GFM
88+
syntax_highlighter: rouge
89+
toc_levels: "2"

0 commit comments

Comments
 (0)