Forum: Ruby rdoc 4.0.0.preview2

rdoc version 4.0.0.preview2 has been released!

* home: https://github.com/rdoc/rdoc
* rdoc: http://docs.seattlerb.org/rdoc
* bugs: https://github.com/rdoc/rdoc/issues

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.

Changes:

=== 4.0.0.preview2

As a preview release, please file bugs for any problems you have with 
rdoc at
https://github.com/rdoc/rdoc/issues

RDoc 4.0 includes several new features and several breaking changes. 
The
changes should not affect users of `rdoc` or `ri`.

Notable feature additions are markdown support and an WEBrick servlet 
that can
serve HTML from an ri store.  (This means that RubyGems 2.0+ no longer 
needs
to build HTML documentation when installing gems.)

* Breaking changes
  * The default output encoding for RDoc is now UTF-8.  Previously RDoc 
used
    the default external encoding which was determined from your locale.
    Issue #106 by Justin Baker.
  * RDoc::RI::Store is now RDoc::Store so ri data generated by RDoc 4 
cannot
    be read by earlier versions of RDoc.  RDoc::RI::Store exists as an 
alias
    of RDoc::Store so ri data from older versions can still be read.
    RDoc::RI::Store will be removed in RDoc 5.

    Tests that create RDoc::CodeObjects on the fly without wiring them 
into
    the documentation tree (did not use add_class, add_method, etc.) 
must be
    updated to use these methods.  The documentation tree automatically
    attaches them to the store instance which allows lookups to work
    correctly.  Additionally, a new method RDoc::Store#add_file must be 
used
    instead of RDoc::TopLevel.new.  The latter will not be attached to 
the
    documentation tree.
  * RDoc generators must accept an RDoc::Store and an RDoc::Options in
    initialize.  RDoc no longer passes an Array of RDoc::TopLevel 
objects to
    #generate.  Use RDoc::Store#all_files instead.
  * Some markup formatters (RDoc::Markup::To*) now accept an 
RDoc::Options
    instance as the first argument.  Notably, the base class Formatter 
and
    ToHtml*.  (This is not universal due to the difficult at accessing 
the
    user's options instance deep inside RDoc.  A future major release 
may
    remedy this.)
  * Added new markup nodes and specials that RDoc::Markup::Formatter
    subclasses must handle.  If you're using 
RDoc::Markup::FormatterTestCase
    the new methods you need to add should be readily apparent.
  * Removed RDoc::RI::Paths::SYSDIR and ::SITEDIR.  These were hidden
    constants so no breakage is expected.  Use 
RDoc::RI::Paths::system_dir
    and ::site_dir instead.
  * RDoc::RI::Store#modules has been renamed to RDoc::Store#module_names
    to avoid confusion with RDoc::Store#all_modules imported from
    RDoc::TopLevel.
  * RDoc::RDocError has been removed.  It was deprecated throughout RDoc 
3.
  * ri -f html is no longer supported.
  * Comment definitions in C comments are now only discovered from the 
first
    line.  A colon on a subsequent line won't trigger definition 
extraction.
    Issue #103, see also
    http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/...
  * Fixed :stopdoc: for class A::B where A has not been seen.  Issue #95 
by
    Ryan Davis
  * RDoc::ClassModule#each_ancestor no longer yields itself if there is
    circular ancestry

* Major enhancements
  * ri can now show pages (README, etc.)

      ri rdoc:README

    Will show the README for the latest version of RDoc.  You can 
specify
    exact gem versions such as "rdoc-4.0:README" or view pages from the
    standard library documentation with "ruby:README".

    RDoc 3 did not save pages in ri data so you will need to regenerate
    documentation from your gems to use this feature.
  * Added Markdown as a supported format.  The markdown format can be 
set on a
    per-file or per-comment basis with the +:markdown:+ directive like 
the rd
    and tomdoc formats and on a per-project basis with
    <tt>rdoc --markup markdown --write-options</tt>
  * Removed global state from RDoc.  RDoc::Store holds the documentation 
tree
    and connects the driver to the parsers and generator.  This also 
allows
    documentation parsing and generation for multiple instances, but the 
rdoc
    command-line tool does not support this.

    Due to this change RDoc::RDoc.current and RDoc::RDoc.reset no longer
    exist.

* Minor enhancements
  * Added --root for building documentation from outside the source dir.
  * Added a table of contents to the sidebar.
  * RDoc markup format merges adjacent labels in a label or note list 
into a
    single definition list item for output.
  * RDoc now tracks use of extend.  Pull request #118 by Michael 
Granger.
  * RDoc now tracks methods that use super.  Pull request #116 by Erik
    Hollensbe.
  * Added methods ::system_dir, ::site_dir, ::home_dir and ::gem_dir to 
fetch
    the components of RDoc::RI::Paths.path individually.
  * Added support for rb_file_const.
  * RDoc now processes files in sorted order.  Issue #71 by Vt Ondruch
  * RDoc now warns with --verbose when methods are duplicated.  Issue 
#71 by
    Vt Ondruch
  * ri will display documentation for all methods in a class if -a is 
given.
    Issue #57 by casper
  * The RDoc coverage report will report line information for 
attributes,
    constants and methods missing documentation.  Issue #121 by Zachary 
Scott
  * RDoc now reports a warning for files that are unreadable due to
    permissions problems.
  * RDoc controls documentation generation for RubyGems 2.0+

