Class: RDoc::Generator::Markdown

Inherits:
Object
  • Object
show all
Defined in:
lib/rdoc/generator/markdown.rb

Overview

Generates Markdown output and a CSV search index from an RDoc store.

Defined Under Namespace

Modules: OptionsExtension

Constant Summary collapse

MARKDOWN_UNKNOWN_TAGS =

Supported reverse_markdown unknown-tag modes.

%i[pass_through drop bypass raise]
ROOT_PAGES =

Root source page basenames and their search-index types.

{
  "readme" => "Readme",
  "guide" => "Readme",
  "changelog" => "Changelog",
  "history" => "Changelog"
}
ROOT_PAGE_EXTENSIONS =

Source page extensions eligible for root page classification.

%w[.rdoc .md .markdown]
TEMPLATE_DIR =

Directory containing ERB templates.

File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "templates"))

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(store, rdoc_options) ⇒ Markdown

Creates a generator for an RDoc store and options.

Parameters:

  • store (RDoc::Store) —

    Source documentation store.

  • rdoc_options (RDoc::Options) —

    Generator options.



140
141
142
143
144
145
146
147
 
# File 'lib/rdoc/generator/markdown.rb', line 140

def initialize(store, rdoc_options)
  @store = store
  @options = rdoc_options
  @markdown_unknown_tags = self.class.validate_markdown_unknown_tags(rdoc_options.markdown_unknown_tags)

  @base_dir = Pathname.pwd
  @expanded_root = Pathname(@options.root.to_s).expand_path
end

Instance Attribute Details

#base_dir ⇒ Pathname (readonly)

Working directory captured when the generator is created.

Returns:

  • (Pathname) 


115
116
117
 
# File 'lib/rdoc/generator/markdown.rb', line 115

def base_dir
  @base_dir
end

#classes ⇒ Array<RDoc::Context>? (readonly)

Classes and modules selected for output.

Returns:

  • (Array<RDoc::Context>, nil) 


120
121
122
 
# File 'lib/rdoc/generator/markdown.rb', line 120

def classes
  @classes
end

#pages ⇒ Array<RDoc::TopLevel>? (readonly)

Text files selected for output.

Returns:

  • (Array<RDoc::TopLevel>, nil) 


125
126
127
 
# File 'lib/rdoc/generator/markdown.rb', line 125

def pages
  @pages
end

#store ⇒ RDoc::Store (readonly)

Source store for generated content.

Returns:

  • (RDoc::Store) 


110
111
112
 
# File 'lib/rdoc/generator/markdown.rb', line 110

def store
  @store
end

Class Method Details

.root_page_type_for(source_path) ⇒ String?

Returns the configured search-index type for an eligible root text page path.

Parameters:

  • source_path (String) —

    Normalized source path relative to the root.

Returns:

  • (String, nil) 


37
38
39
40
41
42
 
# File 'lib/rdoc/generator/markdown.rb', line 37

def self.root_page_type_for(source_path)
  return unless File.dirname(source_path) == "."
  return unless ROOT_PAGE_EXTENSIONS.include?(File.extname(source_path))

  ROOT_PAGES[File.basename(source_path, ".*").downcase]
end

.setup_options(rdoc_options) ⇒ void

This method returns an undefined value.

Registers markdown generator-specific RDoc options.

Parameters:



85
86
87
88
89
90
91
92
 
# File 'lib/rdoc/generator/markdown.rb', line 85

def self.setup_options(rdoc_options)
  rdoc_options.option_parser.on(
    "--markdown-unknown-tags=MODE",
    "How to handle unknown HTML tags: #{MARKDOWN_UNKNOWN_TAGS.join(", ")}."
  ) do |value|
    rdoc_options.markdown_unknown_tags = value.to_sym
  end
end

.validate_markdown_unknown_tags(value) ⇒ Symbol

Validates the configured reverse_markdown unknown-tag mode.

Parameters:

  • value (Symbol) —

    Unknown-tag mode.

Returns:

  • (Symbol) —

    Validated unknown-tag mode.

Raises:

  • (OptionParser::InvalidArgument) 


99
100
101
102
103
104
105
 
# File 'lib/rdoc/generator/markdown.rb', line 99

def self.validate_markdown_unknown_tags(value)
  return value if MARKDOWN_UNKNOWN_TAGS.include?(value)

  expected = MARKDOWN_UNKNOWN_TAGS.map { |mode| ":#{mode}" }.join(", ")
  raise OptionParser::InvalidArgument,
    "invalid markdown_unknown_tags: #{value.inspect} (expected one of: #{expected})"
end

Instance Method Details

#class_dir ⇒ nil Also known as: file_dir

Required by RDoc's generator interface; markdown output has no class subdirectory.

Returns:

  • (nil) 


130
131
 
# File 'lib/rdoc/generator/markdown.rb', line 130

def class_dir
end

#generate ⇒ void

This method returns an undefined value.

Writes class files, page files, and the search index.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/rdoc/generator/markdown.rb', line 152

def generate
  debug("Setting things up ")

  setup

  debug("Generate documentation in #{@output_dir}")

  emit_classfiles

  debug("Generate pages in #{@output_dir}")

  emit_pagefiles

  debug("Generate index file in #{@output_dir}")

  emit_csv_index
end