Skip to content

docs: modernize README and website - #337

Merged
trans merged 1 commit into
mainfrom
docs/modernize-readme-site
Sep 27, 2026
Merged

trans merged 1 commit into
mainfrom
docs/modernize-readme-site

Conversation

@trans

@trans trans commented Sep 27, 2026

Copy link
Copy Markdown
Member

Summary

  • Refresh the README and GitHub Pages site with a responsive design and cherry identity.
  • Replace 2.9-era installation and API links with 3.2.2 guidance, recent release notes, and clearly labeled historical posts.
  • Add a dependency-free Ruby site builder and document how to update generated pages.
  • Distinguish published 3.2.2 behavior from changes already merged to main but still unreleased, including lib/rails.

Checks

  • ruby docs/build.rb
  • Ruby smoke checks for the README and guide examples on current main
  • Local HTML link audit and desktop/mobile browser rendering (no overflow or page errors)
  • git diff --check

@trans trans left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the README, docs/build.rb, the _src templates, the generated pages and atom.xml. It reads well, and the facts check out. One real issue and a couple of small ones.

What I verified

  • README examples: all run on current main and produce what the README shows: to_ranges → [1..3, 6..7], snakecase → "ruby_facets", average → 2.0, and require 'facets/ostruct' loads OpenStruct with the extensions.
  • Guide examples: dashcase → "ruby-facets", Range.intersection(1..10, 5..15) → 5..10, and facets/time/stamp loads.
  • Release facts on the site and feed match HISTORY.md: 3.2.2 on 2026-06-15, 3.2.1 on 2026-06-14 (load fix, OpenDSL, PIC), and 3.2.0 on 2026-04-01 (Ruby 3.1+, to_ranges, dashcase).
  • The builder reproduces the committed HTML exactly: rerunning it leaves no diff.
  • No broken local links in any generated page. atom.xml parses, and its news.html#facets-3-2-x anchors all exist.

Issue: docs/build.rb crashes outside a UTF-8 locale

On a system without a UTF-8 locale (plain C/POSIX, common in containers and minimal CI images) the build fails:

(erb):28: incompatible character encodings: ASCII-8BIT and US-ASCII (Encoding::CompatibilityError)

The templates contain non-ASCII characters (←, ·, ↗), and File.read uses the locale's default encoding. With LANG=C.UTF-8 it works. A one-line fix near the top:

Encoding.default_external = Encoding::UTF_8

Alternatively, pass encoding: 'UTF-8' to the File.read calls.

Smaller points

  • Orphaned archive post: posts/2008-03-24-release-2-4.html is built (it's in the archive hash), but nothing links to it. news.html lists the other five archive posts and skips 2.4.
  • Start year (FYI): the README and site say Facets began in 2005, which matches LICENSE.txt and the 1.0.0 entry (2005-12-04). The old .index metadata recorded a creation date of 2004-12-16, so the pre-1.0 work may date to late 2004. Your call.
  • Optional: docs/README.md says the Brite-era files (.page, .post, brite.yml, assets/layouts/) are kept for reference. Since #335 removed the other leftover tooling files, these could go too, but keeping them is reasonable.

Generated by Claude Code

@trans
trans merged commit 134cc5c into main Sep 27, 2026
14 checks passed
trans pushed a commit that referenced this pull request Sep 27, 2026
Facets took its name in version 0.5.0 on 2004-12-23 (see
work/HISTORY-0.rdoc), and the old .index metadata recorded 2004-12-16;
1.0 followed in December 2005. The README, site and LICENSE said 2005.
They now say 2004.

The news page's archive section gains the short origin story from
work/HISTORY-0.rdoc: TomsLib (2002), Succ (2003), A.B.C. and Raspberry
(2004), then Ruby Facets (December 2004). The README and the contribute
page mention the 2002 roots in a phrase.

Also from the #337 review:
- docs/build.rb sets UTF-8 as the default external encoding, so it no
  longer crashes outside a UTF-8 locale.
- news.html links the 2.4 release post, which was built but not linked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2Njj4j1r9twkVcXsMySLW
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant