readme_yard 0.2.0 → 0.4.0

data/lib/readme_yard.rb

@@ -1,45 +1,45 @@
 # frozen_string_literal: true
 
+require "yard"
 require "yard-readme"
+require "tty-markdown"
 require_relative "readme_yard/version"
 require_relative "readme_yard/error"
 require_relative "readme_yard/logger"
 require_relative "readme_yard/readme_tag"
 require_relative "readme_yard/example_tag"
 require_relative "readme_yard/comment_tag"
+require_relative "readme_yard/code_tag"
 require_relative "readme_yard/source_tag"
-require_relative "readme_yard/object_tag"
+require_relative "readme_yard/value_tag"
+require_relative "readme_yard/string_tag"
+require_relative "readme_yard/tag_registry"
+require_relative "readme_yard/yard_opts_manager"
+require "diffy"
 
-YARDReadme::DocstringParser.readme_tag_names = %w[comment source object]
+YARD::Readme::DocstringParser.readme_tag_names = ReadmeYard::TagRegistry.tag_names
 
 #
 # @readme
-#   Build a better README with [YARD](https://yardoc.org),
-#   one that summarizes and contextualizes the code and documentation,
-#   without duplicating them.
+#   Build a better README with [YARD](https://yardoc.org)
+#   by generating it straight from the source.
 #
-#   This gem aims to minimize the effort needed to keep
-#   your code, docs, and README useful, syncd, and correct.
+#   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.
 #
-#   For a glimpse of how it works, check out the [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
-#   template from which this gem's README was generated.
+#   Look at the [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/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 `{@readme ReadmeYard}` is in the README_YARD file
-#   and someone ran `readme build` at the command line.
+#   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](https://rubydoc.info/github/mattruzicka/readme_yard).
 #
 class ReadmeYard
-  #
-  # @readme comment
-  #
-  # @example
-  #   ReadmeYard.hello_world #=> "Hello 🌎 🌍 🌏"
-  #
-  def self.hello_world
-    "Hello 🌎 🌍 🌏"
-  end
-
   #
   # @see #command_line_usage
   #
@@ -49,23 +49,15 @@ class ReadmeYard
     case arg
     when "build"
       readme_yard.build(options: options)
-    when "doc"
-      readme_yard.doc(options: options)
+    when "yard"
+      readme_yard.yard(options: options)
+    when "version"
+      Logger.puts_md(VERSION)
     else
-      puts TTY::Markdown.parse(readme_yard.command_line_usage)
+      Logger.puts_md(readme_yard.command_line_usage)
     end
   rescue Error => e
-    puts TTY::Markdown.parse(e.message)
-  end
-
-  TAG_CLASS_LOOKUP = { "readme" => ReadmeTag,
-                       "example" => ExampleTag,
-                       "source" => SourceTag,
-                       "comment" => CommentTag,
-                       "object" => ObjectTag }.freeze
-
-  def self.lookup_tag_class(tag_name)
-    TAG_CLASS_LOOKUP[tag_name]
+    Logger.puts_md(e.message)
   end
 
   def initialize
@@ -76,7 +68,9 @@ class ReadmeYard
   attr_accessor :readme_path, :readme_yard_path
 
   #
-  # This method returns the following `@readme` text
+  # 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.
   #
   # @readme
   #   ## Command Line Usage
@@ -85,13 +79,15 @@ class ReadmeYard
   #
   #   `readme build` - Reads from README_YARD.md and writes to README.md.
   #
-  #   `readme doc` - Same as `readme build` + generates yard docs.
+  #   `readme yard` - Same as `readme build` + generates yard docs.
+  #
+  #   `readme version` - Prints the current version of ReadmeYard.
   #
   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"
+    "\n#{ReadmeTag.format_tags(yard_object, yard_tags)}\n\n"
   end
 
   #
@@ -105,20 +101,19 @@ class ReadmeYard
   # `-q` silence yardoc output statements
   #
   def build(options: "-nq")
-    find_or_upsert_yardopts
-    run_yardoc(options: options)
-    File.write(readme_path, gsub_tags!(readme_yard_md))
+    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
 
   #
-  # @readme Same as "build" + generates yard docs.
+  # @readme Same as "build" + generates yard `docs.
   #
-  def doc(options: "-q")
-    build(options: options || "-q")
-  end
-
-  def run_yardoc(options: "-nq")
-    YARD::CLI::Yardoc.run(options || "-nq")
+  def yard(options: "")
+    YardOptsManager.upsert_yardopts
+    build(options: options || "")
   end
 
   private
@@ -144,43 +139,6 @@ class ReadmeYard
      " for usage.\n\n{@readme ReadmeYard#default_readme_yard_md}"
   end
 
-  YARDOPTS_FILE = ".yardopts"
-
-  def find_or_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 gsub_tags!(markdown)
     markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string| format_tag_markdown(string) }
     markdown
@@ -201,12 +159,17 @@ class ReadmeYard
 
   def format_yard_tags_markdown(yard_object, tag_name, string)
     yard_tags = yard_object.tags(tag_name)
+    tag_class = TagRegistry.find_class(tag_name)
+
     if yard_tags.empty?
-      warn_about_yard_tags_not_found(yard_object, tag_name)
-      string
+      if tag_class.respond_to?(:format_yard_object)
+        tag_class.format_yard_object(yard_object) || string
+      else
+        Logger.warn("The `@#{tag_name}` tag is missing from `#{yard_object}`.")
+        string
+      end
     else
-      tag_class = self.class.lookup_tag_class(tag_name)
-      tag_class.format_markdown(yard_object, yard_tags)
+      tag_class.format_tags(yard_object, yard_tags)
     end
   end
 
@@ -224,12 +187,14 @@ class ReadmeYard
     YARD.parse(current_file_path)
   end
 
-  def warn_about_supported_markdown
-    Logger.warn "\n*Readme Yard* works best with markdown." \
-                "\nConsider adding `--markup markdown` to your `.yardopts` file.\n\n"
-  end
+  def show_readme_diff(old_content, new_content)
+    if old_content == new_content
+      Logger.puts_md("\n**No changes** to README.md\n\n")
+      return
+    end
 
-  def warn_about_yard_tags_not_found(yard_object, tag_name)
-    Logger.warn "The `@#{tag_name}` *Readme Yard* tag is missing from #{yard_object}."
+    diff = Diffy::Diff.new(old_content, new_content, context: 0).to_s(:color)
+    Logger.puts_md("\n**Changes to README.md:**\n\n")
+    Logger.puts_text "#{diff}\n"
   end
 end

data/readme_yard.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Build a better README with YARD."
   spec.homepage = "https://github.com/mattruzicka/readme_yard"
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 3.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -22,12 +22,17 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
 
-  spec.executables << "readme"
+  spec.bindir = "bin"
+  spec.executables = ["readme"]
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
+  spec.add_dependency "diffy", "~> 3.4"
   spec.add_dependency "tty-markdown", "~> 0.7"
-  spec.add_dependency "yard-readme", "~> 0.3"
+  spec.add_dependency "yard", "~> 0.9"
+  spec.add_dependency "yard-readme", "~> 0.5"
+
+  spec.add_development_dependency "irb"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: readme_yard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Ruzicka
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: diffy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: tty-markdown
   requirement: !ruby/object:Gem::Requirement
@@ -24,22 +37,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: yard-readme
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
-description:
-email:
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 executables:
 - readme
 extensions: []
@@ -59,14 +98,18 @@ files:
 - bin/readme
 - bin/setup
 - lib/readme_yard.rb
+- lib/readme_yard/code_tag.rb
 - lib/readme_yard/comment_tag.rb
 - lib/readme_yard/error.rb
 - lib/readme_yard/example_tag.rb
 - lib/readme_yard/logger.rb
-- lib/readme_yard/object_tag.rb
 - lib/readme_yard/readme_tag.rb
 - lib/readme_yard/source_tag.rb
+- lib/readme_yard/string_tag.rb
+- lib/readme_yard/tag_registry.rb
+- lib/readme_yard/value_tag.rb
 - lib/readme_yard/version.rb
+- lib/readme_yard/yard_opts_manager.rb
 - readme_yard.gemspec
 homepage: https://github.com/mattruzicka/readme_yard
 licenses:
@@ -75,7 +118,6 @@ metadata:
   homepage_uri: https://github.com/mattruzicka/readme_yard
   source_code_uri: https://github.com/mattruzicka/readme_yard
   changelog_uri: https://github.com/mattruzicka/readme_yard/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,15 +125,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Build a better README with YARD.
 test_files: []

data/lib/readme_yard/object_tag.rb

@@ -1,21 +0,0 @@
-class ReadmeYard
-  #
-  # @readme
-  #   ```@readme object``` - Embeds the comment and source.
-  #
-  class ObjectTag
-    class << self
-      #
-      # This method's comment and code is in the README because
-      # because `@readme object` is below, in the actual source code.
-      #
-      # @readme object
-      #
-      def format_tag_markdown(yard_object, _tag)
-        text = CommentTag.format_docstring_as_comment(yard_object)
-        text << "\n#{yard_object.source}"
-        ExampleTag.format_ruby(text)
-      end
-    end
-  end
-end