yard-readme 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4ec34f12f41177c0652dcf498e833a03b2492e0faf1c487ee40b149bf41b2eb
-  data.tar.gz: 362213c9dd24df82f3396dd81218fe623050d91eb7c59adaed04fbe3587d44b9
+  metadata.gz: dcd61abdc1876be598a2d532300f924ad55a57bfd1621c547a3af4ae58e66878
+  data.tar.gz: 86efaa1311664e611826262de6d8b0a959069033e1eee9f95f7e4b1cbd3bd4a6
 SHA512:
-  metadata.gz: ecda196fad92caf901bbe43c0661dc961fc8abc39ee6aff954144167b6741e6ac5f6d4f6679fbf48a3cb849f64840ff7841039860225da57bc9e6f42a9e0a98c
-  data.tar.gz: 854dbe3d3d9ae01097edc0681d4f267248bb9db5107c01f49a8238131316ceab9f622e11253e1addce0c6d60d67d81c5ddcb659ad4129165a25a7199565d9cca
+  metadata.gz: c782d9c5accdc97a479ca316bb5c779fbaf0f48a0aa638bc9c9f732bc04b941206eb2fe7f82eab7131d463f5daafee32f43e16c8035935301fe61688a01342ad
+  data.tar.gz: f80feffe36580aca84fc820e46bf44218992199da1e6c23a38791a37a560ffc7702246ad2ed55f655b54dd368730ffb4127ac801af6cf17a912d532d56dcd60f

data/.gitignore

@@ -6,3 +6,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+.byebug_history

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.yardopts

@@ -1,2 +1,3 @@
---plugin readme
+-e lib/yard-readme.rb
+--markup markdown
 lib/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.3.0] - 2021-08-07
+
+- Rename newly added methods be373f150e865b933a58a950e6a5c654395e17c4
+
+## [0.2.0] - 2021-08-07
+
+- Be able to support new readme tag args in readme_yard without updating this gem b76ad2459168e4361ab38912e6faa7e36f249cec
+
+## [0.1.2] - 2021-08-07
+
+- Inherit from existing default to minimize conflict between plugins 69463cb2f580a1f5bcb734564eb51b32bf833250
+- Avoid raising error when readme tag text is blank 294c9400de41d297c71212939b410e4ce821bc15
+- Remove special readme tag names (README_YARD args) from docs when parsing docstring 983e1485b89888d390dc4879e7019fd7785dedda
+
+## [0.1.1] - 2021-07-31
+
+- Use readme_yard to build README
+
 ## [0.1.0] - 2021-07-25
 
 - Initial release

data/Gemfile.lock

@@ -1,18 +1,44 @@
 PATH
   remote: .
   specs:
-    yard-readme (0.1.0)
-      yard
+    yard-readme (0.2.0)
+      yard (~> 0.9.26)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    kramdown (2.3.1)
+      rexml
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    readme_yard (0.1.2)
+      tty-markdown (~> 0.7)
+      yard-readme (~> 0.1)
+    rexml (3.2.5)
+    rouge (3.26.0)
+    strings (0.2.1)
+      strings-ansi (~> 0.2)
+      unicode-display_width (>= 1.5, < 3.0)
+      unicode_utils (~> 1.4)
+    strings-ansi (0.2.0)
+    tty-color (0.6.0)
+    tty-markdown (0.7.0)
+      kramdown (>= 1.16.2, < 3.0)
+      pastel (~> 0.8)
+      rouge (~> 3.14)
+      strings (~> 0.2.0)
+      tty-color (~> 0.5)
+      tty-screen (~> 0.8)
+    tty-screen (0.8.1)
+    unicode-display_width (2.0.0)
+    unicode_utils (1.4.0)
     yard (0.9.26)
 
 PLATFORMS
   arm64-darwin-20
 
 DEPENDENCIES
+  readme_yard (~> 0.1)
   yard-readme!
 
 BUNDLED WITH

