roxie 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75b077a1a282d969b55de2bae3f50284b5837a02
-  data.tar.gz: 7b0554af4dd65c7d1a05faf361eb62726d89e479
+  metadata.gz: 7cf03027a4a21a7ecde139fc88e2ba1dc2d161fb
+  data.tar.gz: 98e6e8c9405f4e5a4f1d28010fd9c4071c6f3650
 SHA512:
-  metadata.gz: 2dcb1026d2d8e9a85123be6f2057b9e390c04fd0a9d9f7f958e17736ea18c4783792e7340ce410a7b6ce2f867e087a9c8bd9b2e3f8d56bec7fbdff164a2b5754
-  data.tar.gz: e1add78a103d5ea6f8c19a2451ad940a52b3945ff7fe17ef8e5259e066922ec04c9d30c3581383f20c5d795bf43741237e2d3d2f24d84e3b912c3bc3f340ced9
+  metadata.gz: bcee265575f308d67a0f7da3c3218f7bc33fe98f9c84de6dec4f601f8fade863eaec096b8845435a481160d65a538950cf122b3968b6f827bb3f24637267c73a
+  data.tar.gz: 59e7bb0fefd859f1b8d06f7d0be7138655f12b600c1f25313b85098d59a4b1345d773afecffd821e931788070793a76d28fb903f593012f57dc5cfbc1ce50453

data/.travis.yml

@@ -4,5 +4,8 @@ rvm:
   - 1.9.2
   - 1.9.3
   - 2.0.0
-  - jruby-19mode
+  # - jruby-19mode
   - rbx-19mode
+notifications:
+  email:
+    on_failure: change

data/README.md

@@ -1,5 +1,11 @@
 # Roxie
 
