rspec-documentation 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31073f998af7b0e0f74ebd590721dc9ba5c4aa73b9ed88bf6848a77c189d7355
-  data.tar.gz: 83343ddbbd95d4e100b2675a7e72a92c5ca9df225e99454308bd2af2b078b7ae
+  metadata.gz: a964ddab12c98c8913f741374a4206eaff591787f10e692417d9cf097fd2fe45
+  data.tar.gz: 5dd25967d474700f60118b12649906f072bf912a173651bcf5ea1e70889c7ecb
 SHA512:
-  metadata.gz: e5d845f98a5ceaa7c0c6462cad990a598d84086955f61334b3011c5f3fb15d0e90cd1ba8fff75f3d1559aa8e8f841f78c16391e37a3c048bd1876916b0b352af
-  data.tar.gz: '04739b7fb732fc7a1a6492f23d12d31d598b21d769c89238d0b29aa535a1620069fbc0b1610c8d1fa3d6a29a85a8d614768167b750c3416bbe83871f8990c11b'
+  metadata.gz: 1923b974e68f71be19dfeddc8379d242c54c3ce69770490399237897d46672177c15fa4990260bef4442414746e273e2e1f0764b67ac134a28c4d2c0a2336b09
+  data.tar.gz: 5f25067b064fa2acca91e6b82a45d1bf5218005885262b638589b0a94b746daf9c2c7da21b34b64865cec1e3d924c5f960adc30505c5ced25a146059c4a10bd6

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--exclude spec/fixtures/**/*_spec.rb

data/.rubocop.yml

@@ -4,3 +4,6 @@ require:
 
 AllCops:
   NewCops: enable
+  Exclude:
+  - 'spec/fixtures/**/*'
+  - 'lib/rspec_documentation/page_tree.rb' # Rubocop bug, fixed in main

data/Gemfile

@@ -7,7 +7,10 @@ gemspec
 
 gem 'rake', '~> 13.0'
 
+gem 'devpack', '~> 0.4.1'
 gem 'rspec', '~> 3.0'
+gem 'rspec-file_fixtures', '~> 0.1.6'
+gem 'rspec-its', '~> 1.3'
 gem 'rubocop', '~> 1.51'
 gem 'rubocop-rake', '~> 0.6.0'
 gem 'rubocop-rspec', '~> 2.22'

data/Gemfile.lock

@@ -1,25 +1,41 @@
 PATH
   remote: .
   specs:
-    rspec-documentation (0.0.1)
+    rspec-documentation (0.0.3)
+      htmlbeautifier (~> 1.4)
+      kramdown (~> 2.4)
+      kramdown-parser-gfm (~> 1.1)
+      paintbrush (~> 0.1.3)
+      redcarpet (~> 3.6)
+      rouge (~> 4.1)
+      rspec (~> 3.12)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
     concurrent-ruby (1.2.2)
+    devpack (0.4.1)
     diff-lcs (1.5.0)
