chore: initialize documentation structure with Scribble and GitHub Pages setup

robertDurst · robertDurst · commit 1292c9c329ca · 2025-09-07T09:17:50.000-05:00
diff --git a/.github/workflows/scribble.yml b/.github/workflows/scribble.yml
@@ -0,0 +1,55 @@
+name: Build and Deploy Scribble Documentation
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Racket
+        uses: Bogdanp/setup-racket@v1
+        with:
+          version: '8.17'
+
+      - name: Install Scribble
+        run: raco pkg install scribble
+
+      - name: Build Documentation
+        run: |
+          cd docs
+          raco scribble --htmls --dest ../_site main.scrbl
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+_site/
+.jekyll-cache/
+.DS_Store
+*.log
diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+brickellresearch.org
diff --git a/Dockerfile b/Dockerfile
diff --git a/README.md b/README.md
@@ -0,0 +1,14 @@
+# Brickell Research Documentation
+
+This repository contains documentation built with Racket's Scribble and deployed to GitHub Pages.
+
+## Local Development
+
+1. Install Racket (version 8.12 or later)
+2. Install Scribble: `raco pkg install scribble`
+3. Build the documentation: `cd docs && raco scribble --htmls main.scrbl`
+4. Open the generated HTML files in your browser
+
+## Deployment
+
+The documentation is automatically built and deployed to GitHub Pages when changes are pushed to the main branch.
diff --git a/docs/about.scrbl b/docs/about.scrbl
@@ -0,0 +1,7 @@
+#lang scribble/base
+
+@(require "common.scrbl")
+
+@title{About}
+
+@elem[#:style miami-cyan]{Brickell Research is an independent research lab focused on exploring interesting ideas in the field of programming languages and compilers with a special focus on the Ruby and Racket programming languages.}
diff --git a/docs/brickell_research_logo.png b/docs/brickell_research_logo.png
diff --git a/docs/common.scrbl b/docs/common.scrbl
@@ -0,0 +1,11 @@
+#lang scribble/base
+
+@(require scribble/core scribble/html-properties)
+@(provide miami-pink miami-cyan miami-cyan-italic logo-style title-with-css footer-style)
+
+@(define miami-pink (make-style #f (list (attributes (list (cons 'style "color: #FF1493;"))))))
+@(define miami-cyan (make-style #f (list (attributes (list (cons 'style "color: #00CED1;"))))))
+@(define miami-cyan-italic (make-style #f (list (attributes (list (cons 'style "color: #00CED1; font-style: italic;"))))))
+@(define logo-style (make-style #f (list (attributes (list (cons 'style "float: right; margin: 10px;"))))))
+@(define title-with-css (make-style #f (list (attributes (list (cons 'style "color: #FF1493;"))) (make-css-addition "miami.css"))))
+@(define footer-style (make-style #f (list (alt-tag "footer") (attributes (list (cons 'style "text-align: center; margin-top: 2rem; color: #00CED1; font-style: italic;"))))))
diff --git a/docs/logo.svg b/docs/logo.svg
@@ -0,0 +1,4 @@
+<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
+  <rect width="200" height="200" fill="#1e3a8a"/>
+  <text x="100" y="110" font-family="Arial, sans-serif" font-size="48" font-weight="bold" text-anchor="middle" fill="white">BR</text>
+</svg>
diff --git a/docs/main.html b/docs/main.html
@@ -0,0 +1,2 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html style="color: #FF1493;"><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>Brickell Research</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="miami.css" title="default"/><link rel="stylesheet" type="text/css" href="scribble-style.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,&quot;tocview_0&quot;);">&#9658;</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">Brickell Research</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1&nbsp;</td><td><a href="#%28part._.About%29" class="tocviewlink" data-pltdoc="x">About</a></td></tr><tr><td align="right">2&nbsp;</td><td><a href="#%28part._.Projects%29" class="tocviewlink" data-pltdoc="x">Projects</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._.Brickell_.Research%29" class="tocsubseclink" data-pltdoc="x">Brickell Research</a></td></tr><tr><td><span class="tocsublinknumber">1<tt>&nbsp;</tt></span><a href="#%28part._.About%29" class="tocsubseclink" data-pltdoc="x">About</a></td></tr><tr><td><span class="tocsublinknumber">2<tt>&nbsp;</tt></span><a href="#%28part._.Projects%29" class="tocsubseclink" data-pltdoc="x">Projects</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><h2 class="heading" style="color: #FF1493;"><a name="(part._.Brickell_.Research)"></a>Brickell Research<span class="button-group"><a href="#(part._.Brickell_.Research)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h2><p><img src="brickell_research_logo.png" alt="" width="256" height="256" style="float: right; margin: 10px;"/></p><blockquote class="SCentered"><p><span class="Smaller"><span style="color: #00CED1; font-style: italic;">Website powered by Racket&rsquo;s Scribble documentation system.</span></span></p></blockquote><h3 class="heading">1<tt>&nbsp;</tt><a name="(part._.About)"></a>About<span class="button-group"><a href="#(part._.About)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h3><p><span style="color: #00CED1;">Brickell Research is an independent research lab focused on exploring interesting ideas in the field of programming languages and compilers with a special focus on the Ruby and Racket programming languages.</span></p><h3 class="heading">2<tt>&nbsp;</tt><a name="(part._.Projects)"></a>Projects<span class="button-group"><a href="#(part._.Projects)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h3><p><span style="color: #00CED1;">We are currently working on the following projects:</span></p><ul><li><p><a href="https://rubybib.brickellresearch.org/">a fork of rubybib.</a>: A bibliography for academic papers about the Ruby programming language.</p></li><li><p><a href="https://pkgs.racket-lang.org/package/XDR">XDR</a>: a Racket package for encoding and decoding XDR data.</p></li></ul></div></div><div id="contextindicator">&nbsp;</div></body></html>
diff --git a/docs/main.scrbl b/docs/main.scrbl
@@ -0,0 +1,14 @@
+#lang scribble/base
+
+@(require scribble/core scribble/html-properties "common.scrbl")
+
+
+@image["brickell_research_logo.png" #:scale 0.25 #:style logo-style]
+
+@title[#:style title-with-css]{Brickell Research}
+
+@include-section["about.scrbl"]
+
+@include-section["projects.scrbl"]
+
+@centered{@smaller{@elem[#:style miami-cyan-italic]{Website powered by Racket's Scribble documentation system.}}}
diff --git a/docs/miami.css b/docs/miami.css
@@ -0,0 +1,10 @@
+body { background-color: #000000; color: #E0FFFF; }
+a { color: #00CED1; }
+.maincolumn { background: transparent; }
+.main { background: transparent; }
+.tocview { background: rgba(255,255,255,0.08); }
+h1, h2, h3, h4, h5, h6 { color: #FF1493; }
+/* Pull content up slightly to sit closer to the top */
+.maincolumn { margin-top: 10px; } 
+.tocsub { color: #FF1493; background-color: #000000; }
+.tocviewlisttopspace { display: none; }
diff --git a/docs/projects.scrbl b/docs/projects.scrbl
@@ -0,0 +1,12 @@
+#lang scribble/base
+
+@(require "common.scrbl")
+
+@title{Projects}
+
+@elem[#:style miami-cyan]{We are currently working on the following projects:}
+
+@itemlist[
+ @item{@hyperlink["https://rubybib.brickellresearch.org/"]{a fork of rubybib.}: A bibliography for academic papers about the Ruby programming language.}
+ @item{@hyperlink["https://pkgs.racket-lang.org/package/XDR"]{XDR}: a Racket package for encoding and decoding XDR data.}
+ ]
diff --git a/docs/scribble-common.js b/docs/scribble-common.js
@@ -0,0 +1,172 @@
+// Common functionality for PLT documentation pages
+
+// Page Parameters ------------------------------------------------------------
+
+function GetURL() {
+  return new URL(location);
+}
+
+function GetPageArgs() {
+  return GetURL().searchParams;
+}
+
+function GetPageQueryString() {
+  return GetPageArgs().toString();
+}
+
+function GetPageArg(key, def) {
+  return GetPageArgs().get(key) || def;
+}
+
+function MergePageArgsIntoLink(a) {
+  if (GetPageArgs().size === 0 || !a.dataset.pltdoc) return;
+  a.href = MergePageArgsIntoUrl(a.href);
+}
+
+function MergePageArgsIntoUrl(href) {
+  const url = new URL(href, window.location.href);
+  for (const [key, val] of GetPageArgs()) {
+    if (url.searchParams.has(key)) continue;
+    url.searchParams.append(key, val)
+  }
+  return url.href;
+}
+
+// Cookies --------------------------------------------------------------------
+
+// Actually, try localStorage (a la HTML 5), first.
+
+function GetCookie(key, def) {
+  try {
+    var v = localStorage[key];
+    if (!v) v = def;
+    return v;
+  } catch (e) {
+    var i, cookiestrs;
+    try {
+      if (document.cookie.length <= 0) return def;
+      cookiestrs = document.cookie.split(/; */);
+    } catch (e) { return def; }
+    for (i = 0; i < cookiestrs.length; i++) {
+      var cur = cookiestrs[i];
+      var eql = cur.indexOf('=');
+      if (eql >= 0 && cur.substring(0,eql) == key)
+        return unescape(cur.substring(eql+1));
+    }
+    return def;
+  }
+}
+
+function SetCookie(key, val) {
+  try {
+    localStorage[key] = val;
+  } catch(e) {
+    var d = new Date();
+    d.setTime(d.getTime()+(365*24*60*60*1000));
+    try {
+      document.cookie =
+        key + "=" + escape(val) + "; expires="+ d.toGMTString() + "; path=/";
+    } catch (e) {}
+  }
+}
+
+// note that this always stores a directory name, ending with a "/"
+function SetPLTRoot(ver, relative) {
+  var root = location.protocol + "//" + location.host
+           + NormalizePath(location.pathname.replace(/[^\/]*$/, relative));
+  SetCookie("PLT_Root."+ver, root);
+}
+
+// adding index.html works because of the above
+function GotoPLTRoot(ver, relative) {
+  var u = GetRootPath(ver);
+  if (u == null) return true; // no cookie: use plain up link
+  // the relative path is optional, default goes to the toplevel start page
+  if (!relative) relative = "index.html";
+  location = u + relative;
+  return false;
+}
+
+function GetRootPath(ver) {
+    var u = GetCookie("PLT_Root."+ver, null);
+    if (u != null)
+        return u;
+    // use root specified by local-redirect wrapper, if present
+    if (typeof user_doc_root != "undefined")
+        return user_doc_root;
+    return null;
+}
+
+// Utilities ------------------------------------------------------------------
+
+var normalize_rxs = [/\/\/+/g, /\/\.(\/|$)/, /\/[^\/]*\/\.\.(\/|$)/];
+function NormalizePath(path) {
+  var tmp, i;
+  for (i = 0; i < normalize_rxs.length; i++)
+    while ((tmp = path.replace(normalize_rxs[i], "/")) != path) path = tmp;
+  return path;
+}
+
+// `noscript' is problematic in some browsers (always renders as a
+// block), use this hack instead (does not always work!)
+// document.write("<style>mynoscript { display:none; }</style>");
+
+// Interactions ---------------------------------------------------------------
+
+function DoSearchKey(event, field, ver, top_path) {
+  var val = field.value;
+  if (event && event.key === 'Enter') {
+    var u = GetRootPath(ver);
+    if (u == null) u = top_path; // default: go to the top path
+    u += "search/index.html?q=" + encodeURIComponent(val);
+    u = MergePageArgsIntoUrl(u);
+    location = u;
+    return false;
+  }
+  return true;
+}
+
+function TocviewToggle(glyph, id) {
+  var s = document.getElementById(id).style;
+  var expand = s.display == "none";
+  s.display = expand ? "block" : "none";
+  glyph.innerHTML = expand ? "&#9660;" : "&#9658;";
+}
+
+function TocsetToggle() {
+  document.body.classList.toggle("tocsetoverlay");
+}
+
+// Page Init ------------------------------------------------------------------
+
+// Note: could make a function that inspects and uses window.onload to chain to
+// a previous one, but this file needs to be required first anyway, since it
+// contains utilities for all other files.
+var on_load_funcs = [];
+function AddOnLoad(fun) { on_load_funcs.push(fun); }
+window.onload = function() {
+  for (var i=0; i<on_load_funcs.length; i++) on_load_funcs[i]();
+};
+
+AddOnLoad(function(){
+    var links = document.getElementsByTagName("a");
+    for (var i=0; i<links.length; i++) MergePageArgsIntoLink(links[i]);
+    var label = GetPageArg("ctxtname",false);
+    if (!label) return;
+    var indicator = document.getElementById("contextindicator");
+    if (!indicator) return;
+    indicator.innerHTML = label;
+    indicator.style.display = "block";
+  });
+
+// Pressing "S" or "s" focuses on the "...search manuals..." text field
+AddOnLoad(function(){
+  window.addEventListener("keyup", function(e) {
+    if ((e.key === 's' || e.key === 'S') && e.target === document.body) {
+      var searchBox = document.getElementById('searchbox');
+      if (searchBox) {
+        searchBox.focus();
+      }
+    }
+  }, false);
+});
diff --git a/docs/scribble-style.css b/docs/scribble-style.css
diff --git a/docs/scribble.css b/docs/scribble.css
diff --git a/public/index.html b/public/index.html
diff --git a/server.rkt b/server.rkt

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +_site/
 +.jekyll-cache/
 +.DS_Store
 +*.log
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">`
	`2`	+<html style="color: #FF1493;"><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>Brickell Research</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="miami.css" title="default"/><link rel="stylesheet" type="text/css" href="scribble-style.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">Brickell Research</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="#%28part._.About%29" class="tocviewlink" data-pltdoc="x">About</a></td></tr><tr><td align="right">2 </td><td><a href="#%28part._.Projects%29" class="tocviewlink" data-pltdoc="x">Projects</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._.Brickell_.Research%29" class="tocsubseclink" data-pltdoc="x">Brickell Research</a></td></tr><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#%28part._.About%29" class="tocsubseclink" data-pltdoc="x">About</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#%28part._.Projects%29" class="tocsubseclink" data-pltdoc="x">Projects</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><h2 class="heading" style="color: #FF1493;"><a name="(part._.Brickell_.Research)"></a>Brickell Research<span class="button-group"><a href="#(part._.Brickell_.Research)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h2><p><img src="brickell_research_logo.png" alt="" width="256" height="256" style="float: right; margin: 10px;"/></p><blockquote class="SCentered"><p><span class="Smaller"><span style="color: #00CED1; font-style: italic;">Website powered by Racket’s Scribble documentation system.</span></span></p></blockquote><h3 class="heading">1<tt> </tt><a name="(part._.About)"></a>About<span class="button-group"><a href="#(part._.About)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h3><p><span style="color: #00CED1;">Brickell Research is an independent research lab focused on exploring interesting ideas in the field of programming languages and compilers with a special focus on the Ruby and Racket programming languages.</span></p><h3 class="heading">2<tt> </tt><a name="(part._.Projects)"></a>Projects<span class="button-group"><a href="#(part._.Projects)" class="heading-anchor" title="Link to here">🔗</a><span style="visibility: hidden"> </span></span></h3><p><span style="color: #00CED1;">We are currently working on the following projects:</span></p><ul><li><p><a href="https://rubybib.brickellresearch.org/">a fork of rubybib.</a>: A bibliography for academic papers about the Ruby programming language.</p></li><li><p><a href="https://pkgs.racket-lang.org/package/XDR">XDR</a>: a Racket package for encoding and decoding XDR data.</p></li></ul></div></div><div id="contextindicator"> </div></body></html>