Product Requirements Document (PRD)

Title: YARD YAML Plugin — HTML output from YAML using yaml-converter
Owner: yard-yaml maintainers
Status: Draft
Date: 2025-11-09

1. Summary

Provide a YARD plugin that renders human-friendly HTML pages from YAML files (and YAML content embedded in code comments) as part of a YARD site build. Conversion will be delegated to the yaml-converter gem. The plugin should be discoverable and configurable through standard YARD mechanisms (.yardopts, Rake tasks, and YARD plugins API).

2. Problem & Goals

  • Problem: Projects often keep structured metadata, examples, configuration, and reference material in YAML. Today, YARD primarily documents code. Teams want this YAML to appear as readable HTML alongside API docs without custom build steps.
  • Goals:
    • Convert YAML files into HTML pages during yard doc.
    • Allow embedding YAML snippets in docstrings and render them as formatted HTML blocks.
    • Use yaml-converter for conversion, not bespoke parsing.
    • Integrate pages into YARD’s navigation and search (where feasible).
    • Make behavior configurable and safe-by-default.

3. Users & Use Cases

  • Library authors maintaining configuration samples in YAML and wanting rendered docs next to API docs.
  • Infra/platform teams documenting schemas (OpenAPI-esque, pipelines, CI configs) stored as YAML.
  • Tool authors whose CLI emits YAML and want example outputs in docs.

Key scenarios:
1) Include all docs/**/*.y{a,}ml in the YARD site.
2) Annotate classes with a @yaml tag that links to a converted YAML page or renders an inline block.
3) Convert YAML that contains front matter (title, nav order) to control placement.

4. Scope

In Scope

  • YARD plugin activation and configuration.
  • Discovery of YAML files by glob patterns.
  • Conversion pipeline: YAML -> HTML via yaml-converter.
  • Writing generated HTML into YARD’s output, integrated with templates.
  • Basic theming consistent with YARD default theme.
  • Inline conversion for code comments via tags/directives.
  • Minimal navigation integration (sidebar list, index page, optional TOC).

Out of Scope (v1)

  • Advanced search indexing of YAML content beyond what YARD already indexes.
  • Live preview server for YAML (beyond yard server).
  • Arbitrary templating engines beyond what yaml-converter supports.
  • Custom YARD theme development.

5. Functional Requirements

  • FR1: Plugin can be enabled via .yardopts or YARD::CLI::Yardoc plugin flag.
  • FR2: Accept configuration:
    • yard_yaml.include (array of globs, default: ["docs/**/*.y{a,}ml", "*.y{a,}ml"]).
    • yard_yaml.exclude (globs to ignore, default: ["**/_*.y{a,}ml"]).
    • yard_yaml.out_dir (subdirectory under output, default: yaml/).
    • yard_yaml.index (generate an index page, default: true).
    • yard_yaml.toc (generate per-page TOC, default: auto).
    • yard_yaml.converter_options (passed through to yaml-converter).
    • yard_yaml.front_matter (respect YAML front matter for title/order), default: true.
  • FR3: For each matched YAML file:
    • Convert to HTML via yaml-converter.
    • Derive page title from front matter or filename.
    • Write to <output>/yaml/<basename>.html.
    • Add to sitemap and sidebar group “YAML” by default.
  • FR4: Provide an index page listing converted files (with titles and short descriptions if available).
  • FR5: Provide @yaml tag for docstrings for inline rendered blocks using yaml-converter.
  • FR6: Provide @yaml_file <relative_path> tag to link or embed converted file.
  • FR7: Respect YARD’s asset pipeline; CSS class names must not clash; include minimal CSS.
  • FR8: Failures:
    • If conversion fails, surface a warning and continue unless yard_yaml.strict=true.
    • If a referenced file is missing, emit warning with location.

6. Non-Functional Requirements

  • NFR1: Zero side effects outside YARD’s output directory.
  • NFR2: Deterministic builds; identical input yields identical output.
  • NFR3: Performance: conversion of 100 small YAML files (<20KB each) adds <2s on Ruby 3.2+.
  • NFR4: Security: do not execute arbitrary code; only parse YAML via safe loader if supported by yaml-converter. Disallow ERB evaluation unless explicitly enabled in config (yard_yaml.allow_erb=false by default).
  • NFR5: Compatibility: YARD >= 0.9.35, Ruby >= 3.2.0.
  • NFR6: Test coverage: near-100% for public API, branch coverage enforced by project setup.

7. Success Metrics

  • M1: Plugin enabled and converting at least one YAML file in an example project.
  • M2: Inline @yaml and @yaml_file examples render in generated docs.
  • M3: CI suite passes with coverage thresholds unchanged.
  • M4: Documentation generated by rake yard includes YAML pages and index.

8. Dependencies

  • Runtime: yaml-converter gem.
  • Dev/test: RSpec, kettle-soup-cover, rubocop-gradual, reek, yard.

9. Risks & Mitigations

  • R1: YAML with dangerous tags or anchors. Mitigation: use safe loader; add allow_unsafe opt gated by config and default false.
  • R2: Large YAML files slow conversion. Mitigation: cache and incremental builds keyed by mtime/hash.
  • R3: Theme mismatch. Mitigation: scope CSS and inherit from YARD defaults; feature flag custom CSS.
  • R4: Conflicts with other plugins. Mitigation: namespaced tags (@yaml, @yaml_file) and isolated templates.

10. UX & Configuration

  • .yardopts examples: 
    --plugin yard-yaml
--yard_yaml-include docs/**/*.yml
--yard_yaml-include docs/**/*.yaml
--yard_yaml-exclude docs/**/_*.yml
--yard_yaml-out_dir yaml
--yard_yaml-index
--yard_yaml-toc
--yard_yaml-converter_options pretty:true,wrap:80
  • Front matter in YAML files (optional): 
    ---
title: Deployment Matrix
nav_order: 12
description: Supported deployment scenarios
---
# actual YAML content follows
  • Inline tags in code comments: 
    # @yaml
#   database:
#     host: localhost
#     port: 5432
# @yaml_file docs/examples/config.yml

11. Technical Approach

  • Register plugin via YARD::Templates::Engine.register_template_path for assets and YARD::Handlers for tags.
  • Implement a Yard::Yaml::Converter wrapper around yaml-converter with safe defaults.
  • File discovery happens during yardoc run (post-registry, pre-render) to emit extra objects or extra files in the template phase.
  • Emit YARD::CodeObjects::ExtraFileObject entries for YAML pages for navigation integration.
  • Generate index page using a simple ERB template bundled with the plugin.

12. Acceptance Criteria

  • AC1: Enabling --plugin yaml and running yard doc produces HTML pages under yaml/ for configured inputs.
  • AC2: @yaml renders formatted HTML blocks in docstrings.
  • AC3: @yaml_file links to or embeds the generated page; missing files warn but do not crash by default.
  • AC4: Running bundle exec rake yard includes YAML pages in output and doesn’t fail linters.
  • AC5: Coverage meets thresholds; types and YARD docs added for public API.

13. Rollout

  • v0.1.0: Core conversion, file discovery, basic index, inline tag rendering.
  • v0.2.0: TOC generation, caching, front matter nav ordering, stricter error reporting.
  • v1.0.0: Stabilize public API, theme polish, documentation, compatibility matrix.