+    htmlbeautifier (1.4.2)
     i18n (1.13.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     paint (2.3.0)
+    paintbrush (0.1.3)
     parallel (1.23.0)
     parser (3.2.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
+    redcarpet (3.6.0)
     regexp_parser (2.8.0)
     rexml (3.2.5)
+    rouge (4.1.1)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -29,6 +45,11 @@ GEM
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
+    rspec-file_fixtures (0.1.6)
+      rspec (~> 3.0)
+    rspec-its (1.3.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
     rspec-mocks (3.12.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
@@ -62,13 +83,15 @@ GEM
     unicode-display_width (2.4.2)
 
 PLATFORMS
-  ruby
   x86_64-linux
 
 DEPENDENCIES
+  devpack (~> 0.4.1)
   rake (~> 13.0)
   rspec (~> 3.0)
   rspec-documentation!
+  rspec-file_fixtures (~> 0.1.6)
+  rspec-its (~> 1.3)
   rubocop (~> 1.51)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.22)

data/Makefile

@@ -1,5 +1,14 @@
+project=rspec-documentation
+
 .PHONY: test
 test:
 	bundle exec rspec
 	bundle exec rubocop
 	bundle exec strong_versions
+	exe/rspec-documentation
+
+.PHONY: publish
+publish:
+	@RSPEC_DOCUMENTATION_URL_ROOT='/$(project)' exe/rspec-documentation
+	@rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/$(project)/
+	@echo 'Published.'

data/README.md

@@ -1,31 +1,27 @@
-# Rspec::Documentation
+# RSpec::Documentation
 
-TODO: Delete this and the text below, and describe your gem
+_RSpec Documentation_ provides a simple but powerful system for generating _Ruby_ documentation using [_RSpec_](https://rspec.info/) designed to help you ensure that all code examples in your documentation really work.
 
-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/rspec/documentation`. To experiment with that code, run `bin/console` for an interactive prompt.
+* Create a tree of _Markdown_ files in your project directory under `rspec-documentation/pages/`.
+* Embed tests in ```` ```rspec ```` code blocks (other output formatters are available - see examples).
+* Define a `subject` for each test.
+* Run the provided `rspec-documentation` command.
 
-## Installation
+There is no _DSL_ to learn and vanilla _RSpec_ examples are used to generate inputs and outputs. No _Markdown_ language extensions are used, simply define the language of a fenced code block as `rspec` in any `.md` file and _RSpecDocumentation_ will do the rest.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Quick Example
 
-Install the gem and add to the application's Gemfile by executing:
+The following is an example _Markdown_ file.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+````console
+# An example test
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+This is a very simple test:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```rspec
+subject { 'my subject' }
+it { is_expected.to eql 'my subject' }
+```
+````
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rspec-documentation.
+View the [full documentation](https://docs.bob.frl/rspec-documentation) (built using Rspec Documentation!) for detailed usage instructions.

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rspec/documentation'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/exe/rspec-documentation

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/rspec/documentation'
+
+# Try to load Rails and config/environment.rb, but don't panic if not present, we only use Rails
+# to fetch things like application name etc.
+begin
+  require 'rails'
+  require Pathname.new(Dir.pwd).join('config/environment')
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+documentation = RSpec::Documentation.generate_documentation
+
+exit 1 if documentation.failed?
+exit 0

data/lib/rspec/documentation/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Rspec
+module RSpec
   module Documentation
-    VERSION = '0.0.1'
+    VERSION = '0.0.3'
   end
 end

data/lib/rspec/documentation.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
 require_relative 'documentation/version'
+require_relative '../rspec_documentation'
+load File.expand_path(File.join(__dir__, '../tasks/rspec/documentation/generate.rake'))
 
-module Rspec
+module RSpec
+  # Extension for RSpec, locates RSpec examples found in a Markdown file and executes them,
+  # replacing their output into a tree of Markdown files.
   module Documentation
     class Error < StandardError; end
-    # Your code goes here...
+
+    class << self
+      def generate_documentation
+        RSpecDocumentation::Documentation.new.tap(&:generate)
+      end
+
+      def configure(&block)
+        RSpecDocumentation.configure(&block)
+      end
+    end
   end
 end

data/lib/rspec_documentation/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Configures the rspec-documentation gem, allows setting a context that makes values available to each example.
+  class Configuration
+    def initialize
+      @context_defined = false
+    end
+
+    def context_defined?
+      @context_defined
+    end
+
+    def attribution
+      return @attribution if defined?(@attribution)
+
+      'Documentation generated by ' \
+        '<a target="_blank" href="https://github.com/bobf/rspec-documentation">rspec-documentation</a>'
+    end
+
+    def context(&block)
+      raise Error, 'RSpecDocumentation context has already been defined.' if context_defined?
+
+      @context_defined = true
+      ::RSpec.shared_context('__rspec_documentation', &block)
+    end
+  end
+end

data/lib/rspec_documentation/document.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Translates a Markdown document into a structure of parsed Markdown and embedded RSpec examples.
+  class Document
+    attr_reader :failures, :page_tree
+
+    def initialize(document:, path:, page_tree:)
+      @document = document
+      @path = path
+      @page_tree = page_tree
+      @failures = []
+    end
+
+    def specs
+      @specs ||= parsed_document.specs
+    end
+
+    def render
+      parsed_document.execute_and_substitute_examples!
+      if parsed_document.failures.empty?
+        RSpecDocumentation.template('layout').result(binding)
+      else
+        failures.concat(parsed_document.failures)
+        nil
+      end
+    end
+
+    def html
+      parsed_document.html
+    end
+
+    def title
+      return ::Rails.application.class.module_parent.name.titleize if defined?(::Rails)
+
+      gem_spec&.name
+    end
+
+    def version
+      gem_spec&.version
+    end
+
+    def homepage
+      gem_spec&.homepage
+    end
+
+    def header
+      RSpecDocumentation.template('header').result(binding)
+    end
+
+    def footer
+      RSpecDocumentation.template('footer').result(binding)
+    end
+
+    def stylesheet_bundle_href
+      Util.assets_root.join('bundle.css')
+    end
+
+    def javascript_bundle_src
+      Util.assets_root.join('bundle.js')
+    end
+
+    private
+
+    attr_reader :document, :path
+
+    def parsed_document
+      @parsed_document ||= ParsedDocument.new(document, path: path)
+    end
+
+    def gem_spec
+      @gem_spec ||= Gem::Specification.load(Pathname.new(Dir.pwd).glob('*.gemspec').first.to_s)
+    end
+  end
+end

data/lib/rspec_documentation/documentation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  # Generates documentation from Markdown files, main entry point to documentation generator.
+  class Documentation
+    include Paintbrush
+
+    def generate
+      initialize_if_empty
+      start
+      require_spec_helper
+      ensure_context
+      page_collection.generate
+      flush unless failed?
+      summary.flush
+    rescue RSpecDocumentation::MissingFileError => e
+      warn(paintbrush { red e.message })
+      @failed = true
+    end
+
+    def failed?
+      @failed || !page_collection.failures.empty?
+    end
+
+    private
+
+    def require_spec_helper
+      path = pwd.join('rspec-documentation/spec_helper.rb')
+      require path if path.file?
+    end
+
+    # Ensure `__rspec_documentation` shared context is always defined.
+    # See lib/rspec_documenation/spec.rb
+    def ensure_context
+      return if RSpecDocumentation.configuration.context_defined?
+
+      RSpecDocumentation.configuration.context {} # rubocop:disable Lint/EmptyBlock
+    end
+
+    def start
+      warn(paintbrush { white "\nRunning specs..." })
+      @started_at = Time.now.utc
+    end
+
+    def initialize_if_empty
+      return if Util.base_dir.exist?
+
+      ProjectInitialization.new.flush
+    end
+
+    def summary
+      @summary ||= RSpecDocumentation::Summary.new(
+        page_collection: page_collection,
+        pwd: pwd,
+        started_at: @started_at
+      )
+    end
+
+    def flush
+      page_collection.flush
+      stylesheet_bundle.flush
+      javascript_bundle.flush
+    end
+
+    def stylesheet_bundle
+      @stylesheet_bundle ||= RSpecDocumentation::StylesheetBundle.new
+    end
+
+    def javascript_bundle
+      @javascript_bundle ||= RSpecDocumentation::JavascriptBundle.new
+    end
+
+    def page_paths
+      @page_paths ||= pwd.join('rspec-documentation/pages').glob('**/*.md')
+    end
+
+    def page_collection
+      @page_collection ||= RSpecDocumentation::PageCollection.new(page_paths: page_paths)
+    end
+
+    def pwd
+      @pwd ||= Pathname.new(Dir.pwd)
+    end
+  end
+end

data/lib/rspec_documentation/formatters/ansi.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    COLOR_CODES = [0, 1, 2, 3, 4, 5, 6, 7, 9].freeze
+
+    # Outputs a string containing ANSI color code escape sequences into HTML with attached
+    # classes for each matched color code. Cleans any remaining escape codes.
+    class Ansi
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        "<div class='ansi-html border m-1 p-4'><span>#{subbed_content}</span></div>"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+
+      def subbed_content
+        COLOR_CODES.reduce(subbed_hex_codes) do |string, color_code|
+          string&.gsub("\e[3#{color_code}m", "</span><span class='ansi-color-#{color_code}'>")
+                &.gsub("\e[9#{color_code}m", "</span><span class='ansi-bright ansi-color-#{color_code}'>")
+                &.gsub(/\e\[38;5;([0-9]{1,3})m/, "</span><span class='ansi-color-\\1'>")
+                &.gsub("\e[0m", "</span><span class='ansi-color-reset'>")
+        end&.gsub(/\e\[[0-9;]+m/, '')
+      end
+
+      def subbed_hex_codes
+        subject&.gsub(/\e\[38;2;([0-9]+);([0-9]+);([0-9]+)m/, '</span><span style="color: rgb(\1,\2,\3)">')
+      end
+    end
+  end
+end

data/lib/rspec_documentation/formatters/html.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Beautifies HTML received from a `subject`, renders the raw subject to be inserted directly
+    # into the output document.
+    class Html
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::HTML.new
+        formatter.format(lexer.lex(HtmlBeautifier.beautify(subject)))
+      end
+
+      def rendered_output
+        subject
+      end
+
+      def render_raw?
+        true
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/json.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Produces prettified JSON to from an RSpec `subject` value.
+    class Json
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::JSON.new
+        formatter.format(lexer.lex(JSON.pretty_generate(JSON.parse(subject))))
+      rescue JSON::ParserError => e
+        raise Error, "Expected JSON for:\n#{subject}\n\nParser Error: #{e}"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/ruby.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Default formatter for all RSpec examples. Used by all examples to generate the "Spec" tab
+    # content, i.e. the original source of the example code.
+    class Ruby
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::Ruby.new
+        formatter.format(lexer.lex(subject.inspect))
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+    end
+  end
+end

data/lib/rspec_documentation/formatters/yaml.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RSpecDocumentation
+  module Formatters
+    # Produces prettified YAML to from an RSpec `subject` value.
+    class Yaml
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      def prettified_output
+        nil
+      end
+
+      def rendered_output
+        formatter = Rouge::Formatters::HTML.new
+        lexer = Rouge::Lexers::YAML.new
+        formatter.format(lexer.lex(YAML.safe_load(subject, permitted_classes: permitted_classes).to_yaml))
+      rescue Psych::SyntaxError => e
+        raise Error, "Expected YAML for:\n#{subject}\n\nSyntax Error: #{e}"
+      end
+
+      def render_raw?
+        false
+      end
+
+      private
+
+      attr_reader :subject
+
+      def permitted_classes
+        [Symbol, Date, Time, DateTime]
+      end
+    end
+  end
+end

data/lib/rspec_documentation/formatters.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'formatters/ruby'
+require_relative 'formatters/html'
+require_relative 'formatters/ansi'
+require_relative 'formatters/json'
+require_relative 'formatters/yaml'
+
+module RSpecDocumentation
+  # Provides a set of formatters for rendering the value of a `subject` in an RSpec example into
+  # a useful format according to the language specified in the relevant Markdown code block, e.g.
+  # `rspec:html` will use the `Html` formatter to render beautified HTML source and the rendered
+  # output.
+  module Formatters
+    def self.with_translated_html_entities(content)
+      content&.gsub("\n", '<br/>')
+             &.gsub('  ', '&nbsp;&nbsp;')
+    end
+  end
+end