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/code_tag.rb,
lib/readme_yard/value_tag.rb,
lib/readme_yard/readme_tag.rb,
lib/readme_yard/source_tag.rb,
lib/readme_yard/string_tag.rb,
lib/readme_yard/comment_tag.rb,
lib/readme_yard/example_tag.rb,
lib/readme_yard/tag_registry.rb,
lib/readme_yard/yard_opts_manager.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. Among its features, it introduces the @readme tag that enables you to embed code comments directly into README sections, eliminating redundancy and keeping documentation consistent across your codebase and project README.

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.

Defined Under Namespace

Classes: CodeTag, CommentTag, Error, ExampleTag, Logger, ReadmeTag, SourceTag, StringTag, TagRegistry, ValueTag, YardOptsManager

Constant Summary collapse

VERSION = 
"0.5.0"
DOCS_URL = 
"https://mattruzicka.github.io/readme_yard/"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ ReadmeYard

Returns a new instance of ReadmeYard.



61
62
63
64
 
# File 'lib/readme_yard.rb', line 61

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.



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

def readme_path
  @readme_path
end

#readme_yard_path ⇒ Object

Returns the value of attribute readme_yard_path.



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

def readme_yard_path
  @readme_yard_path
end

Class Method Details

.call(arg, options) ⇒ Object

See Also:



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

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

  case arg
  when "build"
    readme_yard.build(options: options)
  when "yard"
    readme_yard.yard(options: options)
  when "version"
    Logger.puts_md(VERSION)
  else
    Logger.puts_md(readme_yard.command_line_usage)
  end
rescue Error => e
  Logger.puts_md(e.message)
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



101
102
103
104
105
106
107
 
# File 'lib/readme_yard.rb', line 101

def build(options: "-nq")
  YARD::CLI::Yardoc.run(options || "-nq")
  old_readme = File.exist?(readme_path) ? File.read(readme_path) : ""
  new_readme = gsub_tags!(readme_yard_md)
  File.write(readme_path, new_readme)
  show_readme_diff(old_readme, new_readme)
end

#command_line_usage ⇒ Object

This unnecessarily meta method returns the @readme text you see below (if you're reading this in the source code). It was implemented just for fun as a demonstration of @readme tags.

Command Line Usage

readme - Prints command line usage.

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

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

readme version - Prints the current version of ReadmeYard.



84
85
86
87
88
89
 
# File 'lib/readme_yard.rb', line 84

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_tags(yard_object, yard_tags)}\n\n"
end

#yard(options: "") ⇒ Object

Same as "build" + generates yard `docs.



112
113
114
115
 
# File 'lib/readme_yard.rb', line 112

def yard(options: "")
  YardOptsManager.upsert_yardopts
  build(options: options || "")
end