Restructure IRB's documentation

Currently, part of the documentation lives in `lib/irb.rb` as RDoc comments,
and the rest lives in `README.md`.

The RDoc comments are not for viewing on GitHub, while README.md is. So
this means users need to read part of the documentation on
https://ruby.github.io/irb/, and the rest on GitHub. This is not a great
user experience.

This commit restructures the documentation so all major documentation is
in `doc/index.md` that will become the main documentation for IRB on
https://ruby.github.io/irb/.

This solves a 2 main problems:

1. Users can read IRB documentation all in one place, on https://ruby.github.io/irb/.
2. It makes updating the documentation easier, especially the content that
   currently lives in `lib/irb.rb`.

.gitignore

@@ -7,3 +7,4 @@
 /tmp/
 /docs/
 Gemfile.lock
+_site/

.rdoc_options

@@ -0,0 +1,2 @@
+page_dir: doc
+warn_missing_rdoc_ref: true

Rakefile

@@ -45,8 +45,8 @@ end
 task :default => :test
 
 RDoc::Task.new do |rdoc|
-  rdoc.title = "IRB"
-  rdoc.rdoc_dir = "docs"
-  rdoc.main = "README.md"
-  rdoc.options.push("--copy-files", "LICENSE.txt")
+  rdoc.title = "IRB Documentation"
+  rdoc.main = "Index.md"
+  rdoc.rdoc_dir = "_site"
+  rdoc.options.push("lib")
 end

doc/.document

@@ -0,0 +1 @@
+*.md

doc/COMMAND_LINE_OPTIONS.md

