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.



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

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) 


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

def base_dir
  @base_dir
end

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

Classes and modules selected for output.

Returns:

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


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

def classes
  @classes
end

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

Text files selected for output.

Returns:

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


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

def pages
  @pages
end

#store ⇒ RDoc::Store (readonly)

Source store for generated content.

Returns:

  • (RDoc::Store) 


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

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:



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

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) 


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

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) 


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

def class_dir
end

#generate ⇒ void

This method returns an undefined value.

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



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

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