Reorganize top-level doc files for better doc navigation

array.c

@@ -1115,7 +1115,7 @@ rb_ary_s_new(int argc, VALUE *argv, VALUE klass)
  *    array # => [{a: 1}, {}], as array[0] and array[1] are different objects
  *
  *  Raises TypeError if the first argument is not either an array
- *  or an {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]).
+ *  or an {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects]).
  *  Raises ArgumentError if the first argument is a negative integer.
  *
  *  Related: see {Methods for Creating an Array}[rdoc-ref:Array@Methods+for+Creating+an+Array].
@@ -1935,7 +1935,7 @@ rb_ary_aref1(VALUE ary, VALUE arg)
  *  Returns the element of +self+ specified by the given +index+
  *  or +nil+ if there is no such element;
  *  +index+ must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects].
  *
  *  For non-negative +index+, returns the element of +self+ at offset +index+:
  *
@@ -2003,7 +2003,7 @@ rb_ary_last(int argc, const VALUE *argv, VALUE ary) // used by parse.y
  *    fetch(index) {|index| ... } -> element or block_return_value
  *
  *  Returns the element of +self+ at offset +index+ if +index+ is in range; +index+ must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects].
  *
  *  With the single argument +index+ and no block,
  *  returns the element at offset +index+:
@@ -3495,7 +3495,7 @@ static VALUE rb_ary_bsearch_index(VALUE ary);
  *  Returns the element from +self+ found by a binary search,
  *  or +nil+ if the search found no suitable element.
  *
- *  See {Binary Searching}[rdoc-ref:bsearch.rdoc].
+ *  See {Binary Searching}[rdoc-ref:ruby/bsearch.rdoc].
  *
  *  Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
  */
@@ -3519,7 +3519,7 @@ rb_ary_bsearch(VALUE ary)
  *  Returns the integer index of the element from +self+ found by a binary search,
  *  or +nil+ if the search found no suitable element.
  *
- *  See {Binary Searching}[rdoc-ref:bsearch.rdoc].
+ *  See {Binary Searching}[rdoc-ref:ruby/bsearch.rdoc].
  *
  *  Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
  */
@@ -4125,7 +4125,7 @@ rb_ary_delete_at(VALUE ary, long pos)
  *    delete_at(index) -> removed_object or nil
  *
  *  Removes the element of +self+ at the given +index+, which must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects].
  *
  *  When +index+ is non-negative, deletes the element at offset +index+:
  *
@@ -4661,7 +4661,7 @@ rb_ary_transpose(VALUE ary)
  *    replace(other_array) -> self
  *
  *  Replaces the elements of +self+ with the elements of +other_array+, which must be an
- *  {array-convertible object}[rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Objects];
+ *  {array-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Array-Convertible+Objects];
  *  returns +self+:
  *
  *    a = ['a', 'b', 'c']   # => ["a", "b", "c"]
@@ -4780,7 +4780,7 @@ rb_ary_clear(VALUE ary)
  *  When arguments +start+ and +count+ are given,
  *  they select the elements of +self+ to be replaced;
  *  each must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects]
  *  (or +nil+):
  *
  *  - +start+ specifies the zero-based offset of the first element to be replaced;
@@ -6586,7 +6586,7 @@ flatten(VALUE ary, int level)
  *
  *  Returns +self+ as a recursively flattening of +self+ to +depth+ levels of recursion;
  *  +depth+ must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects],
  *  or +nil+.
  *  At each level of recursion:
  *
@@ -6644,7 +6644,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
  *  Returns a new array that is a recursive flattening of +self+
  *  to +depth+ levels of recursion;
  *  +depth+ must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects]
  *  or +nil+.
  *  At each level of recursion:
  *
@@ -6895,7 +6895,7 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj)
  *
  *  With a block given, may call the block, depending on the value of argument +count+;
  *  +count+ must be an
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects],
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects],
  *  or +nil+.
  *
  *  When +count+ is positive,
@@ -7177,7 +7177,7 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj)
  *    combination(n) -> new_enumerator
  *
  *  When a block and a positive
- *  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]
+ *  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects]
  *  argument +n+ (<tt>0 < n <= self.size</tt>)
  *  are given, calls the block with all +n+-tuple combinations of +self+;
  *  returns +self+:
@@ -8017,7 +8017,7 @@ rb_ary_one_p(int argc, VALUE *argv, VALUE ary)
  *  Finds and returns the object in nested object
  *  specified by +index+ and +identifiers+;
  *  the nested objects may be instances of various classes.
- *  See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
+ *  See {Dig Methods}[rdoc-ref:ruby/dig_methods.rdoc].
  *
  *  Examples:
  *
@@ -8282,7 +8282,7 @@ rb_ary_deconstruct(VALUE ary)
  *  Although the effective index into an array is always an integer,
  *  some methods (both within class \Array and elsewhere)
  *  accept one or more non-integer arguments that are
- *  {integer-convertible objects}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects].
+ *  {integer-convertible objects}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects].
  *
  *  == Creating Arrays
  *

array.rb

@@ -184,7 +184,7 @@ def last n = unspecified = true
   #  With no block given, returns a new array containing the elements of +self+
   #  at the offsets given by +indexes+;
   #  each of the +indexes+ must be an
-  #  {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]:
+  #  {integer-convertible object}[rdoc-ref:ruby/implicit_conversion.rdoc@Integer-Convertible+Objects]:
   #
   #    a = [:foo, :bar, :baz]
   #    a.fetch_values(3, 1)   # => [:baz, :foo]

common.mk

@@ -1845,11 +1845,11 @@ $(UNICODE_HDR_DIR)/name2ctype.h:
 		$(UNICODE_SRC_DATA_DIR) $(UNICODE_SRC_EMOJI_DATA_DIR) > $@.new
 	$(MV) $@.new $@
 
-srcs-doc: $(srcdir)/doc/regexp/unicode_properties.rdoc
-$(srcdir)/doc/regexp/$(ALWAYS_UPDATE_UNICODE:yes=unicode_properties.rdoc): \
+srcs-doc: $(srcdir)/doc/ruby/regexp/unicode_properties.rdoc
+$(srcdir)/doc/ruby/regexp/$(ALWAYS_UPDATE_UNICODE:yes=unicode_properties.rdoc): \
 	$(UNICODE_HDR_DIR)/name2ctype.h $(UNICODE_PROPERTY_FILES)
 
-$(srcdir)/doc/regexp/unicode_properties.rdoc:
+$(srcdir)/doc/ruby/regexp/unicode_properties.rdoc:
 	$(Q) $(BOOTSTRAPRUBY) $(tooldir)/generic_erb.rb -c -o $@ \
 		$(srcdir)/template/unicode_properties.rdoc.tmpl \
 		$(UNICODE_SRC_DATA_DIR) $(UNICODE_HDR_DIR)/name2ctype.h || \

dir.c

@@ -3455,7 +3455,7 @@ dir_open_dir(int argc, VALUE *argv)
  *   #<Encoding:UTF-8>
  *   #<Encoding:US-ASCII>
  *
- * See {String Encoding}[rdoc-ref:encodings.rdoc@String+Encoding].
+ * See {String Encoding}[rdoc-ref:ruby/encodings.rdoc@String+Encoding].
  *
  * Returns an enumerator if no block is given.
  */
@@ -3491,7 +3491,7 @@ dir_collect(VALUE dir)
  *   Dir.entries('/example', encoding: 'US-ASCII').first.encoding
  *   # => #<Encoding:US-ASCII>
  *
- * See {String Encoding}[rdoc-ref:encodings.rdoc@String+Encoding].
+ * See {String Encoding}[rdoc-ref:ruby/encodings.rdoc@String+Encoding].
  *
  * Raises an exception if the directory does not exist.
  */
@@ -3588,7 +3588,7 @@ dir_collect_children(VALUE dir)
  *   Dir.children('/example', encoding: 'US-ASCII').first.encoding
  *   # => #<Encoding:US-ASCII>
  *
- * See {String Encoding}[rdoc-ref:encodings.rdoc@String+Encoding].
+ * See {String Encoding}[rdoc-ref:ruby/encodings.rdoc@String+Encoding].
  *
  * Raises an exception if the directory does not exist.
  */

doc/.document

@@ -7,6 +7,5 @@ syntax
 optparse
 rdoc
 regexp
-rjit
-yjit
 ruby
+jit_compilers

doc/NEWS/NEWS-3.0.0.md

@@ -296,7 +296,7 @@ Outstanding ones only.
 
 * Ractor
 
-    * New class added to enable parallel execution. See rdoc-ref:ractor.md for
+    * New class added to enable parallel execution. See rdoc-ref:ruby/ractor.md for
       more details.
 
 * Random
@@ -361,7 +361,7 @@ Outstanding ones only.
 
     * Introduce Fiber.set_scheduler for intercepting blocking operations and
       Fiber.scheduler for accessing the current scheduler. See
-      rdoc-ref:fiber.md for more details about what operations are supported and
+      rdoc-ref:ruby/fiber.md for more details about what operations are supported and
       how to implement the scheduler hooks. [[Feature #16786]]
 
     * Fiber.blocking? tells whether the current execution context is

doc/_regexp.rdoc

@@ -39,7 +39,7 @@ A regexp may be used:
   most such methods accept an argument that may be either a string
   or the (much more powerful) regexp.
 
-  See {Regexp Methods}[rdoc-ref:regexp/methods.rdoc].
+  See {Regexp Methods}[rdoc-ref:ruby/regexp/methods.rdoc].
 
 == \Regexp Objects
 
@@ -814,7 +814,7 @@ Or by using <tt>\P</tt> (uppercase +P+):
   /\P{Alpha}/.match('1') # => #<MatchData "1">
   /\P{Alpha}/.match('a') # => nil
 
-See {Unicode Properties}[rdoc-ref:regexp/unicode_properties.rdoc]
+See {Unicode Properties}[rdoc-ref:ruby/regexp/unicode_properties.rdoc]
 for regexps based on the numerous properties.
 
 Some commonly-used properties correspond to POSIX bracket expressions:

doc/index.md

@@ -30,8 +30,8 @@ Explore the essential classes and modules:
 Deep dive into Ruby's syntax and features:
 
 - [Ruby Syntax](rdoc-ref:syntax.rdoc)
-- [Exceptions](rdoc-ref:exceptions.md)
-- [Implicit Conversions](rdoc-ref:implicit_conversion.rdoc)
+- [Exceptions](rdoc-ref:ruby/exceptions.md)
+- [Implicit Conversions](rdoc-ref:ruby/implicit_conversion.rdoc)
 
 ## Standard Libraries
 
@@ -44,7 +44,7 @@ There are some standard libraries included in Ruby that are also commonly used,
 
 Use the following links to access the comprehensive set of libraries included with Ruby:
 
-- [Standard Library Documentation](rdoc-ref:standard_library.rdoc)
+- [Standard Library Documentation](rdoc-ref:ruby/standard_library.rdoc)
 - [Maintainers](rdoc-ref:maintainers.md)
 
 ## Contribute to Ruby

doc/encodings.rdoc → doc/ruby/encodings.rdoc

@@ -138,15 +138,15 @@ A Ruby String object has an encoding that is an instance of class \Encoding.
 The encoding may be retrieved by method String#encoding.
 
 The default encoding for a string literal is the script encoding;
-see {Script Encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].
+see {Script Encoding}[rdoc-ref:ruby/encodings.rdoc@Script+Encoding].
 
   's'.encoding # => #<Encoding:UTF-8>
 
 The default encoding for a string created with method String.new is:
 
 - For a \String object argument, the encoding of that string.
 - For a string literal, the script encoding;
-  see {Script Encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].
+  see {Script Encoding}[rdoc-ref:ruby/encodings.rdoc@Script+Encoding].
 
 In either case, any encoding may be specified:
 
@@ -192,7 +192,7 @@ The default encoding for these, however, is:
 
 - US-ASCII, if all characters are US-ASCII.
 - The script encoding, otherwise;
-  see (Script Encoding)[rdoc-ref:encodings.rdoc@Script+Encoding].
+  see (Script Encoding)[rdoc-ref:ruby/encodings.rdoc@Script+Encoding].
 
 == Filesystem \Encoding
 

doc/format_specifications.rdoc → doc/ruby/format_specifications.rdoc

@@ -45,42 +45,42 @@ The links lead to the details and examples.
 === \Integer Type Specifiers
 
 - +b+ or +B+: Format +argument+ as a binary integer.
-  See {Specifiers b and B}[rdoc-ref:format_specifications.rdoc@Specifiers+b+and+B].
+  See {Specifiers b and B}[rdoc-ref:ruby/format_specifications.rdoc@Specifiers+b+and+B].
 - +d+, +i+, or +u+ (all are identical):
   Format +argument+ as a decimal integer.
-  See {Specifier d}[rdoc-ref:format_specifications.rdoc@Specifier+d].
+  See {Specifier d}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+d].
 - +o+: Format +argument+ as an octal integer.
-  See {Specifier o}[rdoc-ref:format_specifications.rdoc@Specifier+o].
+  See {Specifier o}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+o].
 - +x+ or +X+: Format +argument+ as a hexadecimal integer.
-  See {Specifiers x and X}[rdoc-ref:format_specifications.rdoc@Specifiers+x+and+X].
+  See {Specifiers x and X}[rdoc-ref:ruby/format_specifications.rdoc@Specifiers+x+and+X].
 
 === Floating-Point Type Specifiers
 
 - +a+ or +A+: Format +argument+ as hexadecimal floating-point number.
-  See {Specifiers a and A}[rdoc-ref:format_specifications.rdoc@Specifiers+a+and+A].
+  See {Specifiers a and A}[rdoc-ref:ruby/format_specifications.rdoc@Specifiers+a+and+A].
 - +e+ or +E+: Format +argument+ in scientific notation.
-  See {Specifiers e and E}[rdoc-ref:format_specifications.rdoc@Specifiers+e+and+E].
+  See {Specifiers e and E}[rdoc-ref:ruby/format_specifications.rdoc@Specifiers+e+and+E].
 - +f+: Format +argument+ as a decimal floating-point number.
-  See {Specifier f}[rdoc-ref:format_specifications.rdoc@Specifier+f].
+  See {Specifier f}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+f].
 - +g+ or +G+: Format +argument+ in a "general" format.
-  See {Specifiers g and G}[rdoc-ref:format_specifications.rdoc@Specifiers+g+and+G].
+  See {Specifiers g and G}[rdoc-ref:ruby/format_specifications.rdoc@Specifiers+g+and+G].
 
 === Other Type Specifiers
 
 - +c+: Format +argument+ as a character.
-  See {Specifier c}[rdoc-ref:format_specifications.rdoc@Specifier+c].
+  See {Specifier c}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+c].
 - +p+: Format +argument+ as a string via <tt>argument.inspect</tt>.
-  See {Specifier p}[rdoc-ref:format_specifications.rdoc@Specifier+p].
+  See {Specifier p}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+p].
 - +s+: Format +argument+ as a string via <tt>argument.to_s</tt>.
-  See {Specifier s}[rdoc-ref:format_specifications.rdoc@Specifier+s].
+  See {Specifier s}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+s].
 - <tt>%</tt>: Format +argument+ (<tt>'%'</tt>) as a single percent character.
-  See {Specifier %}[rdoc-ref:format_specifications.rdoc@Specifier+-25].
+  See {Specifier %}[rdoc-ref:ruby/format_specifications.rdoc@Specifier+-25].
 
 == Flags
 
 The effect of a flag may vary greatly among type specifiers.
 These remarks are general in nature.
-See {type-specific details}[rdoc-ref:format_specifications.rdoc@Type+Specifier+Details+and+Examples].
+See {type-specific details}[rdoc-ref:ruby/format_specifications.rdoc@Type+Specifier+Details+and+Examples].
 
 Multiple flags may be given with single type specifier;
 order does not matter.

doc/ruby/options.md

