DOCSEARCHbyAlgolia
Submit Docs

AnnotateRb Documentation

repository·main·Indexed 20 days ago

https://github.com/drwl/annotaterb

A Ruby gem that adds schema and route annotations to ActiveRecord models, fixture files, tests, factories, and Rails routes. It provides a CLI for manual annotation and Rails generators for automatic updates during database migrations. Supports multiple output formats (bare, rdoc, yard, markdown) and configurable placement via a .annotaterb.yml file.

Tokens
10.5K
Snippets
37
Records
50
Agent score
70%

What's inside AnnotateRb

  1. How column sorting works

    main

    By default, columns are sorted in database order (the order in which migrations were executed). You can change this behavior using the following methods:

    1. Alphabetical Sort: Use the --sort flag to sort columns alphabetically.
    2. Classified Sort: Use the --classified-sort flag to sort columns by a specific hierarchy: id $\rightarrow$ other columns $\rightarrow$ timestamp columns $\rightarrow$ association columns. You can also use --grouped-polymorphic in conjunction with this to group polymorphic associations.

  2. How to preserve class documentation comments

    main

    By default, AnnotateRb places annotations immediately before the class declaration. This can push human-written documentation comments above the annotation block.

    To keep documentation comments adjacent to the class, set position_in_class to before_doc. This inserts the schema annotation above the documentation block, leaving the comment directly before the class.

    Note: Recognized magic comments (e.g., encoding, frozen_string_literal, typed, rbs_inline) are excluded from this logic so the annotation can be inserted between magic comments and the class doc.

    # Source file:
# Doc about User
class User < ApplicationRecord
end

# With position_in_class: before  (default)
# Doc about User
# == Schema Information
# ...
class User < ApplicationRecord
end

# With position_in_class: before_doc
# == Schema Information
# ...
# Doc about User
class User < ApplicationRecord
end

  3. Migrate from Annotate to AnnotateRb

    main

    If you are migrating from the Annotate gem to AnnotateRb, note the following key changes:

    • Ruby Version: Minimum supported Ruby version is 2.7.
    • CLI Structure: Commands are now split into models and routes instead of using --models or -r flags on a single command.
    • Configuration: Environment variables (ENV) are no longer supported. Use a .annotaterb.yml file in your Rails project root instead.
    • Rake Tasks: The following Rake commands from the old gem have been removed: annotate_models, remove_annotation, annotate_routes, and remove_routes.
    • Automatic Annotations: The old lib/tasks/auto_annotate_models.rake file is no longer used. Use the new generator to set up automatic annotations.

  4. Set up automatic annotations with the install generator

    main

    To replace the old Annotate automatic annotation Rake tasks, use the AnnotateRb generator. This will install the necessary files into your Rails project to hook into database migration tasks.

    Run the following command:

    bin/rails g annotate_rb:install

    This command automatically generates a .annotaterb.yml file populated with the gem's default settings. If you had custom settings in the old Annotate.set_defaults block, you should manually migrate those key-value pairs into the new .annotaterb.yml file.

    $ bin/rails g annotate_rb:install

  5. How to skip annotating a particular model

    main

    To prevent AnnotateRb from adding annotations to a specific model file, include the following string anywhere in the file:

    # -*- SkipSchemaAnnotations

    # -*- SkipSchemaAnnotations
class MyModel < ApplicationRecord
end

  6. Run unit and integration tests

    main

    AnnotateRb uses RSpec for unit tests and a combination of RSpec and Aruba for integration tests.

    To run unit tests:

    bundle exec rake spec:unit

    To run integration tests (requires dummyapp setup and DATABASE_ADAPTER environment variable):

    DATABASE_ADAPTER=sqlite3 bundle exec rake spec:integration
    bundle exec rake spec:unit
DATABASE_ADAPTER=sqlite3 bundle exec rake spec:integration

  7. Standard development flow

    main

    Follow these steps to contribute to AnnotateRb:

    1. Fork the repository.
    2. Make your changes.
    3. Run unit tests: bundle exec rake spec:unit.
    4. (Optional) Run integration tests: DATABASE_ADAPTER=sqlite3 bundle exec rake spec:integration (ensure dummyapp is set up).
    5. Run the linter: bundle exec standardrb (or bundle exec standardrb --fix).
    6. Submit a pull request.

  8. Set up the dummyapp for integration testing

    main

    The /spec/dummyapp directory contains a Rails application used for integration testing. To test the gem locally or run integration tests, you must install the dependencies for the dummyapp and set up the required databases.

    When running bundle install or executing commands within the context of the dummyapp, you must specify the DATABASE_ADAPTER environment variable. Supported values include mysql2, pg, and sqlite3.

    # Example of running the gem in the context of the dummyapp with a specific adapter
DATABASE_ADAPTER=sqlite3 bundle exec annotaterb models

  9. Configure AnnotateRb using a YAML file

    main

    AnnotateRb allows you to store default configuration options in a .annotaterb.yml file located in your Rails project root. This replaces the need for environment variables used in the original Annotate gem. The configuration file is processed through ERB before being merged with any options passed via the CLI.

    Supported configuration file locations (in order of precedence):

    1. .annotaterb.yml
    2. config/annotaterb.yml
    3. .config/.annotaterb.yml
    4. .config/annotaterb/config.yml
    # .annotaterb.yml
position: after

  10. Automatically annotate models in Rails

    main

    For Rails projects, you can configure AnnotateRb to automatically update model annotations whenever you run database migration tasks.

    1. Install the hook: Run the following generator to copy a Rake task into lib/tasks that hooks into Rails rake tasks.

      $ bin/rails g annotate_rb:install

      Note: annotate_rb:install runs both annotate_rb:config and annotate_rb:hook.

    2. Run migrations: Annotations will now update automatically after running migrations.

      $ bin/rails db:migrate
# Output will indicate: # Annotating models
# Annotated (1): app/models/task.rb

    Skip automatic annotation: If you want to run a database task without triggering the automatic annotation, set the ANNOTATERB_SKIP_ON_DB_TASKS environment variable to 1.

    $ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate
    $ bin/rails g annotate_rb:install

  12. Install AnnotateRb

    main

    You can install AnnotateRb as a standalone gem or include it in your Rails project's Gemfile. It is recommended to place it in the :development group.

    Standalone installation:

    $ gem install annotaterb

    Rails Gemfile installation:

    group :development do
  gem "annotaterb"
end
    group :development do
  gem "annotaterb"
end