In Files

  • rdoc/options.rb

Files

Class/Module Index [+]

Quicksearch

RDoc::Options

Attributes

all_one_file[R]

Should the output be placed into a single file

charset[R]

Character-set

css[R]

URL of stylesheet

diagram[R]

Should diagrams be drawn

exclude[RW]

Files matching this pattern will be excluded

extra_accessor_flags[R]

Additional attr_… style method flags

extra_accessors[RW]

Pattern for additional attr_… style methods

fileboxes[R]

Should we draw fileboxes in diagrams

files[RW]

The list of files to be processed

force_update[R]

Scan newer sources than the flag file if true.

formatter[RW]

Formatter to mark up text with

generator[RW]

Description of the output generator (set with the -fmt option)

image_format[R]

image format for diagrams

include_line_numbers[R]

Include line numbers in the source listings

inline_source[RW]

Should source code be included inline, or displayed in a popup

main_page[RW]

Name of the file, class or module to display in the initial index page (if not specified the first file we encounter is used)

merge[R]

Merge into classes of the same name when generating ri

op_dir[RW]

The name of the output directory

op_name[RW]

The name to use for the output

promiscuous[R]

Are we promiscuous about showing module contents across multiple files

rdoc_include[R]

Array of directories to search for files to satisfy an :include:

show_all[RW]

Include private and protected methods in the output

show_hash[R]

Include the ‘#’ at the front of hyperlinked instance method names

tab_width[R]

The number of columns in a tab

template[R]

template to be used when generating output

title[R]

Documentation title

verbosity[RW]

Verbosity, zero means quiet

webcvs[R]

URL of web cvs frontend

Public Instance Methods

parse(argv) click to toggle source

Parse command line options.

 
               # File rdoc/options.rb, line 193
  def parse(argv)
    accessors = []

    opts = OptionParser.new do |opt|
      opt.program_name = File.basename $0
      opt.version = RDoc::VERSION
      opt.release = nil
      opt.summary_indent = ' ' * 4
      opt.banner = <<-EOF