@@ -640,7 +640,7 @@ Option `--encoding` is an alias for
 Option `--external-encoding`
 sets the default external encoding for the invoked Ruby program;
 for values of +encoding+,
-see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
+see {Encoding: Names and Aliases}[rdoc-ref:ruby/encodings.rdoc@Names+and+Aliases].
 
 ```sh
 $ ruby -e 'puts Encoding::default_external'
@@ -662,7 +662,7 @@ For a shorter help message, use option `-h`.
 Option `--internal-encoding`
 sets the default internal encoding for the invoked Ruby program;
 for values of +encoding+,
-see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
+see {Encoding: Names and Aliases}[rdoc-ref:ruby/encodings.rdoc@Names+and+Aliases].
 
 ```sh
 $ ruby -e 'puts Encoding::default_internal.nil?'

doc/packed_data.rdoc → doc/ruby/packed_data.rdoc

@@ -58,7 +58,7 @@ Any directive may be followed by either of these modifiers:
     'AB'.unpack('C3')   # => [65, 66, nil]
 
   Note: Directives in <tt>%w[A a Z m]</tt> use +count+ differently;
-  see {String Directives}[rdoc-ref:packed_data.rdoc@String+Directives].
+  see {String Directives}[rdoc-ref:ruby/packed_data.rdoc@String+Directives].
 
 If elements don't fit the provided directive, only least significant bits are encoded:
 

doc/strftime_formatting.rdoc → doc/ruby/strftime_formatting.rdoc

@@ -136,7 +136,7 @@ the only required part is the conversion specifier, so we begin with that.
     t = Time.now       # => 2022-06-29 07:10:20.3230914 -0500
     t.strftime('%N')   # => "323091400"                  # Default.
 
-  Use {width specifiers}[rdoc-ref:strftime_formatting.rdoc@Width+Specifiers]
+  Use {width specifiers}[rdoc-ref:ruby/strftime_formatting.rdoc@Width+Specifiers]
   to adjust units:
 
       t.strftime('%3N')  # => "323"                      # Milliseconds.
@@ -523,5 +523,5 @@ ISO 8601 date and any ISO 8601 time,
 separated by the letter +T+.
 
 For the relevant +strftime+ formats, see
-{Dates}[rdoc-ref:strftime_formatting.rdoc@Dates]
-and {Times}[rdoc-ref:strftime_formatting.rdoc@Times] above.
+{Dates}[rdoc-ref:ruby/strftime_formatting.rdoc@Dates]
+and {Times}[rdoc-ref:ruby/strftime_formatting.rdoc@Times] above.

doc/string/encode.rdoc

@@ -37,7 +37,7 @@ interprets +self+ using +src_encoding+, encodes the new string using +dst_encodi
   t.encoding                            # => #<Encoding:UTF-8>
 
 Optional keyword arguments +enc_opts+ specify encoding options;
-see {Encoding Options}[rdoc-ref:encodings.rdoc@Encoding+Options].
+see {Encoding Options}[rdoc-ref:ruby/encodings.rdoc@Encoding+Options].
 
 Please note that, unless <code>invalid: :replace</code> option is
 given, conversion from an encoding +enc+ to the same encoding +enc+

doc/string/new.rdoc

@@ -16,7 +16,7 @@ returns a copy of +string+ with the same encoding:
 (Unlike \String.new,
 a {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals] like <tt>''</tt> or a
 {here document literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals]
-always has {script encoding}[rdoc-ref:encodings.rdoc@Script+Encoding].)
+always has {script encoding}[rdoc-ref:ruby/encodings.rdoc@Script+Encoding].)
 
 With optional keyword argument +encoding+, returns a copy of +string+
 with the specified encoding;

doc/syntax/assignment.rdoc

@@ -279,7 +279,7 @@ An uninitialized global variable has a value of +nil+.
 
 Ruby has some special globals that behave differently depending on context
 such as the regular expression match variables or that have a side-effect when
-assigned to.  See the {global variables documentation}[rdoc-ref:globals.rdoc]
+assigned to.  See the {global variables documentation}[rdoc-ref:ruby/globals.rdoc]
 for details.
 
 == Assignment Methods