diff --git a/.rdoc_options b/.rdoc_options index 40495cffd9..2a7a20f0ff 100644 --- 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 new file mode 100644 index 0000000000..fcabeeb259 --- /dev/null +++ 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 deleted file mode 100644 index c4b60b29c0..0000000000 --- a/README.rdoc +++ /dev/null @@ -1,144 +0,0 @@ -= \RDoc - Ruby Documentation System - -home :: https://github.com/ruby/rdoc -rdoc :: https://ruby.github.io/rdoc -bugs :: https://github.com/ruby/rdoc/issues -code quality :: https://codeclimate.com/github/ruby/rdoc - -== 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 - - $ rdoc [options] [names...] - -For an up-to-date option summary, type - - $ rdoc --help - -A typical use might be to generate documentation for a package of Ruby -source (such as RDoc itself). - - $ 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 - - % rdoc --main README.rdoc - -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: - - gem 'rdoc' - 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 as an example. - -== Writing Documentation - -To write documentation for RDoc place a comment above the class, module, -method, constant, or attribute you want documented: - - ## - # 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[rdoc-ref:RDoc::TomDoc], Markdown[rdoc-ref:RDoc::Markdown] and -RD[rdoc-ref:RDoc::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/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 77a6d7593b..556c446d54 100644 --- 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: bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] # generates bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]. -# - File: README[rdoc-ref:README.rdoc] generates README[rdoc-ref:README.rdoc]. +# - File: README[rdoc-ref:README.md] generates README[rdoc-ref:README.md]. # # If the referenced item does not exist, no link is generated # and entire rdoc-ref: square-bracketed clause is removed @@ -1050,7 +1050,7 @@ # # [link: Scheme] # -# - link:README_rdoc.html links to link:README_rdoc.html. +# - link:README_md.html links to link:README_md.html. # # [rdoc-image Scheme] # diff --git a/lib/rdoc/ri/task.rb b/lib/rdoc/ri/task.rb index e66b9d2bb6..214ac62208 100644 --- 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 index f558cb0cfd..a444fe5281 100644 --- 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 index 486b938b61..25d18e04d6 100644 --- 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") diff --git a/test/rdoc/rdoc_ri_driver_test.rb b/test/rdoc/rdoc_ri_driver_test.rb index 1cb459909a..a0c4d809a7 100644 --- a/test/rdoc/rdoc_ri_driver_test.rb +++ b/test/rdoc/rdoc_ri_driver_test.rb @@ -258,7 +258,7 @@ def test_add_method_with_rdoc_ref_link para("(from #{@rdoc_home})"), head(3, 'Implementation from Bar'), rule(1), - verb("blah(5) => 5\n", "See also {Doc}[rdoc-ref:README.rdoc]\n"), + verb("blah(5) => 5\n", "See also {Doc}[rdoc-ref:README.md]\n"), rule(1), blank_line, blank_line @@ -653,9 +653,9 @@ def test_display_class_all assert_match %r%Foo::Bar#blah%, out assert_match %r%Foo::Bar#blah_with_rdoc_ref%, out # From Foo::Bar and Foo::Bar#blah_with_rdoc_ref - assert_equal 2, out.scan(/rdoc-ref:README.rdoc/).length - # But README.rdoc should only be displayed once - assert_equal 1, out.scan(/Expanded from README.rdoc/).length + assert_equal 2, out.scan(/rdoc-ref:README.md/).length + # But README.md should only be displayed once + assert_equal 1, out.scan(/Expanded from README.md/).length end def test_rdoc_refs_expansion_can_be_disabled @@ -668,9 +668,9 @@ def test_rdoc_refs_expansion_can_be_disabled end # From Foo::Bar - assert_equal 1, out.scan(/rdoc-ref:README.rdoc/).length - # But README.rdoc should not be expanded - assert_empty out.scan(/Expanded from README.rdoc/) + assert_equal 1, out.scan(/rdoc-ref:README.md/).length + # But README.md should not be expanded + assert_empty out.scan(/Expanded from README.md/) end def test_display_class_ambiguous @@ -773,7 +773,7 @@ def test_display_name util_store out, = capture_output do - assert_equal true, @driver.display_name('home:README.rdoc') + assert_equal true, @driver.display_name('home:README.md') end expected = <<-EXPECTED @@ -841,7 +841,7 @@ def test_display_page util_store out, = capture_output do - @driver.display_page 'home:README.rdoc' + @driver.display_page 'home:README.md' end assert_match %r%= README%, out @@ -874,7 +874,6 @@ def test_display_page_ambiguous end assert_match %r%= README pages in #{@rdoc_home}%, out - assert_match %r%README\.rdoc%, out assert_match %r%README\.md%, out end @@ -928,7 +927,7 @@ def test_display_page_missing end assert_match %r%= Pages in #{@rdoc_home}%, out - assert_match %r%README\.rdoc%, out + assert_match %r%README\.md%, out end def test_display_page_list @@ -948,7 +947,7 @@ def test_display_page_list end assert_match %r%= Pages in #{@rdoc_home}%, out - assert_match %r%README\.rdoc%, out + assert_match %r%README\.md%, out assert_match %r%OTHER\.rdoc%, out end @@ -1543,7 +1542,7 @@ def util_store @top_level = @store1.add_file 'file.rb' - @readme = @store1.add_file 'README.rdoc' + @readme = @store1.add_file 'README.md' @readme.parser = RDoc::Parser::Simple @readme.comment = RDoc::Comment.from_document(doc(head(1, 'README'), para('This is a README'))) @@ -1560,7 +1559,7 @@ def util_store @cFooInc.record_location @top_level @cFoo_Bar = @cFoo.add_class RDoc::NormalClass, 'Bar' - @cFoo_Bar.add_comment "See also {Doc}[rdoc-ref:README.rdoc]", @top_level + @cFoo_Bar.add_comment "See also {Doc}[rdoc-ref:README.md]", @top_level @cFoo_Bar.record_location @top_level @blah = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'blah') @@ -1568,7 +1567,7 @@ def util_store @blah.record_location @top_level @blah_with_rdoc_ref = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'blah_with_rdoc_ref') - @blah_with_rdoc_ref.call_seq = "blah(5) => 5\nSee also {Doc}[rdoc-ref:README.rdoc]" + @blah_with_rdoc_ref.call_seq = "blah(5) => 5\nSee also {Doc}[rdoc-ref:README.md]" @blah_with_rdoc_ref.record_location @top_level @bother = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'bother') diff --git a/test/rdoc/rdoc_servlet_test.rb b/test/rdoc/rdoc_servlet_test.rb index 825abdf4ab..0d9da1b727 100644 --- a/test/rdoc/rdoc_servlet_test.rb +++ b/test/rdoc/rdoc_servlet_test.rb @@ -231,9 +231,9 @@ def test_documentation_page_page generator = @s.generator_for store - store.add_file 'README.rdoc', parser: RDoc::Parser::Simple + store.add_file 'README.md', parser: RDoc::Parser::Simple - @s.documentation_page store, generator, 'README_rdoc.html', @req, @res + @s.documentation_page store, generator, 'README_md.html', @req, @res assert_match %r%README - %, @res.body assert_match %r%]+ class="file">%, @res.body @@ -244,9 +244,9 @@ def test_documentation_page_page_with_nesting generator = @s.generator_for store - store.add_file 'nesting/README.rdoc', parser: RDoc::Parser::Simple + store.add_file 'nesting/README.md', parser: RDoc::Parser::Simple - @s.documentation_page store, generator, 'nesting/README_rdoc.html', @req, @res + @s.documentation_page store, generator, 'nesting/README_md.html', @req, @res assert_equal 200, @res.status end