readme_yard 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6ce40d9abe1cc884d3df5df04fe5d15b51748b7952e761f90c4103f75a27db1
-  data.tar.gz: b1010e42c6856156f4c9ebd8b9ede7e979d840f90199d259250fba943656bd33
+  metadata.gz: 9a4b3f3775475b7a7cb62fec62eb5c95d9d6ef905fab18151636a9c546530b10
+  data.tar.gz: 46be49cca9501b608b435a018ebc36555d698bf1d35da2badb15b0acd3c67231
 SHA512:
-  metadata.gz: dc8d2bc2e84203e326e9e495714f9cd290e3be1d6b560f18d787b17326a59501b54c75d381d0eb5f8fce213de63ff34ff754a0e263ccf9ea47d09c8f0ba9d42c
-  data.tar.gz: 48ec65512c43ad20b8b0e83d16466d3538de673c119c0fc825929c7e033732ad8eec7a23f102c5045e1f8e37923f316b521b52a535a227876f06b5921bb415b1
+  metadata.gz: '02608e395de5ca70c7936804a72f37a174594dd4604646f86880f67ea59a93ea56b8bbbfcd9e8de8178650b66c9e7b76d69e875e55fe3fc67eed2f77f58c7efc'
+  data.tar.gz: 99768416d98d47fb310db967d247ea1a4f5f6cd493dfd5d4905bf49b569951bba5d971e93fa5f2e2b893428a4c9dc3e537389496da20f7eda58b91c7c106cedf

data/.gitignore

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

data/.yardopts

@@ -0,0 +1,3 @@
+--plugin readme
+--markup markdown
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
-## [0.1.0] - 2021-07-25
+## 0.1.1 - 2021-07-30
+
+- First Implementation, the README will hopefully get you started. Please open an issue if it doesn't 🙂.
+
+
+## 0.1.0 - 2021-07-25
 
 - Initial release

data/Gemfile.lock

@@ -1,15 +1,38 @@
 PATH
   remote: .
   specs:
-    readme_yard (0.1.0)
-      yard-readme
+    readme_yard (0.1.1)
+      tty-markdown (~> 0.7)
+      yard-readme (~> 0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    kramdown (2.3.1)
+      rexml
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    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)
-    yard-readme (0.1.0)
-      yard
+    yard-readme (0.1.1)
+      yard (~> 0.9.26)
 
 PLATFORMS
   arm64-darwin-20

data/README.md

@@ -1,35 +1,108 @@
-# ReadmeYard
+# Readme Yard
 
-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/readme_yard`. To experiment with that code, run `bin/console` for an interactive prompt.
+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 this README was generated.
 
-TODO: Delete this and the text above, and describe your gem
+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.
 
-## Installation
+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/master/ReadmeYard),
+_welcome_ to readme yard 🌿 🥏
 
-Add this line to your application's Gemfile:
+---
+
+## Command Line Usage
+
+`readme` - Prints command line usage.
+
+`readme build` - Reads from README_YARD.md and writes to README.md.
+
+`readme doc` - Same as `readme build` + generates yard docs.
+
+---
+
+## Getting Started
+
+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`.
+
+Next run `readme build` at the command line. This creates a README_YARD.md file if there isn’t one by copying the README file if it exists. It then parses README_YARD.md and writes the result to README.md.
+
+In addition to being able to use tags as documented in the next section, you can edit the README_YARD file just as you would edit any README. Then to see changes made to README_YARD reflected in the README, run `readme build`.
+
+---
+
+## Usage
+
+The following tags can be used in README_YARD.md to generate YARD documentation inside your README.
+
+### @readme
+
+Usage: `{@readme ObjectPath}`
+
+`{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate this README's title and description. `ReadmeYard` references the class located in [lib/readme_yard.rb](lib/readme_yard.rb).
+
+`{@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](lib/readme_yard.rb).
+
+`{@readme ReadmeYard.hello_world}` - is used to generate this text in README.md. `ReadmeYard.hello_world` references
+the class method located in [lib/readme_yard.rb](lib/readme_yard.rb).
+
+### @example
+
+Usage: `{@example ObjectPath}`
+
+The below example code is generated from placing `{@example ReadmeYard.hello_world}` in README_YARD.md.
 
 ```ruby
-gem 'readme_yard'
+ReadmeYard.hello_world => "Hello 🌎 🌍 🌏"
 ```
 
-And then execute:
+---
 
-    $ bundle install
+## Inspiration
 
-Or install it yourself as:
+The desire to have the code, README, and documentation for [Evolvable](https://github.com/mattruzicka/evolvable) be useful, synced, and correct as I work on documenting the [1.1.0 Release](https://github.com/mattruzicka/evolvable/pull/8).
 
-    $ gem install readme_yard
+I want a README that summarizes and contextualizes the code and documentation, without duplicating them, so as to make keeping it up-to-date easier. Laziness!
 
-## Usage
+---
+
+## Ideas
+
+- Embed whole doc string if @readme tag is found, but there’s no text.
+
+- Embed whole method if @example tag is found, but no text.
+
+- `readme tags` - Prints usage and a list of all tags
+
+- `readme tags -v` - Prints docstrings of all tags
+
+- `readme tags <tag>` - Prints list of matching tags
+
+- `readme tags <tag>` - Prints list of matching tag docstrings
+
+- Improve linking. At the moment, there's lots of room for error when adding links in the YARD documentation.
+
+- Support @todo tags or any other native YARD tags that might be useful.
+
+- Add ability to target a particular tag in a doc string from README_YARD.md. Maybe via a tag directive?
+
+- Follow @see links to find tags
+
+- Integrate something like https://github.com/lsegal/yard-examples/blob/master/doctest/doctest.rb to add red/green test status to code example. Maybe via some sort of tag directive?
 
-TODO: Write usage instructions here
+- Be able to customize the name of the source and target files.
 
-## Development
+- Integrate with the YARD server so that changes to documentation or README_YARD.md automatically regenerate the README
 
-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.
+- Be able to register regexes for matching tags and running given blocks. Use to create functionality for tagging GitHub source.
 
-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).
+---
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/readme_yard.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.

data/README_YARD.md

