readme_yard 0.1.2 → 0.3.0

data/lib/readme_yard.rb

@@ -1,50 +1,44 @@
 # 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/value_tag"
+require_relative "readme_yard/string_tag"
+require_relative "readme_yard/tag_registry"
+require_relative "readme_yard/yard_opts_manager"
+
+YARD::Readme::DocstringParser.readme_tag_names = ReadmeYard::TagRegistry.tag_names
 
 #
 # @readme
-#   An experiment in building a better README with
-#   [YARD](https://yardoc.org).
-#   Take a look at [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
-#   to see the template from which the README for this project was generated.
+#   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
+#   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](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
-#   [README_YARD.md](https://github.com/mattruzicka/readme_yard/blob/main/README_YARD.md)
-#   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.
 #
-#   If you're looking at the [source code](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb) or
-#   [documentation](https://rubydoc.info/github/mattruzicka/readme_yard),
-#   _welcome_ to readme yard!
+#   Here's the [full documentation](https://rubydoc.info/github/mattruzicka/readme_yard).
 #
 class ReadmeYard
-  class Error < StandardError
-    class << self
-      # TODO: Look for instance method with same name if
-      # class method and vise versa to give a more helpful error.
-      # Also, look for the object path in other scopes.
-      def object_not_found(tag_name, object_path)
-        new("`#{object_path}` could not be found. Perhaps" \
-            " the `@#{tag_name}` tag was moved, mispelled," \
-            " or the `.yardopts` YARD file is missing the file path.")
-      end
-    end
-  end
-
-  #
-  # @readme
-  #   This object only exists so that you can read this in the README. `ReadmeYard.hello_world` references
-  #   the class method located in [lib/readme_yard.rb](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb).
-  #
-  # @example
-  #   ReadmeYard.hello_world => "Hello 🌎 🌍 🌏"
-  #
-  def self.hello_world
-    "Hello 🌎 🌍 🌏"
-  end
-
   #
   # @see #command_line_usage
   #
@@ -54,13 +48,13 @@ 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)
     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)
+    Logger.puts_md(e.message)
   end
 
   def initialize
@@ -80,13 +74,13 @@ 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.
   #
   def command_line_usage
     yard_parse_this_file
     yard_object = YARD::Registry.at("#{self.class.name}##{__method__}")
-    tags = yard_object.tags(:readme)
-    "\n#{format_readme_tags(tags)}\n\n"
+    yard_tags = yard_object.tags(:readme)
+    "\n#{ReadmeTag.format_tags(yard_object, yard_tags)}\n\n"
   end
 
   #
@@ -100,19 +94,16 @@ class ReadmeYard
   # `-q` silence yardoc output statements
   #
   def build(options: "-nq")
-    run_yardoc(options: options)
+    YARD::CLI::Yardoc.run(options || "-nq")
     File.write(readme_path, gsub_tags!(readme_yard_md))
   end
 
   #
   # @readme Same as "build" + generates yard docs.
   #
-  def doc(options: "-q --markup markdown")
-    build(options: options || "-q --markup markdown")
-  end
-
-  def run_yardoc(options: "-nq")
-    YARD::CLI::Yardoc.run("#{options || "-nq"} --plugin readme")
+  def yard(options: "-q")
+    YardOptsManager.upsert_yardopts
+    build(options: options || "-q")
   end
 
   private
@@ -130,22 +121,6 @@ class ReadmeYard
     new_readme_yard_md
   end
 
-  #
-  # This method adds the below paragraph to a project's
-  # README file, if it doesn't already have one when running
-  # `readme build` for the first time.
-  #
-  # @readme
-  #   This is a quick example of using a readme tag in README_YARD.md
-  #
-  #   > {@readme ReadmeYard#default_readme_yard_md}
-  #
-  #   to copy a `@readme` comment from
-  #   [source code](https://github.com/mattruzicka/readme_yard/blob/main/lib/readme_yard.rb)
-  #   and paste it into the README file.
-  #
-  #   🌱 ⚽
-  #
   def default_readme_yard_md
     yard_parse_this_file
     +"Welcome to the README_YARD 🌿 🥏\n\n" \
@@ -155,23 +130,37 @@ class ReadmeYard
   end
 
   def gsub_tags!(markdown)
-    markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string| format_tag(string) }
+    markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string| format_tag_markdown(string) }
     markdown
   end
 
-  def format_tag(string)
+  def format_tag_markdown(string)
     first_char = string[0]
     return string if first_char == "`"
 
     tag_name = extract_tag_name(string)
     object_path = extract_object_path(string)
-    code_object = YARD::Registry.at(object_path)
-    raise Error.tag_not_found(tag_name, object_path) unless code_object
+    yard_object = YARD::Registry.at(object_path)
+    raise Error.object_not_found(object_path, tag_name) unless yard_object
+
+    yard_tags_markdown = format_yard_tags_markdown(yard_object, tag_name, string)
+    "#{first_char if first_char != "{"}#{yard_tags_markdown}"
+  end
 
-    tags = code_object.tags(tag_name)
-    return string if tags.empty?
+  def format_yard_tags_markdown(yard_object, tag_name, string)
+    yard_tags = yard_object.tags(tag_name)
+    tag_class = TagRegistry.find_class(tag_name)
 
-    "#{first_char if first_char != "{"}#{send("format_#{tag_name}_tags", tags)}"
+    if yard_tags.empty?
+      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.format_tags(yard_object, yard_tags)
+    end
   end
 
   def extract_tag_name(tag_string)
@@ -182,14 +171,6 @@ class ReadmeYard
     tag_string.match(/\s(\b.+)}/).captures.first
   end
 
-  def format_readme_tags(tags)
-    tags.map(&:text).join
-  end
-
-  def format_example_tags(tags)
-    tags.map { |tag| "```ruby\n#{tag.text}\n```" }.join("\n")
-  end
-
   def yard_parse_this_file
     gem_spec = Gem::Specification.find_by_name("readme_yard")
     current_file_path = File.join(gem_spec.full_gem_path, "lib", "readme_yard.rb")

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,16 @@ 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 "tty-markdown", "~> 0.7"
-  spec.add_dependency "yard-readme", "~> 0.1"
+  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,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: readme_yard
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Matt Ruzicka
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-markdown
@@ -24,22 +23,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.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
-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,7 +84,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/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:
@@ -68,7 +104,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
@@ -76,15 +111,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: []