@@ -0,0 +1,69 @@
+# Index of Command-Line Options
+
+These are the \IRB command-line options, with links to explanatory text:
+
+- `-d`: Set `$DEBUG` and {$VERBOSE}[rdoc-ref:IRB@Verbosity]
+  to `true`.
+- `-E _ex_[:_in_]`: Set initial external (ex) and internal (in)
+  {encodings}[rdoc-ref:IRB@Encodings] (same as `ruby -E`).
+- `-f`: Don't initialize from {configuration file}[rdoc-ref:IRB@Configuration+File].
+- `-I _dirpath_`: Specify {$LOAD_PATH directory}[rdoc-ref:IRB@Load+Modules]
+  (same as `ruby -I`).
+- `-r _load-module_`: Require {load-module}[rdoc-ref:IRB@Load+Modules]
+  (same as `ruby -r`).
+- `-U`: Set external and internal {encodings}[rdoc-ref:IRB@Encodings] to UTF-8.
+- `-w`: Suppress {warnings}[rdoc-ref:IRB@Warnings] (same as `ruby -w`).
+- `-W[_level_]`: Set {warning level}[rdoc-ref:IRB@Warnings];
+  0=silence, 1=medium, 2=verbose (same as `ruby -W`).
+- `--autocomplete`: Use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- `--back-trace-limit _n_`: Set a {backtrace limit}[rdoc-ref:IRB@Tracer];
+  display at most the top `n` and bottom `n` entries.
+- `--colorize`: Use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- `--context-mode _n_`: Select method to create Binding object
+  for new {workspace}[rdoc-ref:IRB@Commands]; `n` in range `0..4`.
+- `--echo`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--extra-doc-dir _dirpath_`:
+  Add a {documentation directory}[rdoc-ref:IRB@RI+Documentation+Directories]
+  for the documentation dialog.
+- `--inf-ruby-mode`: Set prompt mode to {:INF_RUBY}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  (appropriate for `inf-ruby-mode` on Emacs);
+  suppresses --multiline and --singleline.
+- `--inspect`: Use method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--multiline`: Use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noautocomplete`: Don't use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- `--nocolorize`: Don't use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- `--noecho`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--noecho-on-assignment`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  result on assignment.
+- `--noinspect`: Don't se method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--nomultiline`: Don't use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noprompt`: Don't print {prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats].
+- `--noscript`:  Treat the first command-line argument as a normal
+  {command-line argument}[rdoc-ref:IRB@Initialization+Script],
+  and include it in `ARGV`.
+- `--nosingleline`: Don't use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noverbose`: Don't print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- `--prompt _mode_`, `--prompt-mode _mode_`:
+  Set {prompt and return formats}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  `mode` may be a {pre-defined prompt}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  or the name of a {custom prompt}[rdoc-ref:IRB@Custom+Prompts].
+- `--script`: Treat the first command-line argument as the path to an
+  {initialization script}[rdoc-ref:IRB@Initialization+Script],
+  and omit it from `ARGV`.
+- `--simple-prompt`, `--sample-book-mode`:
+  Set prompt mode to {:SIMPLE}[rdoc-ref:IRB@Pre-Defined+Prompts].
+- `--singleline`: Use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--tracer`: Use {Tracer}[rdoc-ref:IRB@Tracer] to print a stack trace for each input command.
+- `--truncate-echo-on-assignment`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  truncated result on assignment.
+- `--verbose`Print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- `-v`, `--version`: Print the {IRB version}[rdoc-ref:IRB@Version].
+- `-h`, `--help`: Print the {IRB help text}[rdoc-ref:IRB@Help].
+- `--`: Separate options from {arguments}[rdoc-ref:IRB@Command-Line+Arguments]
+  on the command-line.

doc/irb/indexes.md → doc/CONFIGURATION_ENTRIES.md

@@ -1,76 +1,4 @@
-## Indexes
-
-### Index of Command-Line Options
-
-These are the \IRB command-line options, with links to explanatory text:
-
-- `-d`: Set `$DEBUG` and {$VERBOSE}[rdoc-ref:IRB@Verbosity]
-  to `true`.
-- `-E _ex_[:_in_]`: Set initial external (ex) and internal (in)
-  {encodings}[rdoc-ref:IRB@Encodings] (same as `ruby -E`).
-- `-f`: Don't initialize from {configuration file}[rdoc-ref:IRB@Configuration+File].
-- `-I _dirpath_`: Specify {$LOAD_PATH directory}[rdoc-ref:IRB@Load+Modules]
-  (same as `ruby -I`).
-- `-r _load-module_`: Require {load-module}[rdoc-ref:IRB@Load+Modules]
-  (same as `ruby -r`).
-- `-U`: Set external and internal {encodings}[rdoc-ref:IRB@Encodings] to UTF-8.
-- `-w`: Suppress {warnings}[rdoc-ref:IRB@Warnings] (same as `ruby -w`).
-- `-W[_level_]`: Set {warning level}[rdoc-ref:IRB@Warnings];
-  0=silence, 1=medium, 2=verbose (same as `ruby -W`).
-- `--autocomplete`: Use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
-- `--back-trace-limit _n_`: Set a {backtrace limit}[rdoc-ref:IRB@Tracer];
-  display at most the top `n` and bottom `n` entries.
-- `--colorize`: Use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
-  for input and output.
-- `--context-mode _n_`: Select method to create Binding object
-  for new {workspace}[rdoc-ref:IRB@Commands]; `n` in range `0..4`.
-- `--echo`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  return values.
-- `--extra-doc-dir _dirpath_`:
-  Add a {documentation directory}[rdoc-ref:IRB@RI+Documentation+Directories]
-  for the documentation dialog.
-- `--inf-ruby-mode`: Set prompt mode to {:INF_RUBY}[rdoc-ref:IRB@Pre-Defined+Prompts]
-  (appropriate for `inf-ruby-mode` on Emacs);
-  suppresses --multiline and --singleline.
-- `--inspect`: Use method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  return values.
-- `--multiline`: Use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
-- `--noautocomplete`: Don't use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
-- `--nocolorize`: Don't use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
-  for input and output.
-- `--noecho`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  return values.
-- `--noecho-on-assignment`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  result on assignment.
-- `--noinspect`: Don't se method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  return values.
-- `--nomultiline`: Don't use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
-- `--noprompt`: Don't print {prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats].
-- `--noscript`:  Treat the first command-line argument as a normal
-  {command-line argument}[rdoc-ref:IRB@Initialization+Script],
-  and include it in `ARGV`.
-- `--nosingleline`: Don't use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
-- `--noverbose`: Don't print {verbose}[rdoc-ref:IRB@Verbosity] details.
-- `--prompt _mode_`, `--prompt-mode _mode_`:
-  Set {prompt and return formats}[rdoc-ref:IRB@Prompt+and+Return+Formats];
-  `mode` may be a {pre-defined prompt}[rdoc-ref:IRB@Pre-Defined+Prompts]
-  or the name of a {custom prompt}[rdoc-ref:IRB@Custom+Prompts].
-- `--script`: Treat the first command-line argument as the path to an
-  {initialization script}[rdoc-ref:IRB@Initialization+Script],
-  and omit it from `ARGV`.
-- `--simple-prompt`, `--sample-book-mode`:
-  Set prompt mode to {:SIMPLE}[rdoc-ref:IRB@Pre-Defined+Prompts].
-- `--singleline`: Use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
-- `--tracer`: Use {Tracer}[rdoc-ref:IRB@Tracer] to print a stack trace for each input command.
-- `--truncate-echo-on-assignment`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
-  truncated result on assignment.
-- `--verbose`Print {verbose}[rdoc-ref:IRB@Verbosity] details.
-- `-v`, `--version`: Print the {IRB version}[rdoc-ref:IRB@Version].
-- `-h`, `--help`: Print the {IRB help text}[rdoc-ref:IRB@Help].
-- `--`: Separate options from {arguments}[rdoc-ref:IRB@Command-Line+Arguments]
-  on the command-line.
-
-### Index of \IRB.conf Entries
+# \IRB.conf Entries
 
 These are the keys for hash \IRB.conf entries, with links to explanatory text;
 for each entry that is pre-defined, the initial value is given:

doc/EXTEND_IRB.md

@@ -0,0 +1,122 @@
+# Extend IRB
+
+From v1.13.0, IRB provides official APIs to extend its functionality. This feature allows libraries to
+customize and enhance their users' IRB sessions by adding new commands and helper methods tailored for
+the libraries.
+
+## Helper Methods vs. Commands
+
+- Use a helper method if the operation is meant to return a Ruby object that interacts with the application.
+  - For example, an `admin_user` helper method that returns `User.where(admin: true).first`, which can then be used like `login_as(admin_user)`.
+- Use a command if the operation fits one of the following:
+  - A utility operation that performs non-Ruby related tasks, such as IRB's `edit` command.
+  - Displays information, like the `show_source` command.
+  - If the operation requires non-Ruby syntax arguments, like `ls -g pattern`.
+
+If you don't know what to pick, go with commands first. Commands are generally safer as they can handle a wider variety of inputs and use cases.
+
+## Commands
+
+Commands are designed to complete certain tasks or display information for the user, similar to shell commands.
+Therefore, they are designed to accept a variety of inputs, including those that are not valid Ruby code, such
+as `my_cmd Foo#bar` or `my_cmd --flag foo`.
+
+### Example
+
+```rb
+require "irb/command"
+
+class Greet < IRB::Command::Base
+  category "Greeting"
+  description "Greets the user"
+  help_message <<~HELP
+    Greets the user with the given name.
+
+    Usage: greet <name>
+  HELP
+
+  # Any input after the command name will be passed as a single string.
+  # If nothing is added after the command, an empty string will be passed.
+  def execute(arg)
+    puts "Hello! #{arg}"
+  end
+end
+
+IRB::Command.register(:greet, Greet)
+```
+
+As long as the above code is loaded before the IRB session is started, such as in a loaded library or a user's `.irbrc` file, `greet` will be accessible to the user.
+
+```txt
+irb(main):001> greet
+Hello!
+=> nil
+irb(main):002> greet Stan
+Hello! Stan
+=> nil
+```
+
+And because the `Greet` command introduces a new category, `Greeting`, a new help message category will be created:
+
+```txt
+Help
+  help           List all available commands. Use `help <command>` to get information about a specific command.
+
+Greeting
+  greet          Greets the user
+
+IRB
+  context        Displays current configuration.
+  ...
+```
+
+If the optional `help_message` attribute is specified, `help greet` will also display it:
+
+```txt
+irb(main):001> help greet
+Greets the user with the given name.
+
+Usage: greet <name>
+```
+
+## Helper methods
+
+Helper methods are designed to be used as Ruby methods, such as `my_helper(arg, kwarg: val).foo`.
+
+The main use case of helper methods is to provide shortcuts for users, providing quick and easy access to
+frequently used operations or components within the IRB session. For example, a helper method might simplify
+the process of fetching and displaying specific configuration settings or data structures that would otherwise
+require multiple steps to access.
+
+### Example
+
+```rb
+# This only loads the minimum components required to define and register a helper method.
+# It does not load the entire IRB, nor does it initialize it.
+require "irb/helper_method"
+
+class MyHelper < IRB::HelperMethod::Base
+  description "This is a test helper"
+
+  def execute(arg, kwarg:)
+    "arg: #{arg}, kwarg: #{kwarg}"
+  end
+end
+
+IRB::HelperMethod.register(:my_helper, MyHelper)
+```
+
+As long as the above code is loaded before the IRB session is started, such as in a loaded library or a user's `.irbrc` file, `my_helper` will be accessible to the user.
+
+```txt
+irb(main):001> my_helper("foo", kwarg: "bar").upcase
+=> "ARG: FOO, KWARG: BAR"
+```
+
+The registered helper methods will also be listed in the help message's `Helper methods` section:
+
+```txt
+Helper methods
+  conf           Returns the current context.
+  my_helper      This is a test helper
+```