@@ -0,0 +1,87 @@
+# Readme Yard
+
+{@readme ReadmeYard}
+
+---
+
+{@readme ReadmeYard#command_line_usage}
+
+---
+
+## Getting Started
+
+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`.
+
+Next run `readme build` at the command line. This creates a README_YARD.md file if there isn’t one by copying the README file if it exists. It then parses README_YARD.md and writes the result to README.md.
+
+In addition to being able to use tags as documented in the next section, you can edit the README_YARD file just as you would edit any README. Then to see changes made to README_YARD reflected in the README, run `readme build`.
+
+---
+
+## Usage
+
+The following tags can be used in README_YARD.md to generate YARD documentation inside your README.
+
+### @readme
+
+Usage: `{@readme ObjectPath}`
+
+`{@readme ReadmeYard}` is used at the top of this project's README_YARD.md file to generate this README's title and description. `ReadmeYard` references the class located in [lib/readme_yard.rb](lib/readme_yard.rb).
+
+`{@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](lib/readme_yard.rb).
+
+`{@readme ReadmeYard.hello_world}` - {@readme ReadmeYard.hello_world}
+
+### @example
+
+Usage: `{@example ObjectPath}`
+
+The below example code is generated from placing `{@example ReadmeYard.hello_world}` in README_YARD.md.
+
+{@example ReadmeYard.hello_world}
+
+---
+
+## Inspiration
+
+The desire to have the code, README, and documentation for [Evolvable](https://github.com/mattruzicka/evolvable) be useful, synced, and correct as I work on documenting the [1.1.0 Release](https://github.com/mattruzicka/evolvable/pull/8).
+
+I want a README that summarizes and contextualizes the code and documentation, without duplicating them, so as to make keeping it up-to-date easier. Laziness!
+
+---
+
+## Ideas
+
+- Embed whole doc string if @readme tag is found, but there’s no text.
+
+- Embed whole method if @example tag is found, but no text.
+
+- `readme tags` - Prints usage and a list of all tags
+
+- `readme tags -v` - Prints docstrings of all tags
+
+- `readme tags <tag>` - Prints list of matching tags
+
+- `readme tags <tag>` - Prints list of matching tag docstrings
+
+- Improve linking. At the moment, there's lots of room for error when adding links in the YARD documentation.
+
+- Support @todo tags or any other native YARD tags that might be useful.
+
+- Add ability to target a particular tag in a doc string from README_YARD.md. Maybe via a tag directive?
+
+- Follow @see links to find tags
+
+- Integrate something like https://github.com/lsegal/yard-examples/blob/master/doctest/doctest.rb to add red/green test status to code example. Maybe via some sort of tag directive?
+
+- Be able to customize the name of the source and target files.
+
+- Integrate with the YARD server so that changes to documentation or README_YARD.md automatically regenerate the README
+
+- Be able to register regexes for matching tags and running given blocks. Use to create functionality for tagging GitHub source.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/yard-readme.

data/bin/readme

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "readme_yard"
+require "tty-markdown"
+
+arg, options = ARGV
+ReadmeYard.call(arg, options)

data/lib/readme_yard.rb

@@ -1,8 +1,193 @@
 # frozen_string_literal: true
 
+require "yard-readme"
 require_relative "readme_yard/version"
 
-module ReadmeYard
-  class Error < StandardError; end
-  # Your code goes here...
+#
+# @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 this README was generated.
+#
+#   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.
+#
+#   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/master/ReadmeYard),
+#   _welcome_ to readme yard 🌿 🥏
+#
+class ReadmeYard
+  class Error < StandardError
+    class << self
+      def tag_not_found(tag_name, object_path)
+        new("The `@#{tag_name}` tag could not be found at `#{object_path}`")
+      end
+    end
+  end
+
+  #
+  # @readme
+  #   is used to generate this text in README.md. `ReadmeYard.hello_world` references
+  #   the class method located in [lib/readme_yard.rb](lib/readme_yard.rb).
+  #
+  # @example
+  #   ReadmeYard.hello_world => "Hello 🌎 🌍 🌏"
+  #
+  def self.hello_world
+    "Hello 🌎 🌍 🌏"
+  end
+
+  #
+  # @see #command_line_usage
+  #
+  def self.call(arg, options)
+    readme_yard = ReadmeYard.new
+
+    case arg
+    when "build"
+      readme_yard.build(options: options)
+    when "doc"
+      readme_yard.doc(options: options)
+    else
+      puts TTY::Markdown.parse(readme_yard.command_line_usage)
+    end
+  rescue Error => e
+    puts TTY::Markdown.parse(e)
+  end
+
+  def initialize
+    @readme_path = "./README.md"
+    @readme_yard_path = "./README_YARD.md"
+  end
+
+  attr_accessor :readme_path, :readme_yard_path
+
+  #
+  # This method returns the following `@readme` text
+  #
+  # @readme
+  #   ## Command Line Usage
+  #
+  #   `readme` - Prints command line usage.
+  #
+  #   `readme build` - Reads from README_YARD.md and writes to README.md.
+  #
+  #   `readme doc` - 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"
+  end
+
+  #
+  # @readme
+  #   Reads from README_YARD.md and writes to README.md
+  #
+  #   Forwards options to yardoc
+  #
+  # `-n` only generate .yardoc database, no documentation.
+  #
+  # `-q` silence yardoc output statements
+  #
+  def build(options: "-nq")
+    run_yardoc(options: options)
+    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")
+  end
+
+  private
+
+  def readme_yard_md
+    return File.read(readme_yard_path) if File.exist?(readme_yard_path)
+
+    create_new_readme_yard_md
+  end
+
+  def create_new_readme_yard_md
+    new_readme_yard_md = File.read(readme_path) if File.exist?(readme_path)
+    new_readme_yard_md ||= default_readme_yard_md
+    File.write(readme_yard_path, new_readme_yard_md)
+    new_readme_yard_md
+  end
+
+  #
+  # This method adds the below paragraph to a project's
+  # README.md 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" \
+     "Check out this project's" \
+     " [README](https://github.com/mattruzicka/readme_yard#readme)" \
+     " for usage.\n\n{@readme ReadmeYard#default_readme_yard_md}"
+  end
+
+  def gsub_tags!(markdown)
+    markdown.gsub!(/([^`]|^)(\{@\w+\s.+\})/) { |string| format_tag(string) }
+    markdown
+  end
+
+  def format_tag(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
+
+    tags = code_object.tags(tag_name)
+    return string if tags.empty?
+
+    "#{first_char if first_char != "{"}#{send("format_#{tag_name}_tags", tags)}"
+  end
+
+  def extract_tag_name(tag_string)
+    tag_string.match(/{@(\w+)\s/).captures.first
+  end
+
+  def extract_object_path(tag_string)
+    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")
+    YARD.parse(current_file_path)
+  end
 end

data/lib/readme_yard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module ReadmeYard
-  VERSION = "0.1.0"
+class ReadmeYard
+  VERSION = "0.1.1"
 end

data/readme_yard.gemspec

@@ -3,13 +3,16 @@
 require_relative "lib/readme_yard/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "readme_yard"
-  spec.version       = ReadmeYard::VERSION
-  spec.authors       = ["Matt Ruzicka"]
+  spec.name = "readme_yard"
+  spec.version = ReadmeYard::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/readme_yard"
+  spec.summary = "Build a better README with YARD."
+  spec.description = "An experiment in building a README that summarizes" \
+                     "and contextualizes the code and documentation, without" \
+                     " duplicating them, so as to make keeping it up-to-date easier."
+  spec.homepage = "https://github.com/mattruzicka/readme_yard"
   spec.required_ruby_version = ">= 2.5"
 
   spec.metadata["homepage_uri"] = spec.homepage
@@ -21,12 +24,13 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+
+  spec.executables << "readme"
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "yard-readme"
+  spec.add_dependency "tty-markdown", "~> 0.7"
+  spec.add_dependency "yard-readme", "~> 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,50 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: readme_yard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Matt Ruzicka
 autorequire:
-bindir: exe
+bindir: bin
 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: tty-markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: yard-readme
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Generate your README using comments in your code
+        version: '0.1'
+description: An experiment in building a README that summarizesand contextualizes
+  the code and documentation, without duplicating them, so as to make keeping it up-to-date
+  easier.
 email:
-executables: []
+executables:
+- readme
 extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - README.md
+- README_YARD.md
 - Rakefile
 - bin/console
+- bin/readme
 - bin/setup
 - lib/readme_yard.rb
 - lib/readme_yard/version.rb
 - readme_yard.gemspec
 homepage: https://github.com/mattruzicka/readme_yard
-licenses: []
+licenses:
+- MIT
 metadata:
   homepage_uri: https://github.com/mattruzicka/readme_yard
   source_code_uri: https://github.com/mattruzicka/readme_yard
@@ -67,5 +88,5 @@ requirements: []
 rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
-summary: Enhance your README with YARD
+summary: Build a better README with YARD.
 test_files: []