* Bug fixes
  * A word that is directly followed by a multi-word tidy link label no 
longer
    disappears.  (Like <code>text{link}[http://example]</code>)
  * Fixed legacy template support.  Pull Request #107 by Justin Baker.
  * An HTML class in a verbatim section no longer triggers ruby parsing.
    Issue #92 by Vijay Dev
  * Improved documentation for setting the default documentation format 
for
    your ruby project.  Issue #94 by Henrik Hodne
  * Fixed handling of LANG in the RDoc::Options tests.  Issue #99 by Vt
    Ondruch
  * RDoc no longer quits when given an entry that is not a file or 
directory.
    Issue #101 by Charles Nutter
  * Fixed bug in syntax-highlighting that would corrupt regular 
expressions.
    Ruby Bug #6488 by Benny Lyne Amorsen.
  * "class Object" no longer appears in the coverage report if all its 
methods
    are documented.  This suppresses a false positive for libraries that 
add
    toplevel methods.  Pull Request #128 by Zachary Scott.
  * Fixed test_gen_url test name in TestRDocMarkupToHtml.  Pull Request 
#130
    by Zachary Scott.
  * Comment-defined methods ahead of define_method are now discovered. 
Issue
    #133 by eclectic923
  * Fixed detection of define_method documentation.  Issue #138 by 
Marvin
    Glker.
  * Fixed lexing of character syntax (<code>?z</code>).  Reported by 
Xavier
    Noria.
  * Add license to gem spec.  Issue #144 by pivotalcommon
  * Fixed comment selection for classes.  Pull request #146 by pioz
  * Fixed parsing of <code>def self.&() end</code>.  Issue #148 by 
Michael
    Lucy
  * Generated RD parser files are now included in the gem.  Issue #145 
by
    Marvin Glker
  * Class and module aliases now create new classes to avoid duplicate 
names
    in the class list.  Issue #143 by Richard Schneeman, Rails Issue 
#2839
  * RDoc::Markup::Parser now correctly matches indentation of lists when
    multibyte characters are used in the list labels.  Issue #140 by
    burningTyger
  * Fixed mangling of email addresses that look like labels.  Issue #129 
by
    Tobias Koch
  * Classes and modules in a C file may now be created in any order. 
Issue
    #124 by Su Zhang
  * A metaprogrammed method supports the :args: directive.  Issue #100
  * A metaprogrammed method supports the :yields: directive.
  * RDoc will now look for directives up to the end of the line.  For 
example,
      class B < A; end # :nodoc:
    will now hide documentation of B.  Issue #125 by Zachary Scott
  * Fixed tokenization of % when it is not followed by a $-string type
  * Fixed display of __END__ in documentation examples in HTML output
  * Fixed tokenization of reserved words used as new-style hash keys
  * RDoc now handles class << $gvar by ignoring the body
  * Fixed parsing of class A:: B.
  * Worked around bug in RDoc::RubyLex where tokens won't be 
reinterpreted
    after unget_tk.
  * Fixed class << ::Foo writing documentation to /Foo.html
  * Fixed class ::A referencing itself from inside its own namespace.

>
>
> Notable feature additions are markdown support and an WEBrick servlet that
> can
> serve HTML from an ri store.  (This means that RubyGems 2.0+ no longer
> needs
> to build HTML documentation when installing gems.)
>

Nice! I had a gem that did that, but it was quite the hack, so it was 
never
very useful. But I always seemed like a good idea. So I am pleased to 
see
that RDoc can now do it right out of the box.

Quick questions:

1. Can it browse multiple gems at once, or just one at a time?
2. Can it take advantage of custom formats?

Thanks.

On Dec 1, 2012, at 15:07, Intransition <transfire@gmail.com> wrote:

>> Notable feature additions are markdown support and an WEBrick servlet that can
>> serve HTML from an ri store.  (This means that RubyGems 2.0+ no longer needs
>> to build HTML documentation when installing gems.)
>
> Nice! I had a gem that did that, but it was quite the hack, so it was never very 
useful. But I always seemed like a good idea. So I am pleased to see that RDoc can 
now do it right out of the box.
>
> Quick questions:
>
> 1. Can it browse multiple gems at once, or just one at a time?

Multiple gems at once. At the top level you can type to filter on 
installed gems.

> 2. Can it take advantage of custom formats?

Currently it uses the darkish generator. Due to lack of time I haven't 
investigated alternate output templates. Allowing alternate output 
formats is possible before RDoc 4 final. The feature is rather coupled 
to darkish so I'm unsure what work would be needed for alternate 
generators. I'd rather delay that for a future release than rush it.

On Saturday, December 1, 2012 8:08:03 PM UTC-5, Eric Hodel wrote:
>
>
> Multiple gems at once. At the top level you can type to filter on
> installed gems.
>

Awesome!


>
> Currently it uses the darkish generator. Due to lack of time I haven't
> investigated alternate output templates. Allowing alternate output formats
> is possible before RDoc 4 final. The feature is rather coupled to darkish
> so I'm unsure what work would be needed for alternate generators. I'd
> rather delay that for a future release than rush it.
>

Yea, no need to rush. At least it's something to look forward to in a
future version :)

You've done a really great job with RDoc, Eric. I had drifted away into
YARD territory, but now I am felling all torn. RDoc has improved so much
over the last few years. Really great work.

REMOVE stephenp@agrussell.com

does not work here anymore.