Improve Documentation for YAML and CLI Options

[OdenTakashi]

Thanks for taking care of the maintenance. 🚀

Background

Currently, the README documents only the configuration options that can be passed via the CLI.
However, there are additional options defined in the YAML configuration file that cannot be configured through the CLI, and these options are not comprehensively documented.

Problem

This results in a discoverability issue:

• Some options are available only via YAML and are not mentioned in the README.
• Newly added YAML-only options are difficult to notice.
• Existing options may be unintentionally overlooked.
• This may lead to duplicate or redundant feature proposals.

For example, the ignore_multi_database_name option can be configured via YAML, but it is not documented in the README.
Because it was not easily discoverable, a PR was submitted proposing a similar new option:　#291 (comment)

Proposal

To improve clarity and prevent confusion, I propose adding a comprehensive list of all available configuration options to the README — including both CLI and YAML options.

Possible Idea

As a possible idea, we could introduce a single Markdown table summarizing all options in one place.

Example:

YAML Option	CLI Option	Default	Description
include_version	--show-migration	false	Adds the current migration version to the annotation

This approach would:

• Improve discoverability
• Make configuration options easier to understand
• Reduce the likelihood of duplicate feature proposals
• Provide a clear reference for contributors and users

If there are other suggestions or better ways to organize this, I’d be happy to hear them.

Expected Outcome

By documenting all configuration options in a structured and centralized format, the project will become:

• More transparent
• Easier to contribute to
• Less prone to confusion regarding existing functionality

[drwl]

This makes sense to me. Would it be possible to have this be automated? I want to reduce any frictions for people submitting PRs.

Perhaps it could be something done in a Github action that can run on each commit to main. Thoughts?

[OdenTakashi]

That makes a lot of sense.
Automating this would definitely help reduce friction for contributors. I’ll investigate possible approaches and share what I find.

[drwl]

That makes a lot of sense. Automating this would definitely help reduce friction for contributors. I’ll investigate possible approaches and share what I find.

Sounds good, keep me updated!

[OdenTakashi]

I looked into automating the docs and found that CLI flags and YAML keys don't have a 1:1 mapping in some places:

CLI Flag	YAML Key	Note
--show-migration	include_version	Different naming
--ignore-model-subdirects	ignore_model_sub_dir	Different abbreviation (typo in CLI?)
-d, --delete	target_action: :remove_annotations	Different interface
-e, --exclude tests,...	exclude_tests, exclude_fixtures, ...	One flag expands to multiple keys
-f, --format markdown	format_markdown, format_rdoc, ...	Same pattern as above

Also, some options like ignore_multi_database_name are YAML-only and don't appear in help at all.

This makes it difficult to programmatically map CLI flags to YAML keys, so full auto-generation of the docs isn't straightforward.

Some possible approaches:

• A. Hand-written docs + CI check — Write the table manually, CI just checks for missing keys. Simple but the naming gaps stay. (Small effort)

• B. Enrich help output — Add a YAML reference section to the help output, including YAML-only options. This surfaces the CLI/YAML mapping directly to users. The Parser needs YAML key info added to each option definition. (Medium effort)

  YAML configuration keys:
      active_admin                     Annotate active_admin models (CLI: -a)
      include_version                  Include the migration version number (CLI:
--show-migration)
      ignore_multi_database_name       Skip database name in multi-DB setups (YAML
only)

• C. Restructure Options with metadata — Define CLI flags, YAML keys, and descriptions together in Options. The Parser reads CLI flags from this metadata, and a script generates docs from it — both driven by the same source. (Large effort)

OPTION_METADATA = {
  include_version: { cli: "--show-migration", description: "..." },
  ...
}
# Parser and doc generator both read from this

I'm leaning towards B — it directly solves the discoverability problem for users, and the help output can also serve as the source for README documentation.
The changes would mainly be adding YAML key info to the existing option definitions in the Parser.

Which approach do you prefer? Also open to other ideas if you have a better approach in mind.