Rdoc 3.10 Released

RDoc produces HTML and command-line documentation for Ruby projects.
RDoc
includes the +rdoc+ and +ri+ tools for generating and displaying online
documentation.

See RDoc for a description of RDoc’s markup and basic use.

Changes:

=== 3.10 / 2011-10-08

  • Major enhancements

    • RDoc HTML output has been improved:

      • The search from Володя Колесников’s (Vladimir Kolesnikov) Sdoc has
        been
        integrated.

        The search index generation is a reusable component through
        RDoc::Generator::JsonIndex

      • The table of contents is now a separate page and now shows links
        to
        headings and sections inside a page or class.

      • Class pages no longer show the namespace and no longer have file
        info
        pages.

      • HTML output is HTML 5.

      • Static files can be copied into RDoc using --copy-files

    • RDoc supports additional documentation formats:

      • TomDoc 1.0.0-rc1
      • RD format

      The default markup can be set via the –markup option.

      The format of documentation in a particular file can be specified by
      the
      +:markup:+ directive. If the +:markup:+ directive is in the first
      comment
      it is used as the default for the entire file. For other comments
      it
      overrides the default markup format.

      The markup format can be set for rake tasks using RDoc::Task#markup

    • RDoc can save and load an options file.

      To create an options file that defaults to using TomDoc markup run:

      rdoc --markup tomdoc --write-options

      This will create a .rdoc_options file. Check it in to your VCS and
      package it with your gem. RDoc will automatically load this file
      and
      combine it with the user’s options.

      Some options are not saved. See RDoc::[email protected]+Options for
      full
      details.

  • Minor enhancements

    • RDoc autoloads everything. You only need to require ‘rdoc’ now.

    • HTML headings now have ids matching their titles.

      = Hello!

      Is rendered as

      Hello!

    • Labels for classes or methods can be linked-to by adding an
      @
      following the class or method reference. For example,
      RDoc::[email protected]

      See RDoc::[email protected] for further details.

    • For HTML output RDoc uses +SomeClass.method_name+ and
      +SomeClass#method_name+ for remote methods and attributes and
      +::method_name+ and +#method_name+ for local methods.

    • RDoc makes an effort to syntax-highlight ruby code in verbatim
      sections.
      See RDoc::[email protected]+and+Verbatim

    • Added RDoc::TopLevel#text? and RDoc::Parser::Text to indicate a
      parsed file contains no ruby constructs.

    • Added rdoc-label link scheme which allows bidirectional
      links.
      See RDoc::Markup for details.

    • Image paths at HTTPS URLs will now be turned into ++ tags.
      Pull
      Request #60 by James M.

    • Added RDoc::Comment which encapsulates comment-handling
      functionality.

    • Added RDoc::Markup::PreProcess::post_process to allow arbitrary
      comment
      munging.

    • RDoc::RDoc::current is set for the entire RDoc run.

    • Split rdoc/markup/inline into individual files for its component
      classes.

    • Moved token stream HTML markup out of RDoc::AnyMethod#markup_code
      into
      RDoc::TokenStream::to_html

    • “Top” link in section headers is no longer inside the heading
      element.

    • RDoc avoids printing some warnings unless run with rdoc --verbose.
      For
      Rails issue #1646.

    • Finishing a paragraph with two or more spaces will result in a line
      break.
      This feature is experimental and may be modified or removed.

  • Bug fixes

    • Markup defined by RDoc::Markup#add_special inside a is
      no
      longer converted.
    • Performance of RDoc::RubyLex has been improved. Ruby Bug #5202 by
      Ryan
      Melton.
    • Add US-ASCII magic comments to work with ruby -Ku. Issue
      #63 by
      Travis D. Warlick, Jr.
    • Clicking a link in the method description now works. Issue #61 by
      Alan
      Hogan.
    • Fixed RDoc::Markup::Parser for CRLF line endings. Issue #67 by
      Marvin
      Gülker.
    • Fixed lexing of percent strings like %r{#}. Issue #68 by
      eclectic923.
    • The C parser now understands classes defined with
      +rb_struct_define_without_accessor+ (like Range). Pull Request #73
      by Dan
      Bernier
    • Fixed lexing of a b <<-HEREDOC. Issue #75 by John
      Mair.
    • Added LEGAL.rdoc with references to licenses in other files. Issue
      #78 by
      Dmitry Jemerov.
    • Block parameters are displayed in Darkfish output again. Issue #76
      by
      Andrea Singh.
    • The method parameter coverage report no longer includes parameter
      default
      values. Issue #77 by Jake Goulding.
    • The module for an include is not looked up until parsed all the
      files are
      parsed. Unless your project includes nonexistent modules this
      avoids
      worst-case behavior (O(n!)) of RDoc::Include#module.

On Oct 8, 7:19 pm, Eric H. [email protected] wrote:

  headings and sections inside a page or class.
* Class pages no longer show the namespace and no longer have file info
  pages.
* HTML output is HTML 5.
* Static files can be copied into RDoc using --copy-files
  • RDoc supports additional documentation formats:
    • TomDoc 1.0.0-rc1
    • RD format

Some really great enhancements. Nice work.

On Oct 24, 2011, at 08:26 , Matt N. wrote:

Those nonsensical-looking, repeated “mtch” should be mtch[0], mtch[1],
mtch[2] etc., but the [n] is getting eaten and turned into a false
hyperlink.

I pointed this out via email to James B., who confirms that this
might be something RDoc is doing; is that possible? If so, is a fix
possible? (Perhaps not, since this might just be a source code comment
that wasn’t expecting RDoc to come along and try to reformat as HTML…)

Please file a bug on github.com/rdoc/rdoc. Thanks.

Eric H. [email protected] wrote:

RDoc produces HTML and command-line documentation for Ruby projects. RDoc
includes the +rdoc+ and +ri+ tools for generating and displaying online
documentation.

See RDoc for a description of RDoc’s markup and basic use.

Take a peek at this page:

http://ruby-doc.org/core-1.8.7/MatchData.html

Look at the first instance method, #[]:

?mtch is equivalent to the special variable $&, and returns the entire
matched string. mtch, mtch, and so on return the values of the matched
backreferences "

Those nonsensical-looking, repeated “mtch” should be mtch[0], mtch[1],
mtch[2] etc., but the [n] is getting eaten and turned into a false
hyperlink.

I pointed this out via email to James B., who confirms that this
might be something RDoc is doing; is that possible? If so, is a fix
possible? (Perhaps not, since this might just be a source code comment
that wasn’t expecting RDoc to come along and try to reformat as HTML…)

m.

On Oct 24, 2011, at 8:26 AM, Matt N. wrote:

Those nonsensical-looking, repeated “mtch” should be mtch[0], mtch[1],
mtch[2] etc., but the [n] is getting eaten and turned into a false
hyperlink.

I pointed this out via email to James B., who confirms that this
might be something RDoc is doing; is that possible? If so, is a fix
possible? (Perhaps not, since this might just be a source code comment
that wasn’t expecting RDoc to come along and try to reformat as HTML…)

Perhaps, please file a bug as Ryan said so I can look into a fix.

In the mean time I’ve changed the markup:

http://redmine.ruby-lang.org/projects/ruby-trunk/repository/revisions/33522

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs