RUDE: RUby Documentation Effort

[zverok]

Project

The idea is pretty rough yet clean: parse docs from Ruby's official Repo (and from all tags, starting from 2.0) and format it in one informative static site (published with GitHub pages), auto-updated on new versions. Proposed differences from existing projects (say, ruby-doc.org):

• Ruby-version agnostic URLs (instead of having .../2.4.2/Enumerable.html, have /Enumerable.html and effectively render all version-dependent differences there);
• Better representation of "language core" docs (which are currently in doc/*.rdoc files of language repo);
• more compact, easily browsable, modern representation.

Plan

1. Parse ruby docs from source into RDoc or YARD internal structures;
2. Store those structures into human-readable YAML for caching and investigating;
3. Setup custom rendering for those structures, including handmade TOC for generic Ruby documentation from doc/ folder.
4. Setup ruby/ruby repo as a submodule of docs repo, and, switching between version tags, generate YAML from each version;
5. Render all versions docs into the same HTML files (like core/Enumerable.html), with version tags besides methods and JS switches to "show only version X".
6. Wrap everything into a nicely documented set of Rake tasks and publish to GitHub pages, so anybody can fork, republish and play with styles and logic.

Importance

Current existing Ruby docs (docs.ruby-lang.org and ruby-doc.org) are not Googlable in a good way, due to conflicting versions:

Also, it is unclear from docs of some method, whether it is present in your Ruby version, so typical online browsing of some doc is like "Google for <class> <method> → go to URL → manually replace /2.5.0/ in URL with /2.3.1/ → ...)

Finally, really detailed and good written base Ruby docs (like Syntax guide) is not really visible and navigable through documentation sites.

Skills and domains

You'll do a lot of text parsing, preprocessing and formatting, probably hacking with RDoc and/or YARD internals, some basic UI design.