Shomen

ARCHIVED — HISTORICAL ARTIFACT.

This repository is a consolidated historical archive of the Shomen documentation ecosystem from 2011–2015. The original work was spread across eight separate repositories, which have all been merged into this single tree for preservation. No further development is planned.

What Was Shomen?

Shomen was a pluggable Ruby documentation pipeline built around a single insight: separate parsing from rendering by standardizing an intermediate format. Instead of every documentation tool shipping both a parser and a renderer, Shomen defined a canonical JSON/YAML model of a project's API so that:

• Parsers had a single output target, regardless of the source tool.
• Viewers had a single input format, regardless of the source language tool that produced it.

  Ruby source
     │
     ├─ shomen-rdoc   (reads RDoc's .rdoc cache)
     ├─ rdoc-shomen   (RDoc formatter plugin)
     └─ shomen-yard   (YARD formatter plugin)
                      │
                      ▼
               doc.json  ←  the Shomen model (flat, no internal references,
                      │     YAML or JSON, defined by shomen-model)
                      ▼
     ┌─ hypervisor   (jQuery viewer, mouse-wheel scrolling menus)
     ├─ rebecca      (jQuery viewer, dropdown search ribbon)
     └─ rubyfaux     (jQuery viewer, "old-school Ruby style")
                      │
                      ▼
               shomen-server  (tiny Rack server for local viewing)

Pick a generator, pick a viewer theme, publish the JSON anywhere on the web. The viewers could even be pointed at a remote doc.json via a ?doc= URL parameter, so one hosted viewer could render anyone's documentation.

Repository Layout

Each subdirectory is the content of a formerly standalone repository:

Path	Original repo	Description
model/	rubyworks/shomen-model	The format specification and Ruby model API
generators/rdoc/	rubyworks/shomen-rdoc	Stand-alone tool reading RDoc's cache
generators/rdoc-plugin/	rubyworks/rdoc-shomen	RDoc formatter plugin (rdoc -f shomen)
generators/yard/	rubyworks/shomen-yard	YARD formatter plugin
viewers/hypervisor/	rubyworks/hypervisor	"The incredible Hypervisor" — jQuery theme
viewers/rebecca/	rubyworks/rebecca	"Lovely" — jQuery + dropdown search ribbon
viewers/rubyfaux/	rubyworks/rubyfaux	Old-school Ruby-style theme
server/	rubyworks/shomen-server	Minimal Rack static server

The individual repositories have been moved to rubyunworks and archived, preserving their original git history. This consolidated tree contains only the file snapshots, not the commit histories.

Why It Was Abandoned

A few forces combined to render Shomen unnecessary:

1. YARD won the Ruby docs war. RDoc moved to maintenance mode and YARD produced HTML that was good enough for most projects.
2. rubydoc.info already solved the hosted-docs problem centrally, with no per-project ceremony.
3. Nobody actually wanted theme pluggability. The "pick your doc theme" value proposition sounded nice in principle but there was no real user demand — the default was usually fine.
4. The viewer layer aged out. The three viewers were built on 2011-era jQuery plugins (jQote2, quicksearch, old highlight.js, jQuery Templates) which are now defunct. Reviving any of them effectively requires a rewrite.

What Still Holds Up

The core idea — a standardized, structured, language-agnostic intermediate documentation format — is arguably more relevant today than it was in 2011. The reason is LLMs and AI tooling.

When AI systems need to understand a library, they typically either scrape human-readable HTML documentation (fragile) or re-parse source code (expensive). A canonical JSON representation of "every class, module, method, and doc comment in this library" would let any AI tool ingest any library's documentation in a uniform way — the same egalitarian, machine-friendly, no-gatekeeping property that microformats tried to give the web.

Some things in the neighborhood today:

• LSP (Language Server Protocol) — cross-language, but editor-focused, server-based, and not aimed at producing standalone doc sites.
• Rustdoc JSON output (rustdoc --output-format json) — Rust-only but exactly the Shomen pattern: a structured intermediate format designed for downstream tool consumption.
• Doxygen XML — language-agnostic, predates this whole conversation, but old and awkward and not widely consumed by modern tooling.
• Ad-hoc AI-docs formats being built by projects like Context7 — reinventing the wheel per-tool because no standard exists.

The Multi-Language Version (Road Not Taken)

A Ruby-only documentation model is niche and duplicates YARD. The interesting version is a multi-language one: a single JSON schema that any language's doc generator could produce, and any viewer or AI tool could consume.

The historical objection was that writing parsers for N languages is prohibitively expensive. In 2025 that objection is much weaker: LLMs can bootstrap reasonable parsers for a dozen mainstream languages quickly, and once the schema is stable, language communities could ship their own generators as part of their standard doc tooling. GitHub could even produce these automatically on opt-in, the way it already renders READMEs and runs security scans.

There is still no real standard in this space. If someone ever wants to build one, the Shomen model is a reasonable starting point for thinking about the schema.

Copyrights

Copyright (c) 2010–2015 Rubyworks

Distributed under the terms of the BSD-2-Clause license. See LICENSE.txt for details. Individual subprojects retain their own LICENSE / COPYING files where applicable.