rails-engine-docs

Rails Engine Docs

All generated documentation (README, guides, examples) must be in English unless the user explicitly requests another language.

Recommended README Shape

1. Purpose — what the engine does and when to use it
2. Installation — gem add, bundle, run install generator
3. Mounting — explicit mount MyEngine::Engine, at: '/path' in routes
4. Configuration — all options with defaults, required vs optional
5. Usage examples — copyable code for typical workflows
6. Migrations / operational steps — install generator, one-time setup
7. Extension points — adapters, callbacks, config blocks
8. Development and testing — how to run tests or contribute

Documentation Rules

• Document required host-app steps before optional customization.
• Keep examples copyable and close to real code.
• Show the minimum working install path first.
• If the engine assumes any host model, job backend, or auth integration, say so explicitly.
• Document upgrade-impacting changes when setup evolves.

Documentation Gaps to Check

See CHECKLIST.md for the full gap checklist. Critical gaps: installation steps, all config options with defaults, explicit mount path, migration timing, host model/auth assumptions.

Examples

README snippet (install + mount):

## Installation

Add to your Gemfile:

    gem 'my_engine'

Run:

    bundle install
    rails generate my_engine:install

This creates `config/initializers/my_engine.rb`. Mount the engine in `config/routes.rb`:

    mount MyEngine::Engine, at: '/admin'

Configuration section:

## Configuration

In `config/initializers/my_engine.rb`:

    MyEngine.configure do |config|
      config.user_class = "User"       # required: host model for current user
      config.widget_count = 10         # optional, default 10
    end

Output Style

When asked to write docs:

1. Start with the minimum install path.
2. Show one realistic configuration example.
3. Document operational steps explicitly.
4. Keep sections short and task-oriented.
5. Check each row in the Documentation Gaps checklist against the draft. A checklist item passes when the docs contain a corresponding section with at least one copyable code example or explicit prose statement. A checklist item fails when the section is absent, incomplete, or lacks a concrete example. For each failing item: add the missing section or example, then re-run the checklist from the top. Do not finalize until all critical items pass.

Integration

Skill	When to chain
rails-engine-author	Host-app contract, structure, extension points to document
rails-engine-installers	Install generators, setup steps to document
rails-engine-release	Changelog, upgrade notes, version documentation
api-rest-collection	When documenting or adding API endpoints (keep Postman collection in sync)

Assets

• assets/configuration.md
• assets/examples.md
• assets/installation.md