Class: ReadmeYard

Inherits:
Object
  • Object
show all
Defined in:
lib/readme_yard.rb,
lib/readme_yard/error.rb,
lib/readme_yard/logger.rb,
lib/readme_yard/version.rb,
lib/readme_yard/object_tag.rb,
lib/readme_yard/readme_tag.rb,
lib/readme_yard/source_tag.rb,
lib/readme_yard/comment_tag.rb,
lib/readme_yard/example_tag.rb

Overview

Build a better README with YARD by generating it straight from the source.

This gem aims to minimize the effort needed to keep your README, documentation, and source code synced, useful, and correct.

Look at the README_YARD.md template for this project to see how it works. If you're reading the README, that means this text is here because the custom {@readme ReadmeYard} markdown tag is in README_YARD.md and readme build was run at the command line.

Here's the full documentation.

Defined Under Namespace

Classes: CommentTag, Error, ExampleTag, Logger, ObjectTag, ReadmeTag, SourceTag

Constant Summary collapse

TAG_CLASS_LOOKUP = 
{ "readme" => ReadmeTag,
"example" => ExampleTag,
"source" => SourceTag,
"comment" => CommentTag,
"object" => ObjectTag }.freeze
VERSION = 
"0.2.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ ReadmeYard

Returns a new instance of ReadmeYard.



72
73
74
75
 
# File 'lib/readme_yard.rb', line 72

def initialize
  @readme_path = "./README.md"
  @readme_yard_path = "./README_YARD.md"
end

Instance Attribute Details

#readme_path ⇒ Object

Returns the value of attribute readme_path.



77
78
79
 
# File 'lib/readme_yard.rb', line 77

def readme_path
  @readme_path
end

#readme_yard_path ⇒ Object

Returns the value of attribute readme_yard_path.



77
78
79
 
# File 'lib/readme_yard.rb', line 77

def readme_yard_path
  @readme_yard_path
end

Class Method Details

.call(arg, options) ⇒ Object

See Also:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/readme_yard.rb', line 47

def self.call(arg, options)
  readme_yard = ReadmeYard.new

  case arg
  when "build"
    readme_yard.build(options: options)
  when "doc"
    readme_yard.doc(options: options)
  else
    puts TTY::Markdown.parse(readme_yard.command_line_usage)
  end
rescue Error => e
  puts TTY::Markdown.parse(e.message)
end

.hello_world ⇒ Object

object

Examples:

ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"


40
41
42
 
# File 'lib/readme_yard.rb', line 40

def self.hello_world
  "Hello 🌎 🌍 🌏"
end

.lookup_tag_class(tag_name) ⇒ Object 



68
69
70
 
# File 'lib/readme_yard.rb', line 68

def self.lookup_tag_class(tag_name)
  TAG_CLASS_LOOKUP[tag_name]
end

Instance Method Details

#build(options: "-nq") ⇒ Object

Reads from README_YARD.md and writes to README.md

Forwards options to yardoc

-n only generate .yardoc database, no documentation.

-q silence yardoc output statements



108
109
110
111
112
 
# File 'lib/readme_yard.rb', line 108

def build(options: "-nq")
  find_or_upsert_yardopts
  run_yardoc(options: options)
  File.write(readme_path, gsub_tags!(readme_yard_md))
end

#command_line_usage ⇒ Object

This method returns the following @readme text

Command Line Usage

readme - Prints command line usage.

readme build - Reads from README_YARD.md and writes to README.md.

readme doc - Same as readme build + generates yard docs.



91
92
93
94
95
96
 
# File 'lib/readme_yard.rb', line 91

def command_line_usage
  yard_parse_this_file
  yard_object = YARD::Registry.at("#{self.class.name}##{__method__}")
  yard_tags = yard_object.tags(:readme)
  "\n#{ReadmeTag.format_markdown(yard_object, yard_tags)}\n\n"
end

#doc(options: "-q") ⇒ Object

Same as "build" + generates yard docs.



117
118
119
 
# File 'lib/readme_yard.rb', line 117

def doc(options: "-q")
  build(options: options || "-q")
end

#run_yardoc(options: "-nq") ⇒ Object 



121
122
123
 
# File 'lib/readme_yard.rb', line 121

def run_yardoc(options: "-nq")
  YARD::CLI::Yardoc.run(options || "-nq")
end