Usage: #{opt.program_name} [options] [names...]

  Files are parsed, and the information they contain collected, before any
  output is produced. This allows cross references between all files to be
  resolved. If a name is a directory, it is traversed. If no names are
  specified, all Ruby files in the current directory (and subdirectories) are
  processed.

  How RDoc generates output depends on the output formatter being used, and on
  the options you give.

  - HTML output is normally produced into a number of separate files
    (one per class, module, and file, along with various indices).
    These files will appear in the directory given by the --op
    option (doc/ by default).

  - XML output by default is written to standard output. If a
    --opname option is given, the output will instead be written
    to a file with that name in the output directory.

  - .chm files (Windows help files) are written in the --op directory.
    If an --opname parameter is present, that name is used, otherwise
    the file will be called rdoc.chm.
      EOF

      opt.separator nil
      opt.separator "Options:"
      opt.separator nil

      opt.on("--accessor=ACCESSORS", "-A", Array,
             "A comma separated list of additional class",
             "methods that should be treated like",
             "'attr_reader' and friends.",
             " ",
             "Option may be repeated.",
             " ",
             "Each accessorname may have '=text'",
             "appended, in which case that text appears",
             "where the r/w/rw appears for normal.",
             "accessors") do |value|
        value.each do |accessor|
          if accessor =~ /^(\w+)(=(.*))?$/
            accessors << $1
            @extra_accessor_flags[$1] = $3
          end
        end
      end

      opt.separator nil

      opt.on("--all", "-a",
             "Include all methods (not just public) in",
             "the output.") do |value|
        @show_all = value
      end

      opt.separator nil

      opt.on("--charset=CHARSET", "-c",
             "Specifies the output HTML character-set.") do |value|
        @charset = value
      end

      opt.separator nil

      opt.on("--debug", "-D",
             "Displays lots on internal stuff.") do |value|
        $DEBUG_RDOC = value
      end

      opt.separator nil

      opt.on("--diagram", "-d",
             "Generate diagrams showing modules and",
             "classes. You need dot V1.8.6 or later to",
             "use the --diagram option correctly. Dot is",
             "available from http://graphviz.org") do |value|
        check_diagram
        @diagram = true
      end

      opt.separator nil

      opt.on("--exclude=PATTERN", "-x", Regexp,
             "Do not process files or directories",
             "matching PATTERN.") do |value|
        @exclude << value
      end

      opt.separator nil

      opt.on("--extension=NEW=OLD", "-E",
             "Treat files ending with .new as if they",
             "ended with .old. Using '-E cgi=rb' will",
             "cause xxx.cgi to be parsed as a Ruby file.") do |value|
        new, old = value.split(/=/, 2)

        unless new and old then
          raise OptionParser::InvalidArgument, "Invalid parameter to '-E'"
        end

        unless RDoc::ParserFactory.alias_extension old, new then
          raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
        end
      end

      opt.separator nil

      opt.on("--fileboxes", "-F",
             "Classes are put in boxes which represents",
             "files, where these classes reside. Classes",
             "shared between more than one file are",
             "shown with list of files that are sharing",
             "them. Silently discarded if --diagram is",
             "not given.") do |value|
        @fileboxes = value
      end

      opt.separator nil

      opt.on("--force-update", "-U",
             "Forces rdoc to scan all sources even if",
             "newer than the flag file.") do |value|
        @force_update = value
      end

      opt.separator nil

      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
             "Set the output formatter.") do |value|
        @generator_name = value.downcase
        setup_generator
      end

      opt.separator nil

      image_formats = %w[gif png jpg jpeg]
      opt.on("--image-format=FORMAT", "-I", image_formats,
             "Sets output image format for diagrams. Can",
             "be #{image_formats.join ', '}. If this option",
             "is omitted, png is used. Requires",
             "diagrams.") do |value|
        @image_format = value
      end

      opt.separator nil

      opt.on("--include=DIRECTORIES", "-i", Array,
             "set (or add to) the list of directories to",
             "be searched when satisfying :include:",
             "requests. Can be used more than once.") do |value|
        @rdoc_include.concat value.map { |dir| dir.strip }
      end

      opt.separator nil

      opt.on("--inline-source", "-S",
             "Show method source code inline, rather than",
             "via a popup link.") do |value|
        @inline_source = value
      end

      opt.separator nil

      opt.on("--line-numbers", "-N",
             "Include line numbers in the source code.") do |value|
        @include_line_numbers = value
      end

      opt.separator nil

      opt.on("--main=NAME", "-m",
             "NAME will be the initial page displayed.") do |value|
        @main_page = value
      end

      opt.separator nil

      opt.on("--merge", "-M",
             "When creating ri output, merge previously",
             "processed classes into previously",
             "documented classes of the same name.") do |value|
        @merge = value
      end

      opt.separator nil

      opt.on("--one-file", "-1",
             "Put all the output into a single file.") do |value|
        @all_one_file = value
        @inline_source = value if value
        @template = 'one_page_html'
      end

      opt.separator nil

      opt.on("--op=DIR", "-o",
             "Set the output directory.") do |value|
        @op_dir = value
      end

      opt.separator nil

      opt.on("--opname=NAME", "-n",
             "Set the NAME of the output. Has no effect",
             "for HTML.") do |value|
        @op_name = value
      end

      opt.separator nil

      opt.on("--promiscuous", "-p",
             "When documenting a file that contains a",
             "module or class also defined in other",
             "files, show all stuff for that module or",
             "class in each files page. By default, only",
             "show stuff defined in that particular file.") do |value|
        @promiscuous = value
      end

      opt.separator nil

      opt.on("--quiet", "-q",
             "Don't show progress as we parse.") do |value|
        @verbosity = 0
      end

      opt.on("--verbose", "-v",
             "Display extra progress as we parse.") do |value|
        @verbosity = 2
      end


      opt.separator nil

      opt.on("--ri", "-r",
             "Generate output for use by `ri`. The files",
             "are stored in the '.rdoc' directory under",
             "your home directory unless overridden by a",
             "subsequent --op parameter, so no special",
             "privileges are needed.") do |value|
        @generator_name = "ri"
        @op_dir = RDoc::RI::Paths::HOMEDIR
        setup_generator
      end

      opt.separator nil

      opt.on("--ri-site", "-R",
             "Generate output for use by `ri`. The files",
             "are stored in a site-wide directory,",
             "making them accessible to others, so",
             "special privileges are needed.") do |value|
        @generator_name = "ri"
        @op_dir = RDoc::RI::Paths::SITEDIR
        setup_generator
      end

      opt.separator nil

      opt.on("--ri-system", "-Y",
             "Generate output for use by `ri`. The files",
             "are stored in a site-wide directory,",
             "making them accessible to others, so",
             "special privileges are needed.  This",
             "option is intended to be used during Ruby",
             "installation.") do |value|
        @generator_name = "ri"
        @op_dir = RDoc::RI::Paths::SYSDIR
        setup_generator
      end

      opt.separator nil

      opt.on("--show-hash", "-H",
             "A name of the form #name in a comment is a",
             "possible hyperlink to an instance method",
             "name. When displayed, the '#' is removed",
             "unless this option is specified.") do |value|
        @show_hash = value
      end

      opt.separator nil

      opt.on("--style=URL", "-s",
             "Specifies the URL of a separate stylesheet.") do |value|
        @css = value
      end

      opt.separator nil

      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
             "Set the width of tab characters.") do |value|
        @tab_width = value
      end

      opt.separator nil

      opt.on("--template=NAME", "-T",
             "Set the template used when generating",
             "output.") do |value|
        @template = value
      end

      opt.separator nil

      opt.on("--title=TITLE", "-t",
             "Set TITLE as the title for HTML output.") do |value|
        @title = value
      end

      opt.separator nil

      opt.on("--webcvs=URL", "-W",
             "Specify a URL for linking to a web frontend",
             "to CVS. If the URL contains a '\%s', the",
             "name of the current file will be",
             "substituted; if the URL doesn't contain a",
             "'\%s', the filename will be appended to it.") do |value|
        @webcvs = value
      end
    end

    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']

    opts.parse! argv

    @files = argv.dup

    @rdoc_include << "." if @rdoc_include.empty?

    if @exclude.empty? then
      @exclude = nil
    else
      @exclude = Regexp.new(@exclude.join("|"))
    end

    check_files

    # If no template was specified, use the default template for the output
    # formatter

    @template ||= @generator_name

    # Generate a regexp from the accessors
    unless accessors.empty? then
      re = '^(' + accessors.map { |a| Regexp.quote a }.join('|') + ')$'
      @extra_accessors = Regexp.new re
    end

  rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
    puts opts
    puts
    puts e
    exit 1
  end
            
quiet() click to toggle source

Don’t display progress as we process the files

 
               # File rdoc/options.rb, line 570
def quiet
  @verbosity.zero?
end
            
quiet=(bool) click to toggle source
 
               # File rdoc/options.rb, line 574
def quiet=(bool)
  @verbosity = bool ? 0 : 1
end
            
title=(string) click to toggle source

Set the title, but only if not already set. This means that a title set from the command line trumps one set in a source file

 
               # File rdoc/options.rb, line 563
def title=(string)
  @title ||= string
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus