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, one that summarizes and contextualizes the code and documentation, without duplicating them.

This gem aims to minimize the effort needed to keep your code, docs, and README useful, syncd, and correct.

For a glimpse of how it works, check out the README_YARD.md template from which this gem's README was generated. If you're reading the README, that means this text is here because {@readme ReadmeYard} is in the README_YARD file and someone ran readme build 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.



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

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.



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

def readme_path
  @readme_path
end

#readme_yard_path ⇒ Object

Returns the value of attribute readme_yard_path.



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

def readme_yard_path
  @readme_yard_path
end

Class Method Details

.call(arg, options) ⇒ Object

See Also:



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

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

comment

Examples:

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


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

def self.hello_world
  "Hello 🌎 🌍 🌏"
end

.lookup_tag_class(tag_name) ⇒ Object 



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

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



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

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.



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

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.



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

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

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



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

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