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.

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.

Each subdirectory is the content of a formerly standalone repository:

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.

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.

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.

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.

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.