readme_yard 0.2.0 → 0.4.0

data/README_YARD.md

@@ -1,18 +1,29 @@
 # Readme Yard 🌿
 [![Gem Version](https://badge.fury.io/rb/readme_yard.svg)](https://badge.fury.io/rb/readme_yard)
-[![Maintainability](https://api.codeclimate.com/v1/badges/9fe0012930c3886dbe00/maintainability)](https://codeclimate.com/github/mattruzicka/readme_yard/maintainability)
+
+**Code Version: {@string ReadmeYard::VERSION}**
 
 {@readme ReadmeYard}
 
 ---
 
+⚠️ **Generated file warning** – Edit README_YARD.md, not README.md. Changes to README.md will be lost when running `readme build`.
+
+### Future Work
+- Implement safeguards to prevent accidental edits to README.md
+- Support bidirectional editing through git integration
+
+[PRs are welcome](#contributing) for these improvements.
+
+---
+
 ## Table of Contents
 - [Installation](#installation)
 - [Getting Started](#getting-started)
 - [Command Line Usage](#command-line-usage)
 - [Tag Usage](#tag-usage)
 - [Readme Tag](#readme-tag)
-- [Readme YARD Tags](#readme-yard-tags)
+- [Standalone Tag Usage](#standalone-tag-usage)
 - [Example Tag](#example-tag)
 - [Contributing](#contributing)
 
@@ -20,13 +31,17 @@
 
 ## Installation
 
-Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your application's Gemfile and run `bundle install` or install it yourself with: `gem install readme_yard`
+Add [gem "readme_yard"](https://rubygems.org/gems/readme_yard) to your Gemfile and run `bundle install` or install it yourself with: `gem install readme_yard`
+
+**Note:** As of version 0.3.0, Readme Yard requires Ruby 3.0 or higher.
 
 ## Getting Started
 
-Run `readme build` at the command line. That will create a README_YARD.md file if there isn’t one by copying your exisiting README.md file.
+Run `readme build` at the command line. This creates a README_YARD.md file if there isn't one by copying your existing README.md file.
 
-README_YARD.md is the template from which `readme build` generates the README. It augments your markdown with tagging capabilities as described in the section on [Tag Usage](#tag-usage).
+README_YARD.md is the template from which `readme build` generates the README. Readme Yard adds the ability to embed and reference your source code in your README via README_YARD.md.
+
+See [Tag Usage](#tag-usage).
 
 ---
 
@@ -36,80 +51,139 @@ README_YARD.md is the template from which `readme build` generates the README. I
 
 ## Tag Usage
 
-Readme Yard uses **README tags** and **YARD tags** in order to find, format, and embed Ruby source code inside README.md.
+Readme Yard uses YARD tags and custom markdown tags. YARD tags live inside Ruby source code. The markdown tags live inside README_YARD.md.
 
-**README tags** live inside README_YARD.md.
+When the Readme Yard build process encounters a tag in README_YARD.md, it searches the Ruby source code for its YARD tag counterpart, formats the output, and embeds it in the README file.
 
-**YARD tags** live inside Ruby source code.
+### Tag Reference Table
 
-When the Readme Yard build process encounters a tag in README_YARD.md, it searches the Ruby source code for its YARD tag counterpart, formats the output, and embeds it in the README file.
+| Tag Type | YARD Syntax (in source code) | Markdown Syntax (in README_YARD.md) | Standalone Tag* | Purpose |
+|----------|------------------------------|-------------------------------------|----------------|---------|
+| Readme | `@readme` | `{@readme ObjectPath}` | N/A | General purpose tag to embed content from source code |
+| Readme (comment) | `@readme comment` | `{@readme ObjectPath}` | `{@comment ObjectPath}` | Embeds only the comment from source code |
+| Readme (code) | `@readme code` | `{@readme ObjectPath}` | `{@code ObjectPath}` | Embeds only code implementation |
+| Readme (source) | `@readme source` | `{@readme ObjectPath}` | `{@source ObjectPath}` | Embeds both comments and code |
+| Readme (value) | `@readme value` | `{@readme ObjectPath}` | `{@value ObjectPath}` | Embeds a Ruby value as a Ruby code block |
+| Readme (string) | `@readme string` | `{@readme ObjectPath}` | `{@string ObjectPath}` | Embeds a Ruby string as normal text |
+| Example | `@example` | `{@example ObjectPath}` | N/A | Embeds example code from YARD @example tags |
+
+> *Standalone tags allow embedding content without requiring corresponding YARD tags in source code. See [Standalone Tag Usage](#standalone-tag-usage) for details.
 
 ### Examples
 
-This project's [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md) has `{@readme ReadmeYard.hello_world}` just below this paragraph, unless you're looking at the [README]((https://github.com/mattruzicka/readme_yard/blob/main/README.md)) where you should instead see a code example which was generated from running `readme build`.
+The next line is a code snippet if you're looking at the [README](https://github.com/mattruzicka/readme_yard/blob/main/README.md) and `{@readme ReadmeYard::ExampleTag.hello_world}` if you're looking at [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md).
 
-{@readme ReadmeYard.hello_world}
+{@readme ReadmeYard::ExampleTag.hello_world}
 
-The README tag tells Readme Yard to parse the `@readme` YARD tag located above the `hello_world` class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
+The markdown tag tells Readme Yard to parse the `@readme` tag located above the `hello_world` class method located in [lib/readme_yard/example_tag.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/example_tag.rb).
 
 To use another "meta" example, `{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate the first few sentences of this README. `ReadmeYard` references the class located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
 
-Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments located above. `ReadmeYard#command_line_usage` references the instance method `command_line_usage` located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
+Last one, `{@readme ReadmeYard#command_line_usage}` is used to generate the "Command Line Usage" section above from the comments of the `command_line_usage` instance method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb). This method is extra meta: it returns the result of formatting its own comments as markdown. In this way, the usage instructions in the comments, the README, and as printed at the command line will always be in sync.
 
 ---
 
 ## Readme Tag
 
-**README Tag** syntax: `{@readme ObjectPath}`
+**Markdown** syntax: `{@readme ObjectPath}`
 
-**YARD Tag** syntax: `@example <name>`
+**YARD** syntax: `@example <name>`
 
 {@readme ReadmeYard::ReadmeTag}
 
-The above two sentences were generated via `{@readme ReadmeYard::ReadmeTag}` in README_YARD.md and the @readme tag at the top of [ReadmeYard::ReadmeTag class](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb).
+### {@readme ReadmeYard::CommentTag}
+
+**Usage:**
+
+{@example ReadmeYard::CommentTag}
+
+This example [@readme comment](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/comment_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::CommentTag.format_tag}` markdown tag.
+
+{@readme ReadmeYard::CommentTag.format_tag}
+
+### {@readme ReadmeYard::CodeTag}
+
+**Usage:**
 
-## Readme YARD Tags
+{@example ReadmeYard::CodeTag}
 
+This example [@readme code](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/code_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::CodeTag.format_tag}` markdown tag.
 
-### Comment Tag
+{@readme ReadmeYard::CodeTag.format_tag}
 
-{@readme ReadmeYard::CommentTag}
+### {@readme ReadmeYard::SourceTag}
 
-[This @readme comment YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/comment_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::CommentTag.format_tag_markdown}` is in README_YARD.md.
+**Usage:**
 
-{@readme ReadmeYard::CommentTag.format_tag_markdown}
+{@example ReadmeYard::SourceTag}
 
-### Source Tag
+This example [@readme source](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/source_tag.rb) tag embeds the below code snippet via the `{@readme ReadmeYard::SourceTag.format_tag}` markdown tag.
 
-{@readme ReadmeYard::SourceTag}
+{@readme ReadmeYard::SourceTag.format_tag}
 
-[This @readme source YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::SourceTag.format_tag_markdown}` is in README_YARD.md.
+### {@readme ReadmeYard::ValueTag}
 
-{@readme ReadmeYard::SourceTag.format_tag_markdown}
+**Usage:**
 
+{@example ReadmeYard::ValueTag}
 
-### Object Tag
+This example [@readme value](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/value_tag.rb) tag embeds the below code snippet via the `{@value ReadmeYard::ValueTag::EXAMPLE}` markdown tag.
 
-{@readme ReadmeYard::ObjectTag}
+{@value ReadmeYard::ValueTag::EXAMPLE}
 
-[This @readme object YARD tag](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/readme_tag.rb) embeds the below code snippet because `{@readme ReadmeYard::ObjectTag.format_tag_markdown}` is in README_YARD.md.
+### {@readme ReadmeYard::StringTag}
 
-{@readme ReadmeYard::ObjectTag.format_tag_markdown}
+**Usage:**
 
+Because a [@readme string](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard/string_tag.rb) tag:
+
+{@example ReadmeYard::StringTag::XZAMPLE}
+
+Is located above this constant:
+
+{@code ReadmeYard::StringTag::XZAMPLE}
+
+We see can see its string value as simple text below:
+
+{@string ReadmeYard::StringTag::XZAMPLE}
+
+---
+
+## Standalone Tag Usage
+
+While using the `@readme` tag in your source code is recommended because it makes the README's dependency on source code explicit, sometimes it's useful to embed source code snippets directly without it. This is especially valuable when a source object can only contain one `@readme` tag, but you want to highlight multiple aspects of the object.
+
+You can use any of these tags directly in README_YARD.md without requiring a corresponding `@readme` tag in the source code:
+
+- `{@comment ObjectPath}` - Embeds comments only
+- `{@code ObjectPath}` - Embeds code only
+- `{@source ObjectPath}` - Embeds both comments and code
+- `{@value ObjectPath}` - Embeds a Ruby value as a Ruby code block
+- `{@string ObjectPath}` - Embeds a Ruby string as plain text
+
+For example, in the StringTag section above, we used both:
+- `{@code ReadmeYard::StringTag::XZAMPLE}` to show the constant definition
+- `{@string ReadmeYard::StringTag::XZAMPLE}` to display the string value as text
+
+The standalone tag usage provides more flexibility when documenting your code and doesn't require modifications to the source files.
 
 ---
 
 ## Example Tag
 
-**README Tag** syntax: `{@example ObjectPath}`
+**Markdown** syntax: `{@example ObjectPath}`
+
+**YARD** syntax: `@example`
 
-**YARD Tag** example: `@example`
+{@readme ReadmeYard::ExampleTag}
 
-{@readme ReadmeYard.hello_world}
+**Usage:**
 
-Given that the above comment is for the `hello_world` class method, the below example code is generated from placing `{@example ReadmeYard.hello_world}` in README_YARD.md.
+{@source ReadmeYard::ExampleTag.hello_world}
 
-{@example ReadmeYard.hello_world}
+The below example code is generated from `{@example ReadmeYard::ExampleTag.hello_world}` because, as you can see above, the "hello_world" class method has an `@example` tag.
+
+{@example ReadmeYard::ExampleTag.hello_world}
 
 ---
 
@@ -117,6 +191,4 @@ Given that the above comment is for the `hello_world` class method, the below ex
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.
 
-Thanks for taking the time to think about me, the README.
-
-🌿 🥏 🌱 ⚽
+Thanks for reading me, the README that documents how to document the README with code that documents itself 🤯

data/bin/readme

@@ -3,7 +3,7 @@
 
 require "bundler/setup"
 require "readme_yard"
-require "tty-markdown"
 
-arg, options = ARGV
+arg, *arg_options = ARGV.dup
+options = arg_options.join(" ") unless arg_options.empty?
 ReadmeYard.call(arg, options)

data/lib/readme_yard/code_tag.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class ReadmeYard
+  #
+  # @readme
+  #   Embed Ruby code
+  #
+  # @example
+  #   # @readme code
+  #
+  class CodeTag
+    class << self
+      #
+      # The code for this method is in the README because
+      # `@readme code` is below (in the source code).
+      #
+      # @readme code
+      #
+      def format_tag(yard_object, _tag)
+        ExampleTag.format_ruby(yard_object.source)
+      end
+
+      def format_yard_object(yard_object)
+        format_tag(yard_object, nil)
+      end
+    end
+  end
+end

data/lib/readme_yard/comment_tag.rb

@@ -1,21 +1,30 @@
+# frozen_string_literal: true
+
 class ReadmeYard
   #
   # @readme
-  #   ```@readme comment``` - Embeds the comment.
+  #   Embed comments
+  #
+  # @example
+  #   # @readme comment
   #
   class CommentTag
     class << self
       #
       # This comment is in the README because `@readme comment`
-      # is below, in the source code.
+      # is below (in the source code).
       #
       # @readme comment
       #
-      def format_tag_markdown(yard_object, _tag)
+      def format_tag(yard_object, _tag)
         comment = format_docstring_as_comment(yard_object)
         ExampleTag.format_ruby(comment)
       end
 
+      def format_yard_object(yard_object)
+        format_tag(yard_object, nil)
+      end
+
       #
       # @see https://rubydoc.info/gems/yard/YARD%2FDocstring:to_raw
       #
@@ -29,12 +38,12 @@ class ReadmeYard
           comment << line
         end
         last_line = yard_object.docstring.all.lines.last
-        comment << "#" if last_line.match?(/\n$/)
+        comment << "#" if last_line&.match?(/\n$/)
         comment
       end
 
       def named_readme_tag_regex
-        @named_readme_tag_regex ||= /(\n|^)@readme\s(#{YARDReadme::DocstringParser.readme_tag_names.join("|")})\n/
+        @named_readme_tag_regex ||= /(\n|^)@readme\s(#{ReadmeYard::TagRegistry.tag_names.join("|")})\n/
       end
     end
   end

data/lib/readme_yard/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class ReadmeYard
   class Error < StandardError
     class << self

data/lib/readme_yard/example_tag.rb

@@ -1,11 +1,29 @@
+# frozen_string_literal: true
+
 class ReadmeYard
+  #
+  # @readme
+  #   The Example Tag leverages YARD's standard `@example` tag syntax, allowing you to
+  #   include example code in your README directly from source files. This saves time and
+  #   ensures your README stays in sync with your YARD documentation
+  #
   class ExampleTag
     class << self
-      def format_markdown(yard_object, yard_tags)
-        yard_tags.map { |tag| format_tag_markdown(yard_object, tag) }.join("\n")
+      #
+      # @readme source
+      #
+      # @example
+      #   ReadmeYard::ExampleTag.hello_world #=> "Hello 🌎 🌍 🌏"
+      #
+      def hello_world
+        "Hello 🌎 🌍 🌏"
+      end
+
+      def format_tags(yard_object, yard_tags)
+        yard_tags.map { |tag| format_tag(yard_object, tag) }.join("\n")
       end
 
-      def format_tag_markdown(yard_object, tag)
+      def format_tag(yard_object, tag)
         text = tag.text.empty? ? yard_object.source : tag.text
         format_ruby(text)
       end

data/lib/readme_yard/logger.rb

@@ -1,9 +1,20 @@
+# frozen_string_literal: true
+
 class ReadmeYard
   class Logger
     class << self
       def warn(msg)
+        msg = "Warning: #{msg}"
+        puts_md(msg)
+      end
+
+      def puts_md(msg)
         puts TTY::Markdown.parse(msg)
       end
+
+      def puts_text(msg)
+        puts msg
+      end
     end
   end
-end
+end

data/lib/readme_yard/readme_tag.rb

@@ -1,19 +1,21 @@
+# frozen_string_literal: true
+
 class ReadmeYard
   #
   # @readme
-  #   By default, only the text nested under the @readme tag
-  #   will be embedded in the final output.
-  #
-  #   Different embed options are provided via the following
-  #   name options: `comment`, `source`, and `object`.
+  #   By default, only the text nested under a @readme tag
+  #   will be embedded in the final output. The default
+  #   embed behavior can be changed through the use of tag names.
   #
   # @see ReadmeYard::CommentTag
+  # @see ReadmeYard::CodeTag
   # @see ReadmeYard::SourceTag
-  # @see ReadmeYard::ObjectTag
+  # @see ReadmeYard::ValueTag
+  # @see ReadmeYard::StringTag
   #
   class ReadmeTag
     class << self
-      def format_markdown(yard_object, yard_tags)
+      def format_tags(yard_object, yard_tags)
         md = +""
         yard_tags.each do |tag|
           res = format_yard_tag(yard_object, tag)
@@ -22,7 +24,7 @@ class ReadmeYard
         md
       end
 
-      def format_tag_markdown(_yard_object, tag)
+      def format_tag(_yard_object, tag)
         "#{tag.text}\n"
       end
 
@@ -30,10 +32,12 @@ class ReadmeYard
 
       def format_yard_tag(yard_object, tag)
         if tag.name && !tag.name.empty?
-          tag_class = ReadmeYard.lookup_tag_class(tag.name)
-          tag_class&.format_tag_markdown(yard_object, tag)
+          tag_class = TagRegistry.find_class(tag.name)
+          tag_class&.format_tag(yard_object, tag)
         elsif tag.text && !tag.text.empty?
-          format_tag_markdown(yard_object, tag)
+          format_tag(yard_object, tag)
+        else
+          Logger.warn("Empty `@readme` tag found in `#{yard_object}`.")
         end
       end
     end

data/lib/readme_yard/source_tag.rb

@@ -1,17 +1,29 @@
+# frozen_string_literal: true
+
 class ReadmeYard
   #
   # @readme
-  #   ```@readme source``` - Embeds the source.
+  #   Embed Ruby comments and code
+  #
+  # @example
+  #   # @readme source
   #
   class SourceTag
     class << self
       #
-      # The following tag embeds this method's source.
+      # The comment and code for ReadmeYard::SourceTag#format_tag
+      # is in the README because `@readme source` is below (in the source code).
       #
       # @readme source
       #
-      def format_tag_markdown(yard_object, _tag)
-        ExampleTag.format_ruby(yard_object.source)
+      def format_tag(yard_object, _tag)
+        text = CommentTag.format_docstring_as_comment(yard_object)
+        text << "\n#{yard_object.source}"
+        ExampleTag.format_ruby(text)
+      end
+
+      def format_yard_object(yard_object)
+        format_tag(yard_object, nil)
       end
     end
   end

data/lib/readme_yard/string_tag.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+class ReadmeYard
+  #
+  # @readme
+  #   Embed a Ruby string as normal text
+  #
+  class StringTag
+    #
+    # @example
+    #   # @readme string
+    #
+    # @readme string
+    #
+    XZAMPLE = <<~STRING
+      I heard you like self-documenting Ruby, so I wrote
+      self-documenting Ruby for your self-documenting Ruby.
+    STRING
+
+    class << self
+      def format_tag(yard_object, _tag)
+        if yard_object.respond_to?(:value)
+          normalize_yard_value(yard_object.value)
+        else
+          Logger.warn("Cannot parse `@readme string`: #{yard_object.class.name} lacks `value` method.")
+        end
+      end
+
+      def format_yard_object(yard_object)
+        format_tag(yard_object, nil)
+      end
+
+      def normalize_yard_value(string_value)
+        return "" if string_value.nil? || string_value.empty?
+
+        string_value = string_value.dup
+
+        # Handle heredoc format
+        return normalize_value_for_heredoc(string_value) if string_value.strip.start_with?("<<~")
+
+        # Handle regular string format
+        string_value.delete_prefix!('"')
+        string_value.delete_suffix!('"')
+
+        # Replace different line continuation patterns
+        # This handles patterns like: " \\\n" and \\\n"
+        string_value.gsub!(/" \\\n"/, "")
+        string_value.gsub!(/\\\n\s*"/, "")
+        string_value.gsub!(/"\\\n"/, "")
+        string_value.gsub!(/"\\\n/, "")
+
+        # Unescape common escape sequences
+        string_value.gsub!(/\\n/, "\n")
+        string_value.gsub!(/\\t/, "\t")
+        string_value.gsub!(/\\r/, "\r")
+        string_value.gsub!(/\\"/, '"')
+        string_value.gsub!(/\\'/, "'")
+        string_value.gsub!(/\\\\/, "\\")
+        string_value
+      end
+
+      private
+
+      def normalize_value_for_heredoc(string_value)
+        # Extract the content between the heredoc delimiters
+        lines = string_value.lines
+        delimiter = lines.first.strip.gsub(/<<~/, "").strip
+        content_lines = []
+
+        in_content = false
+        lines.each do |line|
+          if in_content && line.strip == delimiter
+            break
+          elsif in_content
+            content_lines << line
+          elsif line.strip.start_with?("<<~")
+            in_content = true
+          end
+        end
+
+        # Return the joined content with proper indentation removed
+        content_lines.join.gsub(/^\s+/, "").strip
+      end
+    end
+  end
+end

data/lib/readme_yard/tag_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class ReadmeYard
+  class TagRegistry
+    TAGS = { "readme" => ReadmeTag,
+             "example" => ExampleTag,
+             "code" => CodeTag,
+             "source" => SourceTag,
+             "comment" => CommentTag,
+             "value" => ValueTag,
+             "string" => StringTag }.freeze
+
+    def self.find_class(tag_name)
+      TAGS[tag_name.downcase]
+    end
+
+    def self.tag_names
+      TAGS.keys
+    end
+  end
+end

data/lib/readme_yard/value_tag.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class ReadmeYard
+  #
+  # @readme
+  #   Embed a Ruby value as a Ruby code block
+  #
+  # @example
+  #   # @readme value
+  #
+  class ValueTag
+    #
+    # @readme value
+    #
+    EXAMPLE = { key: "value" }.freeze
+
+    class << self
+      def format_tag(yard_object, _tag)
+        if yard_object.respond_to?(:value)
+          "```ruby\n#{yard_object.value}\n```"
+        else
+          Logger.warn("Cannot parse `@readme value`: #{yard_object.class.name} lacks `value` method.")
+        end
+      end
+
+      def format_yard_object(yard_object)
+        format_tag(yard_object, nil)
+      end
+    end
+  end
+end

data/lib/readme_yard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class ReadmeYard
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/readme_yard/yard_opts_manager.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class ReadmeYard
+  class YardOptsManager
+    class << self
+      YARDOPTS_FILE = ".yardopts"
+
+      def upsert_yardopts
+        File.exist?(YARDOPTS_FILE) ? update_yardopts_file : create_yardopts_file
+      end
+
+      def update_yardopts_file
+        text = File.read(YARDOPTS_FILE)
+        text_addition = build_yardopts_text_addition(text)
+        File.open(YARDOPTS_FILE, "a") { |f| f.write(text_addition) } if text_addition
+      end
+
+      def build_yardopts_text_addition(yardopts_text)
+        return if yardopts_text.match?(/\s*--plugin\s+readme\W/)
+
+        readme_plugin_opts = default_readme_plugin_opts(yardopts_text)
+        case yardopts_text
+        when /\s*--markup\s+markdown/, /\s*-m\s+markdown/
+          readme_plugin_opts
+        when /\s*--markup\s/, /\s*-m\s/
+          warn_about_supported_markdown
+          readme_plugin_opts
+        else
+          readme_plugin_opts << "--markup markdown\n"
+        end
+      end
+
+      def default_readme_plugin_opts(yardopts_text)
+        readme_opts = +""
+        readme_opts << "\n" unless yardopts_text.lines.last.include?("\n")
+        readme_opts << "--plugin readme\n"
+      end
+
+      def create_yardopts_file
+        File.write(YARDOPTS_FILE, "--plugin readme\n--markup markdown\n")
+      end
+
+      def warn_about_supported_markdown
+        Logger.warn "*Readme Yard* works best with markdown. " \
+                    "Consider adding `--markup markdown` to your `.yardopts` file."
+      end
+    end
+  end
+end