+[![Build Status](https://travis-ci.org/mbarvian/roxie.png?branch=master)](https://travis-ci.org/mbarvian/roxie)
+[![Coverage Status](https://coveralls.io/repos/mbarvian/roxie/badge.png?branch=master)](https://coveralls.io/r/mbarvian/roxie?branch=master)
+[![Code Climate](https://codeclimate.com/github/mbarvian/roxie.png)](https://codeclimate.com/github/mbarvian/roxie)
+[![Dependency Status](https://gemnasium.com/mbarvian/roxie.png)](https://gemnasium.com/mbarvian/roxie)
+[![Gem Version](https://badge.fury.io/rb/roxie.png)](http://badge.fury.io/rb/roxie)
+
 Minimal [Dox](https://github.com/visionmedia/dox) and [Rocco](https://github.com/rtomayko/rocco)-inspired documentation generator written in Ruby.
 
 ## Installation
@@ -18,7 +24,97 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+There are a few different ways to generate documentation with Roxie.  The first is through the command line, like so:
+
+```
+# Generates documentation for all .rb files in the current directory (recursive)
+$ roxie **/*.rb
+```
+
+You can get a full list of the switches and commands you can use by running `roxie help [COMMAND]`.
+
+You can also use Roxie as a Rake task, similar to Yard.  Here's an example of a simple Rakefile with a custom Roxie task:
+
+```ruby
+require 'roxie/rake/task'
+Roxie::Rake::Task.new(:doc) do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = [
+    '--only-tagged',
+    '--force'
+  ]
+end
+
+task :default => :doc
+```
+
+By default, the task name is `roxie`, but you can change it to be anything you'd like by passing in a new name to the constructor.  It's also worth noting that `t.files` can be a `Rake::FileList`.
+
+Finally, you can use Roxie by itself as a normal Ruby gem.  Here's a sample snippet that will extract all the comments from the tiny JavaScript string:
+
+```ruby
+require 'roxie'
+
+js = <<-JS
+  /**
+   * Escape the given `html`.
+   *
+   * Examples:
+   *
+   *     utils.escape('<script></script>')
+   *     // => '&lt;script&gt;&lt;/script&gt;'
+   *
+   * @param {String} html string to be escaped
+   * @return {String} escaped html
+   * @api public
+   */
+
+  exports.escape = function(html){
+    return String(html)
+      .replace(/&(?!\w+;)/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  };
+JS
+
+Roxie.extract(js, :language => 'JavaScript')
+
+# => [
+#   {
+#     :description => "Escape the given `html`.\\n\\nExamples:\\n\\n    utils.escape('<script></script>')\\n    // => '&lt;script&gt;&lt;/script&gt;'",
+#     :tags => [
+#       {
+#         :type => "param",
+#         :description => "{String} html string to be escaped"
+#       },
+#       {
+#         :type => "return",
+#         :description => "{String} escaped html"
+#       },
+#       {
+#         :type => "api",
+#         :description => "public"
+#       }
+#     ],
+#     :line => 14
+#   }
+# ]
+```
+
+### Configuring
+
+You can pass in a hash as the second parameter of `Roxie.extract()` to configure the extractor.  Here are the supported options:
+
+Option                      | Description
+----------------------------|-----------------------------------------------------------------
+`:language`                 | The language of the input as specified in `languages.yml`
+`:only_tagged`              | Only extract comments that have `@tags` in them
+`:only_single`              | Only extract single-line comments
+`:only_multi`               | Only extract multi-line comments
+
+### Note
+
+Roxie itself does very little by design.  I wanted something language-agnostic that I could use to feed into a custom [Middleman](http://middlemanapp.com/) site.  As a result, the only functionality Roxie includes is extracting `@tags` from comment blocks.  Beyond that, how you display your documentation is completely up to you.
 
 ## Contributing
 

data/Rakefile

@@ -1,5 +1,8 @@
 require 'bundler/gem_tasks'
 
+require 'rake/clean'
+CLEAN.include('coverage', 'doc', 'pkg', 'tmp')
+
 require 'roxie/rake/task'
 Roxie::Rake::Task.new do |t|
   t.files = ['lib/**/*.rb']

data/features/cli.feature

@@ -7,3 +7,7 @@ Feature: Roxie Base CLI
   Scenario: Print out the version number
     Given I run `roxie version`
     Then the output should contain "Roxie"
+
+  Scenario: Check for unknown switches
+    Given I run `roxie --crazy-unknown-switch`
+    Then the output should contain "Unknown switch"

data/features/generator.feature

@@ -3,6 +3,61 @@ Feature: Documentation Generator
   Scenario: Build empty app
     Given an empty app
     When I run `roxie`
+    Then was successfully generated
+    Then the docs should not contain "tags:"
+
+  Scenario: Build empty app with alias `d`
+    Given an empty app
+    When I run `roxie d`
+    Then was successfully generated
+
+  Scenario: Build empty app with custom output
+    Given an empty app
+    When I successfully run `roxie -o documentation/reference.json`
     Then the following files should exist:
-      | doc/api.json                                  |
-    And the file "doc/api.json" should not contain "tags:"
+      | documentation/reference.json                        |
+
+  Scenario: Build mixed app with default options
+    Given I successfully generate "mixed" with `roxie **/*`
+    Then the docs should contain "index.coffee"
+    And the docs should not contain "This line should not be documented"
+    And the docs should contain '"type": "module"'
+
+  Scenario: Build mixed app with only multi-line comments
+    Given I successfully generate "mixed" with `roxie **/* --only-multi`
+    Then the docs should contain "index.coffee"
+    And the docs should not contain "single line"
+
+  Scenario: Build mixed app with only single-line comments
+    Given I successfully generate "mixed" with `roxie **/* --only-single`
+    Then the docs should contain "index.coffee"
+    And the docs should contain "single line"
+
+  Scenario: Build multi-language app with only tagged comments
+    Given I successfully generate "multi-language" with `roxie **/* --only-tagged`
+    Then the docs should contain "utils.js"
+    Then the docs should contain "functions.scss"
+    And the docs should not contain "test.coffee"
+    And the docs should not contain "default.css"
+
+  Scenario: Build app with fallback language
+    Given I successfully generate "incorrect-extensions" with `roxie **/* -l JavaScript`
+    Then the docs should contain "utils.javascripty"
+    Then the docs should contain "global.css"
+
+  Scenario: Build app with specified base path
+    Given I successfully generate "specific-base" with `roxie hello_world.rb --base-path codebase`
+    Then the docs should contain "hello_world.rb"
+
+  Scenario: Build app with excludes
+    Given I successfully generate "ignores" with `roxie **/*.js -x ignore`
+    Then the docs should not contain "ignore"
+
+  Scenario: Build app with EOL comments
+    Given I successfully generate "eol" with `roxie **/*.js --only-single`
+    Then the docs should not contain '"line":'
+
+  Scenario: Build app with errors
+    Given a fixture app "doomed"
+    When I run `roxie **/*.js`
+    Then the exit status should be 1

data/features/step_definitions/generator_steps.rb

@@ -5,6 +5,15 @@ Given /^an empty app$/ do
   step %Q{I cd to "empty_app"}
 end
 
+Given /^was successfully generated$/ do
+  step %Q{a directory named "doc" should exist}
+  step %Q{the exit status should be 0}
+end
+
+Given /^was unsuccessfully generated$/ do
+  step %Q{the exit status should be 1}
+end
+
 Given /^a fixture app "([^\"]*)"$/ do |path|
   # This step can be reentered from several places but we don't want
   # to keep re-copying and re-cd-ing into ever-deeper directories
@@ -18,7 +27,33 @@ Given /^a fixture app "([^\"]*)"$/ do |path|
   step %Q{I cd to "#{path}"}
 end
 
-# Provide this Aruba overload in case we're matching something with quotes in it
+Given /^I successfully generate "([^\"]*)" with `(.*?)`$/ do |path, cmd|
+  step %Q{a fixture app "#{path}"}
+  step %Q{I run `#{cmd}`}
+  step %Q{was successfully generated}
+end
+
+# Provide these Aruba overload in case we're matching something with quotes in it
 Then /^the file "([^"]*)" should contain '([^']*)'$/ do |file, partial_content|
   check_file_content(file, partial_content, true)
 end
+
+Then /^the file "([^"]*)" should not contain '([^']*)'$/ do |file, partial_content|
+  check_file_content(file, partial_content, false)
+end
+
+Then /^the docs should contain "(.*?)"$/ do |partial_content|
+  step %Q{the file "doc/api.json" should contain "#{partial_content}"}
+end
+
+Then /^the docs should contain '([^']*)'$/ do |partial_content|
+  step %Q{the file "doc/api.json" should contain '#{partial_content}'}
+end
+
+Then /^the docs should not contain "(.*?)"$/ do |partial_content|
+  step %Q{the file "doc/api.json" should not contain "#{partial_content}"}
+end
+
+Then /^the docs should not contain '([^']*)'$/ do |partial_content|
+  step %Q{the file "doc/api.json" should not contain '#{partial_content}'}
+end

data/fixtures/doomed/utils.js

@@ -0,0 +1,10 @@
+var hello = function() {
+  return "hello";
+}
+
+/**
+ * This comment extends into oblivion and will surely crash
+ * Roxie, as Roxie doesn't check against syntax
+ * errors like these.
+
+myVar = 123;

data/fixtures/eol/main.js

@@ -0,0 +1,10 @@
+/**
+ * This comment should be picked up just fine.
+ */
+
+function sayHello() {
+  alert("Hello world!");
+}
+
+// This comment has no code after it, so it should
+// not have an associated line number.

data/fixtures/ignores/ignore.js

@@ -0,0 +1,7 @@
+/**
+ * This file should be ignored.
+ */
+
+function annoy() {
+  alert("Howdy");
+}

data/fixtures/ignores/ignore/util.js

@@ -0,0 +1,7 @@
+/**
+ * This file should also be ignored
+ */
+
+function getMessage() {
+  return "Hello world!";
+}

data/fixtures/ignores/included.js

@@ -0,0 +1,7 @@
+/**
+ * This file should be included
+ */
+
+function sayHello() {
+  console.log("Hello world!");
+}

data/fixtures/incorrect-extensions/css/global.css

@@ -0,0 +1,6 @@
+/**
+ * Style the body tag.
+ */
+body {
+  font-size: 1.25em;
+}

data/fixtures/incorrect-extensions/js/utils.javascripty

@@ -0,0 +1,19 @@
+/**
+ * Escape the given `html`.
+ *
+ * Examples:
+ *
+ *     utils.escape('<script></script>')
+ *     // => '&lt;script&gt;&lt;/script&gt;'
+ *
+ * @param {String} html string to be escaped
+ * @return {String} escaped html
+ * @api public
+ */
+
+exports.escape = function(html){
+  return String(html)
+    .replace(/&(?!\w+;)/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+};

data/fixtures/mixed/index.coffee

@@ -0,0 +1,28 @@
+###
+# Roxie example documentation
+
+This is a module-level docstring, and will be displayed at the top of the module documentation.
+@module {MyClass}
+@extends {Superclass}
+###
+
+class MyClass extends Superclass
+  ###
+  This docstring documents MyClass. It can include *Markdown* syntax,
+  which will be converted to html.
+  ###
+  constructor: (@args) ->
+    ### Constructor documentation goes here. ###
+
+  # As you can see, it supports single line comments
+  # as well!
+  method: (args) ->
+    ### Print out a sample string
+    and then return ###
+    console.log "Hello world!"
+
+myFunc = (arg1, arg2, args...) ->
+  ###
+  This function will be documented as well
+  ###
+  doSomething() # This line should not be documented

data/fixtures/multi-language/css/default.css

@@ -0,0 +1,7 @@
+/**
+ * Styles the body tag for the entire page.
+ */
+
+body {
+  font-size: 150%; /* this shouldn't be commented */
+}

data/fixtures/multi-language/css/functions.scss

@@ -0,0 +1,14 @@
+/**
+ * Converts a px-based value to a rem-based one.
+ *
+ * @param px the px-based value to convert
+ * @return px in rems
+ */
+
+@function remify($val) {
+  @if type_of($val) != number or unit($val) != "px" {
+    @return $val;
+  } @else {
+    @return ($val * $baseline-rem);
+  }
+}

data/fixtures/multi-language/js/test.coffee

@@ -0,0 +1,26 @@
+###
+# Roxie example documentation
+
+This is a module-level docstring, and will be displayed at the top of the module documentation.
+###
+
+class MyClass extends Superclass
+  ###
+  This docstring documents MyClass. It can include *Markdown* syntax,
+  which will be converted to html.
+  ###
+  constructor: (@args) ->
+    ### Constructor documentation goes here. ###
+
+  # As you can see, it supports single line comments
+  # as well!
+  method: (args) ->
+    ### Print out a sample string
+    and then return ###
+    console.log "Hello world!"
+
+myFunc = (arg1, arg2, args...) ->
+  ###
+  This function will be documented as well
+  ###
+  doSomething() # This line should not be documented

data/fixtures/multi-language/js/utils.js

@@ -0,0 +1,19 @@
+/**
+ * Escape the given `html`.
+ *
+ * Examples:
+ *
+ *     utils.escape('<script></script>')
+ *     // => '&lt;script&gt;&lt;/script&gt;'
+ *
+ * @param {String} html string to be escaped
+ * @return {String} escaped html
+ * @api public
+ */
+
+exports.escape = function(html){
+  return String(html)
+    .replace(/&(?!\w+;)/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+};

data/fixtures/specific-base/codebase/hello_world.rb

@@ -0,0 +1,21 @@
+# A simple application
+#
+# @module {MyApplication}
+module MyApplication
+  class HelloWorld
+
+    def initialize
+      @message = "Hello world!"
+    end
+
+    # Output "Hello world!"
+    #
+    # @api public
+    def log_message
+      puts @message
+    end
+
+  end
+end
+
+MyApplication::HelloWorld.new.log_message

data/lib/roxie/cli/doc.rb

@@ -86,7 +86,9 @@ module Roxie
           }.reject { |k, v| v.nil? }
 
           # Extract relevant comments out of file
-          @docs[file] = Roxie.extract(data, opts)
+          if doc = Roxie.extract(data, opts)
+            @docs[file] = doc unless doc.empty?
+          end
         end
       end
 

data/lib/roxie/extractor.rb

@@ -16,15 +16,15 @@ module Roxie
 
     def initialize(options = {})
       @options = self.class.default_options.merge(options)
-      unless @language = LANGUAGES[@options[:language]]
-        logger.warn "Roxie doesn't understand #{@options[:language]}"
-      end
+      @language = LANGUAGES[@options[:language]]
     end
 
     # Read up to 100KB
     BYTE_LIMIT = 100_000
 
     def extract(text)
+      return unless @language
+
       @code = text.dup
       @scanner = StringScanner.new(@code)
 
@@ -71,7 +71,7 @@ module Roxie
           @scanner.scan_until(/(?=\S)/)
           comment[:line] = @code[0..@scanner.pos].count("\n") + 1 unless @scanner.eos?
 
-          comments << comment unless @options[:only_tagged] && comment[:tags].empty?
+          comments << comment unless @options[:only_tagged] && tags.empty?
         else
           # Skip line
           @scanner.skip_until(/\n|\Z/)

data/lib/roxie/languages.yml

@@ -46,6 +46,12 @@ CoffeeScript:
 Common Lisp:
   single: ";"
 
+CSS:
+  multi:
+    start: "/**"
+    middle: "*"
+    end: "*/"
+
 D:
   single: "//"
   multi:

data/lib/roxie/version.rb

@@ -1,3 +1,3 @@
 module Roxie
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roxie
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Maxwell Barvian
@@ -59,6 +59,19 @@ files:
 - features/generator.feature
 - features/step_definitions/generator_steps.rb
 - features/support/env.rb
+- fixtures/doomed/utils.js
+- fixtures/eol/main.js
+- fixtures/ignores/ignore.js
+- fixtures/ignores/ignore/util.js
+- fixtures/ignores/included.js
+- fixtures/incorrect-extensions/css/global.css
+- fixtures/incorrect-extensions/js/utils.javascripty
+- fixtures/mixed/index.coffee
+- fixtures/multi-language/css/default.css
+- fixtures/multi-language/css/functions.scss
+- fixtures/multi-language/js/test.coffee
+- fixtures/multi-language/js/utils.js
+- fixtures/specific-base/codebase/hello_world.rb
 - lib/roxie.rb
 - lib/roxie/cli.rb
 - lib/roxie/cli/doc.rb