ruby · st0012 · Sep 16, 2025 · Sep 7, 2025 · kou · Sep 7, 2025
diff --git a/.rdoc_options b/.rdoc_options
@@ -1,5 +1,5 @@
 op_dir: _site # for GitHub Pages and should match the config of RDoc task in Rakefile
 title: rdoc Documentation
-main_page: README.rdoc
+main_page: README.md
 autolink_excluded_words:
 - RDoc
diff --git a/README.md b/README.md
@@ -0,0 +1,112 @@
+# RDoc - Ruby Documentation System
+
+- GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
+- Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
+
+## Description
+
+RDoc produces HTML and command-line documentation for Ruby projects.  RDoc includes the `rdoc` and `ri` tools for generating and displaying documentation from the command-line.
+
+## Generating Documentation
+
+Once installed, you can create documentation using the `rdoc` command
+
+```shell
+rdoc [options] [names...]
+```
+
+For an up-to-date option summary, type
+
+```shell
+rdoc --help
+```
+
+A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).
+
+```shell
+rdoc
+```
+
+This command generates documentation for all the Ruby and C source files in and below the current directory.  These will be stored in a documentation tree starting in the subdirectory `doc`.
+
+You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file.  In our case, we could type
+
+```shell
+rdoc --main README.md
+```
+
+You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.
+
+RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.
+
+To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
+
+To generate documentation programmatically:
+
+```rb
+require 'rdoc/rdoc'
+
+options = RDoc::Options.new
+options.files = ['a.rb', 'b.rb']
+options.setup_generator 'darkfish'
+# see RDoc::Options
+
+rdoc = RDoc::RDoc.new
+rdoc.document options
+# see RDoc::RDoc
+```
+
+You can specify the target files for document generation with `.document` file in the project root directory. `.document` file contains a list of file and directory names including comment lines starting with `#`. See [https://github.com/ruby/rdoc/blob/master/.document](https://github.com/ruby/rdoc/blob/master/.document) as an example.
+
+## Writing Documentation
+
+To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+
+```rb
+##
+# This class represents an arbitrary shape by a series of points.
+class Shape
+  ##
+  # Creates a new shape described by a +polyline+.
+  #
+  # If the +polyline+ does not end at the same point it started at the
+  # first pointed is copied and placed at the end of the line.
+  #
+  # An ArgumentError is raised if the line crosses itself, but shapes may
+  # be concave.
+  def initialize polyline
+    # ...
+  end
+end
+```
+
+The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported.  You can set the default comment format for your entire project by creating a `.rdoc_options` file.  See RDoc::Options@Saved+Options for instructions on creating one.  You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats.  See RDoc::Markup@Other+directives.
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing.  See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic.  See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+
+See RDoc::Parser::C for documenting C extensions with RDoc.
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report.  `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+
+## Theme Options
+
+There are a few community-maintained themes for RDoc:
+
+- [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
+- [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))
+
+Please follow the theme's README for usage instructions.
+
+## Bugs
+
+See CONTRIBUTING.rdoc for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
+
+## License
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual files and LEGAL.rdoc for details.
+
+RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.
+
+## Warranty
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.
diff --git a/README.rdoc b/README.rdoc
diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
@@ -1007,7 +1007,7 @@
 #     generates baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute].
 #   - Alias: <tt>bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]</tt>
 #     generates bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias].
-#   - File: <tt>README[rdoc-ref:README.rdoc]</tt> generates README[rdoc-ref:README.rdoc].
+#   - File: <tt>README[rdoc-ref:README.md]</tt> generates README[rdoc-ref:README.md].
 #
 #   If the referenced item does not exist, no link is generated
 #   and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed
@@ -1050,7 +1050,7 @@
 #
 # [<tt>link:</tt> Scheme]
 #
-#   - <tt>link:README_rdoc.html</tt> links to link:README_rdoc.html.
+#   - <tt>link:README_md.html</tt> links to link:README_md.html.
 #
 # [<tt>rdoc-image</tt> Scheme]
 #

diff --git a/lib/rdoc/ri/task.rb b/lib/rdoc/ri/task.rb
@@ -26,8 +26,8 @@
 #   require 'rdoc/ri/task'
 #
 #   RDoc::RI::Task.new do |ri|
-#     ri.main = 'README.rdoc'
-#     ri.rdoc_files.include 'README.rdoc', 'lib/**/*.rb'
+#     ri.main = 'README.md'
+#     ri.rdoc_files.include 'README.md', 'lib/**/*.rb'
 #   end
 #
 # For further configuration details see RDoc::Task.

diff --git a/lib/rdoc/task.rb b/lib/rdoc/task.rb
@@ -58,8 +58,8 @@
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new do |rdoc|
-#     rdoc.main = "README.rdoc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #   end
 #
 # The +rdoc+ object passed to the block is an RDoc::Task object. See the
@@ -74,8 +74,8 @@
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new :rdoc_dev do |rdoc|
-#     rdoc.main = "README.rdoc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #     rdoc.options << "--all"
 #   end
 #

diff --git a/rdoc.gemspec b/rdoc.gemspec
@@ -45,7 +45,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
     "History.rdoc",
     "LEGAL.rdoc",
     "LICENSE.rdoc",
-    "README.rdoc",
+    "README.md",
     "RI.md",
     "TODO.rdoc",
     "exe/rdoc",
@@ -60,7 +60,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
 
   s.files = (non_lib_files + template_files + lib_files).uniq
 
-  s.rdoc_options = ["--main", "README.rdoc"]
+  s.rdoc_options = ["--main", "README.md"]
   s.extra_rdoc_files += s.files.grep(%r[\A[^\/]+\.(?:rdoc|md)\z])
 
   s.required_ruby_version = Gem::Requirement.new(">= 2.6.0")