roxie 0.0.2 → 0.0.3
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.travis.yml +4 -1
- data/README.md +97 -1
- data/Rakefile +3 -0
- data/features/cli.feature +4 -0
- data/features/generator.feature +57 -2
- data/features/step_definitions/generator_steps.rb +36 -1
- data/fixtures/doomed/utils.js +10 -0
- data/fixtures/eol/main.js +10 -0
- data/fixtures/ignores/ignore.js +7 -0
- data/fixtures/ignores/ignore/util.js +7 -0
- data/fixtures/ignores/included.js +7 -0
- data/fixtures/incorrect-extensions/css/global.css +6 -0
- data/fixtures/incorrect-extensions/js/utils.javascripty +19 -0
- data/fixtures/mixed/index.coffee +28 -0
- data/fixtures/multi-language/css/default.css +7 -0
- data/fixtures/multi-language/css/functions.scss +14 -0
- data/fixtures/multi-language/js/test.coffee +26 -0
- data/fixtures/multi-language/js/utils.js +19 -0
- data/fixtures/specific-base/codebase/hello_world.rb +21 -0
- data/lib/roxie/cli/doc.rb +3 -1
- data/lib/roxie/extractor.rb +4 -4
- data/lib/roxie/languages.yml +6 -0
- data/lib/roxie/version.rb +1 -1
- metadata +14 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 7cf03027a4a21a7ecde139fc88e2ba1dc2d161fb
|
4
|
+
data.tar.gz: 98e6e8c9405f4e5a4f1d28010fd9c4071c6f3650
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: bcee265575f308d67a0f7da3c3218f7bc33fe98f9c84de6dec4f601f8fade863eaec096b8845435a481160d65a538950cf122b3968b6f827bb3f24637267c73a
|
7
|
+
data.tar.gz: 59e7bb0fefd859f1b8d06f7d0be7138655f12b600c1f25313b85098d59a4b1345d773afecffd821e931788070793a76d28fb903f593012f57dc5cfbc1ce50453
|
data/.travis.yml
CHANGED
data/README.md
CHANGED
@@ -1,5 +1,11 @@
|
|
1
1
|
# Roxie
|
2
2
|
|
3
|
+
[![Build Status](https://travis-ci.org/mbarvian/roxie.png?branch=master)](https://travis-ci.org/mbarvian/roxie)
|
4
|
+
[![Coverage Status](https://coveralls.io/repos/mbarvian/roxie/badge.png?branch=master)](https://coveralls.io/r/mbarvian/roxie?branch=master)
|
5
|
+
[![Code Climate](https://codeclimate.com/github/mbarvian/roxie.png)](https://codeclimate.com/github/mbarvian/roxie)
|
6
|
+
[![Dependency Status](https://gemnasium.com/mbarvian/roxie.png)](https://gemnasium.com/mbarvian/roxie)
|
7
|
+
[![Gem Version](https://badge.fury.io/rb/roxie.png)](http://badge.fury.io/rb/roxie)
|
8
|
+
|
3
9
|
Minimal [Dox](https://github.com/visionmedia/dox) and [Rocco](https://github.com/rtomayko/rocco)-inspired documentation generator written in Ruby.
|
4
10
|
|
5
11
|
## Installation
|
@@ -18,7 +24,97 @@ Or install it yourself as:
|
|
18
24
|
|
19
25
|
## Usage
|
20
26
|
|
21
|
-
|
27
|
+
There are a few different ways to generate documentation with Roxie. The first is through the command line, like so:
|
28
|
+
|
29
|
+
```
|
30
|
+
# Generates documentation for all .rb files in the current directory (recursive)
|
31
|
+
$ roxie **/*.rb
|
32
|
+
```
|
33
|
+
|
34
|
+
You can get a full list of the switches and commands you can use by running `roxie help [COMMAND]`.
|
35
|
+
|
36
|
+
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:
|
37
|
+
|
38
|
+
```ruby
|
39
|
+
require 'roxie/rake/task'
|
40
|
+
Roxie::Rake::Task.new(:doc) do |t|
|
41
|
+
t.files = ['lib/**/*.rb']
|
42
|
+
t.options = [
|
43
|
+
'--only-tagged',
|
44
|
+
'--force'
|
45
|
+
]
|
46
|
+
end
|
47
|
+
|
48
|
+
task :default => :doc
|
49
|
+
```
|
50
|
+
|
51
|
+
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`.
|
52
|
+
|
53
|
+
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:
|
54
|
+
|
55
|
+
```ruby
|
56
|
+
require 'roxie'
|
57
|
+
|
58
|
+
js = <<-JS
|
59
|
+
/**
|
60
|
+
* Escape the given `html`.
|
61
|
+
*
|
62
|
+
* Examples:
|
63
|
+
*
|
64
|
+
* utils.escape('<script></script>')
|
65
|
+
* // => '<script></script>'
|
66
|
+
*
|
67
|
+
* @param {String} html string to be escaped
|
68
|
+
* @return {String} escaped html
|
69
|
+
* @api public
|
70
|
+
*/
|
71
|
+
|
72
|
+
exports.escape = function(html){
|
73
|
+
return String(html)
|
74
|
+
.replace(/&(?!\w+;)/g, '&')
|
75
|
+
.replace(/</g, '<')
|
76
|
+
.replace(/>/g, '>');
|
77
|
+
};
|
78
|
+
JS
|
79
|
+
|
80
|
+
Roxie.extract(js, :language => 'JavaScript')
|
81
|
+
|
82
|
+
# => [
|
83
|
+
# {
|
84
|
+
# :description => "Escape the given `html`.\\n\\nExamples:\\n\\n utils.escape('<script></script>')\\n // => '<script></script>'",
|
85
|
+
# :tags => [
|
86
|
+
# {
|
87
|
+
# :type => "param",
|
88
|
+
# :description => "{String} html string to be escaped"
|
89
|
+
# },
|
90
|
+
# {
|
91
|
+
# :type => "return",
|
92
|
+
# :description => "{String} escaped html"
|
93
|
+
# },
|
94
|
+
# {
|
95
|
+
# :type => "api",
|
96
|
+
# :description => "public"
|
97
|
+
# }
|
98
|
+
# ],
|
99
|
+
# :line => 14
|
100
|
+
# }
|
101
|
+
# ]
|
102
|
+
```
|
103
|
+
|
104
|
+
### Configuring
|
105
|
+
|
106
|
+
You can pass in a hash as the second parameter of `Roxie.extract()` to configure the extractor. Here are the supported options:
|
107
|
+
|
108
|
+
Option | Description
|
109
|
+
----------------------------|-----------------------------------------------------------------
|
110
|
+
`:language` | The language of the input as specified in `languages.yml`
|
111
|
+
`:only_tagged` | Only extract comments that have `@tags` in them
|
112
|
+
`:only_single` | Only extract single-line comments
|
113
|
+
`:only_multi` | Only extract multi-line comments
|
114
|
+
|
115
|
+
### Note
|
116
|
+
|
117
|
+
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.
|
22
118
|
|
23
119
|
## Contributing
|
24
120
|
|
data/Rakefile
CHANGED
data/features/cli.feature
CHANGED
@@ -7,3 +7,7 @@ Feature: Roxie Base CLI
|
|
7
7
|
Scenario: Print out the version number
|
8
8
|
Given I run `roxie version`
|
9
9
|
Then the output should contain "Roxie"
|
10
|
+
|
11
|
+
Scenario: Check for unknown switches
|
12
|
+
Given I run `roxie --crazy-unknown-switch`
|
13
|
+
Then the output should contain "Unknown switch"
|
data/features/generator.feature
CHANGED
@@ -3,6 +3,61 @@ Feature: Documentation Generator
|
|
3
3
|
Scenario: Build empty app
|
4
4
|
Given an empty app
|
5
5
|
When I run `roxie`
|
6
|
+
Then was successfully generated
|
7
|
+
Then the docs should not contain "tags:"
|
8
|
+
|
9
|
+
Scenario: Build empty app with alias `d`
|
10
|
+
Given an empty app
|
11
|
+
When I run `roxie d`
|
12
|
+
Then was successfully generated
|
13
|
+
|
14
|
+
Scenario: Build empty app with custom output
|
15
|
+
Given an empty app
|
16
|
+
When I successfully run `roxie -o documentation/reference.json`
|
6
17
|
Then the following files should exist:
|
7
|
-
|
|
8
|
-
|
18
|
+
| documentation/reference.json |
|
19
|
+
|
20
|
+
Scenario: Build mixed app with default options
|
21
|
+
Given I successfully generate "mixed" with `roxie **/*`
|
22
|
+
Then the docs should contain "index.coffee"
|
23
|
+
And the docs should not contain "This line should not be documented"
|
24
|
+
And the docs should contain '"type": "module"'
|
25
|
+
|
26
|
+
Scenario: Build mixed app with only multi-line comments
|
27
|
+
Given I successfully generate "mixed" with `roxie **/* --only-multi`
|
28
|
+
Then the docs should contain "index.coffee"
|
29
|
+
And the docs should not contain "single line"
|
30
|
+
|
31
|
+
Scenario: Build mixed app with only single-line comments
|
32
|
+
Given I successfully generate "mixed" with `roxie **/* --only-single`
|
33
|
+
Then the docs should contain "index.coffee"
|
34
|
+
And the docs should contain "single line"
|
35
|
+
|
36
|
+
Scenario: Build multi-language app with only tagged comments
|
37
|
+
Given I successfully generate "multi-language" with `roxie **/* --only-tagged`
|
38
|
+
Then the docs should contain "utils.js"
|
39
|
+
Then the docs should contain "functions.scss"
|
40
|
+
And the docs should not contain "test.coffee"
|
41
|
+
And the docs should not contain "default.css"
|
42
|
+
|
43
|
+
Scenario: Build app with fallback language
|
44
|
+
Given I successfully generate "incorrect-extensions" with `roxie **/* -l JavaScript`
|
45
|
+
Then the docs should contain "utils.javascripty"
|
46
|
+
Then the docs should contain "global.css"
|
47
|
+
|
48
|
+
Scenario: Build app with specified base path
|
49
|
+
Given I successfully generate "specific-base" with `roxie hello_world.rb --base-path codebase`
|
50
|
+
Then the docs should contain "hello_world.rb"
|
51
|
+
|
52
|
+
Scenario: Build app with excludes
|
53
|
+
Given I successfully generate "ignores" with `roxie **/*.js -x ignore`
|
54
|
+
Then the docs should not contain "ignore"
|
55
|
+
|
56
|
+
Scenario: Build app with EOL comments
|
57
|
+
Given I successfully generate "eol" with `roxie **/*.js --only-single`
|
58
|
+
Then the docs should not contain '"line":'
|
59
|
+
|
60
|
+
Scenario: Build app with errors
|
61
|
+
Given a fixture app "doomed"
|
62
|
+
When I run `roxie **/*.js`
|
63
|
+
Then the exit status should be 1
|
@@ -5,6 +5,15 @@ Given /^an empty app$/ do
|
|
5
5
|
step %Q{I cd to "empty_app"}
|
6
6
|
end
|
7
7
|
|
8
|
+
Given /^was successfully generated$/ do
|
9
|
+
step %Q{a directory named "doc" should exist}
|
10
|
+
step %Q{the exit status should be 0}
|
11
|
+
end
|
12
|
+
|
13
|
+
Given /^was unsuccessfully generated$/ do
|
14
|
+
step %Q{the exit status should be 1}
|
15
|
+
end
|
16
|
+
|
8
17
|
Given /^a fixture app "([^\"]*)"$/ do |path|
|
9
18
|
# This step can be reentered from several places but we don't want
|
10
19
|
# to keep re-copying and re-cd-ing into ever-deeper directories
|
@@ -18,7 +27,33 @@ Given /^a fixture app "([^\"]*)"$/ do |path|
|
|
18
27
|
step %Q{I cd to "#{path}"}
|
19
28
|
end
|
20
29
|
|
21
|
-
|
30
|
+
Given /^I successfully generate "([^\"]*)" with `(.*?)`$/ do |path, cmd|
|
31
|
+
step %Q{a fixture app "#{path}"}
|
32
|
+
step %Q{I run `#{cmd}`}
|
33
|
+
step %Q{was successfully generated}
|
34
|
+
end
|
35
|
+
|
36
|
+
# Provide these Aruba overload in case we're matching something with quotes in it
|
22
37
|
Then /^the file "([^"]*)" should contain '([^']*)'$/ do |file, partial_content|
|
23
38
|
check_file_content(file, partial_content, true)
|
24
39
|
end
|
40
|
+
|
41
|
+
Then /^the file "([^"]*)" should not contain '([^']*)'$/ do |file, partial_content|
|
42
|
+
check_file_content(file, partial_content, false)
|
43
|
+
end
|
44
|
+
|
45
|
+
Then /^the docs should contain "(.*?)"$/ do |partial_content|
|
46
|
+
step %Q{the file "doc/api.json" should contain "#{partial_content}"}
|
47
|
+
end
|
48
|
+
|
49
|
+
Then /^the docs should contain '([^']*)'$/ do |partial_content|
|
50
|
+
step %Q{the file "doc/api.json" should contain '#{partial_content}'}
|
51
|
+
end
|
52
|
+
|
53
|
+
Then /^the docs should not contain "(.*?)"$/ do |partial_content|
|
54
|
+
step %Q{the file "doc/api.json" should not contain "#{partial_content}"}
|
55
|
+
end
|
56
|
+
|
57
|
+
Then /^the docs should not contain '([^']*)'$/ do |partial_content|
|
58
|
+
step %Q{the file "doc/api.json" should not contain '#{partial_content}'}
|
59
|
+
end
|
@@ -0,0 +1,19 @@
|
|
1
|
+
/**
|
2
|
+
* Escape the given `html`.
|
3
|
+
*
|
4
|
+
* Examples:
|
5
|
+
*
|
6
|
+
* utils.escape('<script></script>')
|
7
|
+
* // => '<script></script>'
|
8
|
+
*
|
9
|
+
* @param {String} html string to be escaped
|
10
|
+
* @return {String} escaped html
|
11
|
+
* @api public
|
12
|
+
*/
|
13
|
+
|
14
|
+
exports.escape = function(html){
|
15
|
+
return String(html)
|
16
|
+
.replace(/&(?!\w+;)/g, '&')
|
17
|
+
.replace(/</g, '<')
|
18
|
+
.replace(/>/g, '>');
|
19
|
+
};
|
@@ -0,0 +1,28 @@
|
|
1
|
+
###
|
2
|
+
# Roxie example documentation
|
3
|
+
|
4
|
+
This is a module-level docstring, and will be displayed at the top of the module documentation.
|
5
|
+
@module {MyClass}
|
6
|
+
@extends {Superclass}
|
7
|
+
###
|
8
|
+
|
9
|
+
class MyClass extends Superclass
|
10
|
+
###
|
11
|
+
This docstring documents MyClass. It can include *Markdown* syntax,
|
12
|
+
which will be converted to html.
|
13
|
+
###
|
14
|
+
constructor: (@args) ->
|
15
|
+
### Constructor documentation goes here. ###
|
16
|
+
|
17
|
+
# As you can see, it supports single line comments
|
18
|
+
# as well!
|
19
|
+
method: (args) ->
|
20
|
+
### Print out a sample string
|
21
|
+
and then return ###
|
22
|
+
console.log "Hello world!"
|
23
|
+
|
24
|
+
myFunc = (arg1, arg2, args...) ->
|
25
|
+
###
|
26
|
+
This function will be documented as well
|
27
|
+
###
|
28
|
+
doSomething() # This line should not be documented
|
@@ -0,0 +1,14 @@
|
|
1
|
+
/**
|
2
|
+
* Converts a px-based value to a rem-based one.
|
3
|
+
*
|
4
|
+
* @param px the px-based value to convert
|
5
|
+
* @return px in rems
|
6
|
+
*/
|
7
|
+
|
8
|
+
@function remify($val) {
|
9
|
+
@if type_of($val) != number or unit($val) != "px" {
|
10
|
+
@return $val;
|
11
|
+
} @else {
|
12
|
+
@return ($val * $baseline-rem);
|
13
|
+
}
|
14
|
+
}
|
@@ -0,0 +1,26 @@
|
|
1
|
+
###
|
2
|
+
# Roxie example documentation
|
3
|
+
|
4
|
+
This is a module-level docstring, and will be displayed at the top of the module documentation.
|
5
|
+
###
|
6
|
+
|
7
|
+
class MyClass extends Superclass
|
8
|
+
###
|
9
|
+
This docstring documents MyClass. It can include *Markdown* syntax,
|
10
|
+
which will be converted to html.
|
11
|
+
###
|
12
|
+
constructor: (@args) ->
|
13
|
+
### Constructor documentation goes here. ###
|
14
|
+
|
15
|
+
# As you can see, it supports single line comments
|
16
|
+
# as well!
|
17
|
+
method: (args) ->
|
18
|
+
### Print out a sample string
|
19
|
+
and then return ###
|
20
|
+
console.log "Hello world!"
|
21
|
+
|
22
|
+
myFunc = (arg1, arg2, args...) ->
|
23
|
+
###
|
24
|
+
This function will be documented as well
|
25
|
+
###
|
26
|
+
doSomething() # This line should not be documented
|
@@ -0,0 +1,19 @@
|
|
1
|
+
/**
|
2
|
+
* Escape the given `html`.
|
3
|
+
*
|
4
|
+
* Examples:
|
5
|
+
*
|
6
|
+
* utils.escape('<script></script>')
|
7
|
+
* // => '<script></script>'
|
8
|
+
*
|
9
|
+
* @param {String} html string to be escaped
|
10
|
+
* @return {String} escaped html
|
11
|
+
* @api public
|
12
|
+
*/
|
13
|
+
|
14
|
+
exports.escape = function(html){
|
15
|
+
return String(html)
|
16
|
+
.replace(/&(?!\w+;)/g, '&')
|
17
|
+
.replace(/</g, '<')
|
18
|
+
.replace(/>/g, '>');
|
19
|
+
};
|
@@ -0,0 +1,21 @@
|
|
1
|
+
# A simple application
|
2
|
+
#
|
3
|
+
# @module {MyApplication}
|
4
|
+
module MyApplication
|
5
|
+
class HelloWorld
|
6
|
+
|
7
|
+
def initialize
|
8
|
+
@message = "Hello world!"
|
9
|
+
end
|
10
|
+
|
11
|
+
# Output "Hello world!"
|
12
|
+
#
|
13
|
+
# @api public
|
14
|
+
def log_message
|
15
|
+
puts @message
|
16
|
+
end
|
17
|
+
|
18
|
+
end
|
19
|
+
end
|
20
|
+
|
21
|
+
MyApplication::HelloWorld.new.log_message
|
data/lib/roxie/cli/doc.rb
CHANGED
data/lib/roxie/extractor.rb
CHANGED
@@ -16,15 +16,15 @@ module Roxie
|
|
16
16
|
|
17
17
|
def initialize(options = {})
|
18
18
|
@options = self.class.default_options.merge(options)
|
19
|
-
|
20
|
-
logger.warn "Roxie doesn't understand #{@options[:language]}"
|
21
|
-
end
|
19
|
+
@language = LANGUAGES[@options[:language]]
|
22
20
|
end
|
23
21
|
|
24
22
|
# Read up to 100KB
|
25
23
|
BYTE_LIMIT = 100_000
|
26
24
|
|
27
25
|
def extract(text)
|
26
|
+
return unless @language
|
27
|
+
|
28
28
|
@code = text.dup
|
29
29
|
@scanner = StringScanner.new(@code)
|
30
30
|
|
@@ -71,7 +71,7 @@ module Roxie
|
|
71
71
|
@scanner.scan_until(/(?=\S)/)
|
72
72
|
comment[:line] = @code[0..@scanner.pos].count("\n") + 1 unless @scanner.eos?
|
73
73
|
|
74
|
-
comments << comment unless @options[:only_tagged] &&
|
74
|
+
comments << comment unless @options[:only_tagged] && tags.empty?
|
75
75
|
else
|
76
76
|
# Skip line
|
77
77
|
@scanner.skip_until(/\n|\Z/)
|
data/lib/roxie/languages.yml
CHANGED
data/lib/roxie/version.rb
CHANGED
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: roxie
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.0.
|
4
|
+
version: 0.0.3
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Maxwell Barvian
|
@@ -59,6 +59,19 @@ files:
|
|
59
59
|
- features/generator.feature
|
60
60
|
- features/step_definitions/generator_steps.rb
|
61
61
|
- features/support/env.rb
|
62
|
+
- fixtures/doomed/utils.js
|
63
|
+
- fixtures/eol/main.js
|
64
|
+
- fixtures/ignores/ignore.js
|
65
|
+
- fixtures/ignores/ignore/util.js
|
66
|
+
- fixtures/ignores/included.js
|
67
|
+
- fixtures/incorrect-extensions/css/global.css
|
68
|
+
- fixtures/incorrect-extensions/js/utils.javascripty
|
69
|
+
- fixtures/mixed/index.coffee
|
70
|
+
- fixtures/multi-language/css/default.css
|
71
|
+
- fixtures/multi-language/css/functions.scss
|
72
|
+
- fixtures/multi-language/js/test.coffee
|
73
|
+
- fixtures/multi-language/js/utils.js
|
74
|
+
- fixtures/specific-base/codebase/hello_world.rb
|
62
75
|
- lib/roxie.rb
|
63
76
|
- lib/roxie/cli.rb
|
64
77
|
- lib/roxie/cli/doc.rb
|