data/README.md

@@ -1,35 +1,23 @@
-# Yard::Readme
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yard/readme`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'yard-readme'
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install yard-readme
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# yard-readme
+
+A [YARD](https://yardoc.org) plugin used by
+[readme_yard](https://github.com/mattruzicka/readme_yard).
+It adds a `@readme` tag to YARD.
+
+It also replaces the default docstring parser so that only
+`@readme` tags and not their text values are stripped from
+the generated documentation. I prefer this over the default
+YARD behavior for the `@readme` tag because it allows the
+comments in the source code to signal the README dependency
+without pushing the generated YARD documentation into a
+separate "readme" section.
+
+That said, I welcome a PR that adds the default behavior as an option, as I think it could be preferable for some use cases. Ideally, I or someone would open a YARD PR to make leaving
+the tag text an option when registering a tag. Especially
+since this plugin's current behavior of replacing the
+`YARD::DocstringParser` could potentially conflict with
+other YARD plugins and is also more vulnerable to change.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yard-readme.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.

data/README_YARD.md

@@ -0,0 +1,9 @@
+# yard-readme
+
+{@readme YARDReadme}
+
+That said, I welcome a PR that adds the default behavior as an option, as I think it could be preferable for some use cases. {@readme YARDReadme::DocstringParser}
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.

data/lib/yard-readme.rb

@@ -3,6 +3,32 @@
 require 'yard'
 require_relative 'yard-readme/version'
 require_relative 'yard-readme/docstring_parser'
+require_relative 'yard-readme/tag_factory'
 
+#
+# @readme
+#   A [YARD](https://yardoc.org) plugin used by
+#   [readme_yard](https://github.com/mattruzicka/readme_yard).
+#   It adds a `@readme` tag to YARD.
+#
+#   It also replaces the default docstring parser so that only
+#   `@readme` tags and not their text values are stripped from
+#   the generated documentation. I prefer this over the default
+#   YARD behavior for the `@readme` tag because it allows the
+#   comments in the source code to signal the README dependency
+#   without pushing the generated YARD documentation into a
+#   separate "readme" section.
+#
+module YARDReadme; end
+
+#
+# @see https://www.rubydoc.info/gems/yard/0.9.13/YARD/DocstringParser
+#
 YARD::Docstring.default_parser = YARDReadme::DocstringParser
-YARD::Tags::Library.define_tag('README', :readme)
+
+#
+# @see https://www.rubydoc.info/gems/yard/file/docs/TagsArch.md
+#
+YARD::Tags::Library.default_factory = YARDReadme::TagFactory
+
+YARD::Tags::Library.define_tag('README', :readme, :with_title_and_text)

data/lib/yard-readme/docstring_parser.rb

@@ -1,5 +1,33 @@
 module YARDReadme
-  class DocstringParser < YARD::DocstringParser
+  #
+  # @readme
+  #   Ideally, I or someone would open a YARD PR to make leaving
+  #   the tag text an option when registering a tag. Especially
+  #   since this plugin's current behavior of replacing the
+  #   `YARD::DocstringParser` could potentially conflict with
+  #   other YARD plugins and is also more vulnerable to change.
+  #
+  # Doing so would make this custom parser obsolete.
+  #
+  class DocstringParser < YARD::Docstring.default_parser
+    class << self
+      attr_accessor :readme_tag_names
+
+      def readme_tag_names_regex
+        @readme_tag_names_regex ||= /\A(#{readme_tag_names.join("|")})/
+      end
+
+      def readme_tag_names_regex?
+        readme_tag_names && !readme_tag_names.empty?
+      end
+
+      def strip_readme_tag_arg(text)
+        return text unless readme_tag_names_regex?
+
+        text.sub(readme_tag_names_regex, "")
+      end
+    end
+
     def parse_content(content)
       content = content.split(/\r?\n/) if content.is_a?(String)
       return '' if !content || content.empty?
@@ -27,7 +55,8 @@ module YARDReadme
               docstring << parse_content(directive.expanded_text).chomp
             end
           else
-            push_readme_text(docstring, buf) if tag_name == 'readme'
+            readme_text = parse_readme_text(buf) if parse_readme_text?(tag_name, buf)
+            docstring << readme_text if readme_text
             create_tag(tag_name, buf)
           end
           tag_name = nil
@@ -61,14 +90,13 @@ module YARDReadme
       docstring
     end
 
-    def push_readme_text(docstring, buf)
-      return if buf.empty?
+    def parse_readme_text(text)
+      readme_text = self.class.strip_readme_tag_arg(text)
+      readme_text << "\n\n" if readme_text
+    end
 
-      buf.split("\n").each do |buf_line|
-        docstring << buf_line
-        docstring << "\n"
-      end
-      docstring << "\n"
+    def parse_readme_text?(tag_name, buf)
+      tag_name == 'readme' && !buf.empty?
     end
   end
 end

data/lib/yard-readme/tag_factory.rb

@@ -0,0 +1,16 @@
+module YARDReadme
+  class TagFactory < YARD::Tags::Library.default_factory.class
+    #
+    # @see https://github.com/lsegal/yard/blob/359006641260eef1fe6d28f5c43c7c98d40f257d/lib/yard/tags/default_factory.rb#L70
+    #
+    def parse_tag_with_title_and_text(tag_name, text)
+      return YARD::Tags::Tag.new(tag_name, text) if blank_readme_tag?(tag_name, text)
+
+      super
+    end
+
+    def blank_readme_tag?(tag_name, text)
+      tag_name == "readme" && text.nil? || text.empty?
+    end
+  end
+end

data/lib/yard-readme/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module YARDReadme
-  VERSION = '0.1.0'
+  VERSION = "0.3.0"
 end

data/yard-readme.gemspec

@@ -3,19 +3,19 @@
 require_relative "lib/yard-readme/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "yard-readme"
-  spec.version       = YARDReadme::VERSION
-  spec.authors       = ["Matt Ruzicka"]
+  spec.name = "yard-readme"
+  spec.version = YARDReadme::VERSION
+  spec.authors = ["Matt Ruzicka"]
+  spec.license = "MIT"
 
-  spec.summary       = "Enhance your README with YARD"
-  spec.description   = "Generate your README using comments in your code"
-  spec.homepage      = 'https://github.com/mattruzicka/yard-readme'
+  spec.summary = "Enhance your README with YARD"
+  spec.description = "Generate your README using comments in your code"
+  spec.homepage = 'https://github.com/mattruzicka/yard-readme'
   spec.required_ruby_version = ">= 2.4.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = 'https://github.com/mattruzicka/yard-readme'
-  spec.metadata["changelog_uri"] = 'https://github.com/mattruzicka/yard-readme' \
-                                   '/blob/master/CHANGELOG.md'
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -27,7 +27,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "yard"
+  spec.add_dependency "yard", "~> 0.9.26"
+
+  spec.add_development_dependency 'readme_yard', "~> 0.1"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,29 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: yard-readme
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-25 00:00:00.000000000 Z
+date: 2021-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.26
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.26
+- !ruby/object:Gem::Dependency
+  name: readme_yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Generate your README using comments in your code
 email:
 executables: []
@@ -31,19 +45,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
+- README_YARD.md
 - bin/console
 - bin/setup
 - lib/yard-readme.rb
 - lib/yard-readme/docstring_parser.rb
+- lib/yard-readme/tag_factory.rb
 - lib/yard-readme/version.rb
 - yard-readme.gemspec
 homepage: https://github.com/mattruzicka/yard-readme
-licenses: []
+licenses:
+- MIT
 metadata:
   homepage_uri: https://github.com/mattruzicka/yard-readme
   source_code_uri: https://github.com/mattruzicka/yard-readme