How to Generate and Access YARD Documentation

This guide explains how to generate and view the YARD documentation for FakeDataDSL.

Prerequisites

Make sure you have the required gems installed:

bundle install

Or install YARD and Redcarpet manually:

gem install yard
gem install redcarpet

Generating Documentation

Basic Generation

Generate documentation with default settings:

cd /path/to/fake_data_dsl
bundle exec yard doc

This will:

Parse all Ruby files in lib/
Include markdown files from docs/
Generate HTML documentation in doc/ directory

With Options

Generate with specific options:

# Generate to custom directory
bundle exec yard doc --output-dir public/docs

# Generate with statistics
bundle exec yard doc --stats

# Generate without private methods
bundle exec yard doc --no-private

# Generate with all methods (including private)
bundle exec yard doc --private

Clean Generation

Remove old documentation and regenerate:

# Remove old docs
rm -rf doc/

# Generate fresh
bundle exec yard doc

Accessing Documentation

Local HTML Files

After generation, open the documentation:

# On macOS
open doc/index.html

# On Linux
xdg-open doc/index.html

# On Windows
start doc/index.html

Or use a web server:

# Using Python
cd doc
python3 -m http.server 8000
# Then visit http://localhost:8000

# Using Ruby
cd doc
ruby -run -e httpd . -p 8000
# Then visit http://localhost:8000

File Structure

The generated documentation structure:

doc/
├── index.html              # Main documentation page
├── _index.html            # Class/module index
├── file_list.html         # List of all files
├── class_list.html        # List of all classes
├── method_list.html       # List of all methods
├── FakeDataDSL.html      # Main module documentation
├── FakeDataDSL/
│   ├── Types.html         # Types module
│   ├── Types/
│   │   ├── Base.html      # Base type class
│   │   ├── Uuid.html      # UUID type
│   │   └── ...            # Other types
│   └── ...
└── docs/                  # Markdown documentation
    ├── README.html
    ├── getting_started.html
    └── ...

Documentation Features

Classes - Browse all classes and modules
Methods - View all methods
Files - See source file structure
Search - Search across all documentation

Markdown Files

All markdown files from docs/ are included:

Getting Started Guide
DSL Reference
Type Reference
Behaviors Guide
Generation Modes
Advanced Features
Examples
API Reference
Best Practices
Troubleshooting

Code Examples

All code examples are syntax-highlighted and can be copied directly.

Continuous Documentation

Pre-commit Hook

Generate docs before committing:

# .git/hooks/pre-commit
#!/bin/bash
bundle exec yard doc
git add doc/

CI/CD Integration

Generate docs in CI:

# .github/workflows/docs.yml
name: Documentation
on:
  push:
    branches: [main]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
      - run: bundle install
      - run: bundle exec yard doc
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./doc

Publishing Documentation

GitHub Pages

Generate documentation:
```
bundle exec yard doc
```

Push to gh-pages branch:

git checkout --orphan gh-pages
git rm -rf .
cp -r doc/* .
git add .
git commit -m "Update documentation"
git push origin gh-pages

Enable GitHub Pages in repository settings

Read the Docs

Install sphinx and sphinx-rtd-theme
Convert YARD docs to Sphinx format
Configure Read the Docs

Troubleshooting

YARD Not Found

# Install YARD
gem install yard

# Or use bundle
bundle install

Redcarpet Not Found

# Install Redcarpet for markdown support
gem install redcarpet

Documentation Not Updating

# Clear cache and regenerate
rm -rf .yardoc doc/
bundle exec yard doc

Missing Markdown Files

Ensure .yardopts includes:

docs/**/*.md