docco

Basic Setup

Add the following to your gem’s Rakefile:

require 'docco/tasks'

That’s it! Now you can generate documentation with:

bundle exec rake docco:docs

This will:

1. Read your README.md
2. Extract metadata from your .gemspec
3. Generate a beautiful HTML website in the docs/ directory
4. Copy the necessary CSS styles

Programmatic Usage

You can also use Docco programmatically in your Ruby code:

require 'docco'

# Basic usage - auto-detects gemspec
builder = Docco::DocsBuilder.new(
  readme_path: 'README.md',
  output_dir: 'docs'
)
builder.build

# With custom gemspec path
builder = Docco::DocsBuilder.new(
  readme_path: 'README.md',
  output_dir: 'public/docs',
  gemspec_path: 'my_gem.gemspec'
)
builder.build

Available Rake Tasks

Docco provides three rake tasks:

Generate Documentation

# Default: uses README.md and outputs to docs/
bundle exec rake docco:docs

# With custom paths
bundle exec rake docco:docs[path/to/README.md,output/dir,my_gem.gemspec]

Copy Styles

If you want to customize the styles, first copy the default stylesheet:

# Copies to docs/styles.css (default)
bundle exec rake docco:css

# Copy to custom directory
bundle exec rake docco:css[custom/path]

Then you can edit docs/styles.css to customize the appearance.

Generate GitHub Action

Automatically create a GitHub Action that builds and deploys your documentation to GitHub Pages:

bundle exec rake docco:gh

This creates .github/workflows/deploy-docs.yml with a pre-configured workflow that:

• Runs on push to main branch
• Builds your documentation
• Deploys to GitHub Pages

GitHub Actions Integration

After running rake docco:gh, you’ll have a GitHub Action that automatically deploys documentation. To complete the setup:

1. Go to your GitHub repository settings
2. Navigate to Pages section
3. Set source to “GitHub Actions”

Now every push to main will automatically rebuild and deploy your docs!

Example workflow (created by docco:gh):

name: Deploy Documentation

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
      - run: bundle install
      - run: bundle exec rake docco:docs
      - uses: actions/upload-pages-artifact@v1
        with:
          path: docs
      - uses: actions/deploy-pages@v1

README Structure Requirements

For best results, structure your README like this:

# Gem Name

Brief description of your gem.

## Installation

Installation instructions...

## Usage

### Basic Usage

Example code...

### Advanced Usage

More examples...

## Configuration

Configuration options...

## Contributing

Contributing guidelines...

• The first # heading becomes the page title
• Level 2 headings (##) become main navigation items
• Level 3 headings (###) become sub-navigation items

Custom Styles

Copy the default styles and customize them:

bundle exec rake docco:css

Then edit docs/styles.css to match your branding. The CSS uses CSS custom properties (variables) for easy theming:

:root {
  --primary-color: #007bff;
  --bg-color: #ffffff;
  --text-color: #333333;
  /* ... and many more */
}

Gemspec Metadata

Docco extracts information from your gemspec. Make sure these fields are set:

Gem::Specification.new do |spec|
  spec.name = "my_gem"
  spec.summary = "A short description"
  spec.description = "A longer description"
  spec.homepage = "https://github.com/username/my_gem"

  # For the GitHub link, set source_code_uri
  spec.metadata["source_code_uri"] = "https://github.com/username/my_gem"
end

Testing Your Changes

Generate documentation for Docco itself:

bundle exec rake docco:docs

Then open docs/index.html in your browser to see the results.