yard-readme 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4ec34f12f41177c0652dcf498e833a03b2492e0faf1c487ee40b149bf41b2eb
-  data.tar.gz: 362213c9dd24df82f3396dd81218fe623050d91eb7c59adaed04fbe3587d44b9
+  metadata.gz: 4458410fb0b98437c2146843c50d289a30a48198b1c9aca310a4b0a029304b3a
+  data.tar.gz: f14c8330d1c130c19b5db7ab3584949bfc5987bd0c4748126c3ce3f3504ff866
 SHA512:
-  metadata.gz: ecda196fad92caf901bbe43c0661dc961fc8abc39ee6aff954144167b6741e6ac5f6d4f6679fbf48a3cb849f64840ff7841039860225da57bc9e6f42a9e0a98c
-  data.tar.gz: 854dbe3d3d9ae01097edc0681d4f267248bb9db5107c01f49a8238131316ceab9f622e11253e1addce0c6d60d67d81c5ddcb659ad4129165a25a7199565d9cca
+  metadata.gz: 733c2915d1453899173f74d634b5d157567a11173b5e1202b95d3fb68a92ade3d5e4d7ab9e539d9ad591bab1a8303f5ab3e94b5242566ed401644ce4689fa832
+  data.tar.gz: 6d4d1d75d943e0ab629fa2035784dd9f343cf8dd54732d54cc4613e779788a686f39a7454960c9451bcb76640c89c7b414d980bd256af96e035cbc44a2c64a6d

data/.gitignore

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

data/.yardopts

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

data/Gemfile.lock

@@ -1,18 +1,44 @@
 PATH
   remote: .
   specs:
-    yard-readme (0.1.0)
-      yard
+    yard-readme (0.1.1)
+      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.1)
+      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

@@ -4,5 +4,21 @@ require 'yard'
 require_relative 'yard-readme/version'
 require_relative 'yard-readme/docstring_parser'
 
+#
+# @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
+
 YARD::Docstring.default_parser = YARDReadme::DocstringParser
 YARD::Tags::Library.define_tag('README', :readme)

data/lib/yard-readme/docstring_parser.rb

@@ -1,4 +1,14 @@
 module YARDReadme
+  #
+  # @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::DocstringParser
     def parse_content(content)
       content = content.split(/\r?\n/) if content.is_a?(String)
@@ -27,7 +37,7 @@ module YARDReadme
               docstring << parse_content(directive.expanded_text).chomp
             end
           else
-            push_readme_text(docstring, buf) if tag_name == 'readme'
+            docstring << parse_readme_text(buf) if tag_name == 'readme' && !buf.empty?
             create_tag(tag_name, buf)
           end
           tag_name = nil
@@ -61,14 +71,8 @@ module YARDReadme
       docstring
     end
 
-    def push_readme_text(docstring, buf)
-      return if buf.empty?
-
-      buf.split("\n").each do |buf_line|
-        docstring << buf_line
-        docstring << "\n"
-      end
-      docstring << "\n"
+    def parse_readme_text(text)
+      text << "\n\n"
     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.1.1'
 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.1.1
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-25 00:00:00.000000000 Z
+date: 2021-07-31 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: []
@@ -36,6 +50,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - README.md
+- README_YARD.md
 - bin/console
 - bin/setup
 - lib/yard-readme.rb
@@ -43,7 +58,8 @@ files:
 - 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