rsg_doc 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c09f5aafe9ecd80c48b7e2486e1d5e7a0a26322a
+  data.tar.gz: ab508931966bda51b4ab86d6a0c4d4c0febdf740
+SHA512:
+  metadata.gz: 3da3339def91f42811c669a23b5142b08179f3e6288d66c6c9e6605f4ad40622d8971e81740c53c46e2ca3a9bd29670edfe24df1f8d4dc367d9b64857d1f6967
+  data.tar.gz: 9e62cdbda81736723f4e9dc44c6b15aa54b4c2eda3e87677b98a876b649dcfd989886c920874d7413a6ba0168400545f75032c1366b0ced466e44955841d155c

data/.gitignore

@@ -0,0 +1,2 @@
+*.gem
+.byebug_history

data/LICENSE.txt

@@ -0,0 +1,14 @@
+Copyright 2017 REDspace.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

data/README.md

@@ -0,0 +1,68 @@
+# Roku SceneGraph/BrightScript Documentation Generator
+
+[![Gem Version](https://badge.fury.io/rb/rsg_doc.svg)](https://badge.fury.io/rb/rsg_doc)
+
+A tool to generate documentation for Brightscript referenced in Scenegraph XML.
+
+## Installation
+
+    $ gem install rsg_doc
+
+## Usage
+
+From within the root directory for a project:
+
+    $ rsg
+
+### Result
+
+The generator targets Scenegraph xml files and parses Brightscript associated through the use of script tags.
+
+    <script type="text/brightscript" uri="pkg:/somebrightscript.brs"></script>'
+A docs folder is created containing same directory structure as the project with .brs.html and .xml.html files located where the source would be.
+
+For information on how the html files are generated check out the [Standard](#standard).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## Standard
+
+
+
+### Function Comment Structure
+
+Comments on functions need to be in two blocks separated by an empty commented line:
+ * **Description block**<br>
+ A section for an explanation of the sub/function. Multiple lines will be stitched together to form a single description.
+ <br><br>
+ * **Tag block**<br>
+ A section where tags can be used to effect how content is rendered.
+
+### Available Tags
+
+* **@deprecated** :_description_:<br>
+* **@param** :_attribute_name_: :_description_:
+* **@return** :_description_:
+* **@since** :_version_:
+
+Example:
+```BrightScript
+' Description block: any commented lines prior to an empty line
+' the is part of the description
+' this is also part of the description but the line below is not
+'
+' @deprecated Removed in 0.0.2 in favor of new function
+' @param params contains information useful to this function
+' @param anotherArg a string used for something
+' @return 0 if successful, error code if not
+' @since version 0.0.1
+function myFunction(params as Object, anotherArg as String) as Int
+...
+end function
+```

data/bin/rsg

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+#********** Copyright 2017 REDspace. All Rights Reserved. **********
+
+require "rsg_doc"
+require "byebug"
+
+Docgen.new(root_dir: Dir.pwd()).generate

data/lib/rsg_doc.rb

@@ -0,0 +1,11 @@
+#********** Copyright 2017 REDspace. All Rights Reserved. **********
+
+require 'fileutils'
+
+# require the document generator
+require 'rsg_doc/docgen.rb'
+
+module RSGDoc
+  # Version for the roku scenegraph document generator
+  VERSION = "0.0.2"
+end

data/lib/rsg_doc/docgen.rb

@@ -0,0 +1,243 @@
+#********** Copyright 2017 REDspace. All Rights Reserved. **********
+
+require 'erb'
+
+# Generate Brightscript documentation
+class Docgen
+
+  # Set the root directory
+  def initialize(root_dir: nil)
+    @ROOT_DIR = root_dir
+    @BRS_DOC_REF = "https://sdkdocs.roku.com/display/sdkdoc/"
+    FileUtils.cd(@ROOT_DIR)
+    FileUtils.mkdir_p 'docs', :mode => 0755
+    # Grab the document root
+    @doc_dir = File.join(@ROOT_DIR, "docs")
+  end
+
+  # Generate html files for xml files and brs included via script tags
+  def generate
+    Dir.glob(File.join(@ROOT_DIR, "**", "*.xml")).each do |file|
+      FileUtils.mkdir_p File.join(@doc_dir, File.dirname(file).split(@ROOT_DIR)[1]), :mode => 0755
+      parsexml(file)
+    end
+  end
+
+  # Look through the xml file and generate an html file with appropriate information
+  def parsexml(filename)
+    scripts = Array.new
+    # Initialize the hash containing xml.html information
+    xml_html_content = Hash.new
+    xml_html_content[:fields] = Array.new
+    xml_html_content[:brsfiles] = Array.new
+    xml_html_content[:functionalfields] = Array.new
+
+    # Iterate through lines in the file
+    File.open(filename).each do |line|
+      # Look for component name and optionally the extended class
+      temp_component = /<component name="(?<name>[^"]*)" (extends="(?<extendedClass>[^"]*)")?.*>/.match(line)
+      if (temp_component)
+        xml_html_content[:componentName] = temp_component['name']
+        xml_html_content[:componentExtendedClass] = temp_component['extendedClass']
+        next
+      end
+      # Look for referenced brightscript files
+      tempScript = /<script.*uri="pkg:(?<uri>[^"]*)".*>/.match(line)
+      if (tempScript)
+        scripts.push( tempScript )
+        next
+      end
+      # Look for fields on the inferface
+      tempField = /<field (id="(?<id>[^"]*)") (type="(?<type>[^"]*)").*>/.match(line)
+      if (tempField)
+          xml_html_content[:fields].push({
+            :id => tempField['id'],
+            :type => tempField['type']
+          })
+        next
+      end
+      # Look for functional fields on the interface
+      tempFuncField = /<function (name="(?<name>[^"]*)").*>/.match(line)
+      if (tempFuncField)
+        xml_html_content[:functionalfields].push({
+          :name => tempFuncField['name']
+        })
+      end
+    # End looping through file
+    end
+
+    # Define the variable for the portion of the path after the root and before pkg:
+    # Needs to be changes in order to account for relative paths
+    packageDoc = nil
+
+    # Parse the brightscript
+    scripts.each do |script|
+
+      packageDoc = File.dirname(filename.split(@ROOT_DIR)[1]).split(File.dirname(script['uri']))[0]
+      xml_html_content[:brsfiles].push({
+        :path => File.join(@doc_dir, packageDoc, File.path(script['uri'])),
+        :name => File.basename(script['uri'])
+      })
+
+      brs_doc_contents = parsebrs( script['uri'], packageDoc, filename )
+      # Pair up the functional field with the corresponding script
+      xml_html_content[:functionalfields].each do |function|
+        if brs_doc_contents[:content][:functions].empty?
+          puts "Warn: Uncommented functional field located in #{brs_doc_contents[:ref]}"
+        else
+          brs_doc_contents[:content][:functions].each do |brsfunction|
+            if brsfunction[:functionname] == function[:name]
+              function.merge!(:file => brs_doc_contents[:file])
+            end
+          end
+        end
+      end
+    end
+
+    # Using the .xml.html.erb
+    template = ERB.new(File.read(File.join(File.dirname(__FILE__), "docgenTemplates", "docgen.xml.html.erb")))
+    # Document the xml file
+    xml_file = File.open(
+      File.join(
+          @doc_dir,
+          File.dirname(filename).split(@ROOT_DIR)[1],
+          File.basename(filename)
+      ) << ".html","w",0755)
+    xml_file.write( template.result(binding) )
+    xml_file.close
+  end
+
+  # Controls the parsing for the commands
+  def parsebrs( script, package, parentxmlfile)
+
+    # FUTURE: Account for the path being relative, versus using package root
+    @ref_brs_script = File.join(@ROOT_DIR, package, script)
+
+    # html to be written to the documentation
+    brs_doc_content = Hash.new
+    brs_doc_content[:functions] = Array.new
+    brs_doc_content[:name] = File.basename(@ref_brs_script)
+
+    begin
+      lines = IO.readlines(@ref_brs_script)
+    rescue Errno::ENOENT
+      puts "Warn: BrightScript file not found: #{@ref_brs_script} Referenced from: #{parentxmlfile}"
+      return
+    else
+      # look through the saved lines for comments to parse
+      counter = 0;
+      until counter > lines.length
+        if  /^\s*(sub|function)/.match(lines[counter])
+          rev_counter = counter - 1
+          while rev_counter > 0
+            break unless  /\s*('|(?i:rem))/.match(lines[rev_counter])
+            rev_counter -= 1
+          end
+          brs_doc_content[:functions].push(
+            parseComments(lines.slice(rev_counter+1, counter-rev_counter))
+          ) if counter-rev_counter > 1
+        end
+        counter += 1
+      # End of loop per file
+      end
+
+        # Using the .xml.html.erb
+      template = ERB.new(File.read(File.join(File.dirname(__FILE__), "docgenTemplates", "docgen.brs.html.erb")))
+      # Document brightscript file
+      brs_doc_loc = File.join(
+            @doc_dir,
+            File.dirname(@ref_brs_script).split(@ROOT_DIR)[1],
+            File.basename(@ref_brs_script)
+      ) << ".html"
+      brs_file = File.open(brs_doc_loc, "w", 0755)
+      brs_file.write( template.result(binding) )
+      brs_file.close
+      return {:content => brs_doc_content, :file => brs_doc_loc, :ref => @ref_brs_script }
+    end
+  end
+
+  # Find all the comment components when generating the brightscript file
+  def parseComments(comments)
+    # Last line of the comments will be the function name
+    brs_html_content = Hash.new
+    brs_html_content[:description] = Array.new
+    line_num = 0;
+
+    # Parse description block
+    while line_num < comments.length - 1
+      if /('|(?i:rem))\s*$/.match(comments[line_num])
+        line_num += 1
+        break
+      end
+      full_comment = /('|(?i:rem))\s*(?<comment>\w.*$)/.match(comments[line_num])
+      if not full_comment
+        puts "fatal! Bad comment in file #{@ref_brs_script}"
+        abort
+      else
+        brs_html_content[:description].push( parseDescription(full_comment['comment'] ))
+      end
+      line_num += 1
+    end
+    brs_html_content[:params] = Array.new
+    # Parse the block tags if present
+    while line_num < comments.length - 1
+      # Look for deprecated tag
+      dep_match = /'\s*@deprecated\s*(?<description>.*$)/.match(comments[line_num])
+      if dep_match
+        brs_html_content[:deprecated] = parseDescription(dep_match['description'])
+        line_num += 1
+        next
+      end
+      # Look for param tag
+      param_match = /'\s*@param\s*(?<name>\w*)\s*(?<description>\w.*)?/.match(comments[line_num])
+      if param_match
+        brs_html_content[:params].push({
+          :name => param_match['name'],
+          :description => parseDescription(param_match['description'])
+        })
+        line_num += 1
+        next
+      end
+      # Look for since tags
+      since_match = /'\s*@since\s*(?<description>\w.*)/.match(comments[line_num])
+      if since_match
+        brs_html_content[:since] = parseDescription(since_match['description'])
+        line_num += 1
+        next
+      end
+      # Look for return tags
+      return_match = /'\s*@return\s*(?<description>\w.*$)/.match(comments[line_num])
+      if return_match
+        brs_html_content[:return] = parseDescription(return_match['description'])
+        line_num += 1
+        next
+      end
+      line_num += 1
+    end
+    # Get the function details (name for now)
+    function_info = /^\s*(sub|function)\s(?<name>[^(]*)\((?<inputs>[^)]*)\)\s*(?<returntype>\w.*)?/.match(comments[comments.length-1])
+    if function_info
+      brs_html_content[:functionname] = function_info['name']
+      brs_html_content[:functioninputs] = function_info['inputs']
+    end
+    return brs_html_content
+  end
+
+  # Handle the description and the inline tags
+  def parseDescription(des)
+    return des unless inline_match = /^'(.*)(?<inline>{[^}]*})(.*)/.match(des)
+
+    link_string = ""
+    tag_match = /@(?<tag>\w*)\s+(?<component>\w*)\s+(?<link_text>[^}]*)/.match(inline_match['inline'])
+    if tag_match
+      case tag_match['tag']
+      when "link"
+        link_string = "<a href=\"#{ File.join(@BRS_DOC_REF,tag_match['component']) }\">#{tag_match['link_text']}</a>"
+        return des.split(inline_match['inline']).join(link_string)
+      end
+      return des
+    end
+  end
+
+# End class
+end

data/lib/rsg_doc/docgenTemplates/docgen.brs.html.erb

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+  <head>
+
+  </head>
+  <body>
+    <h1> <%= brs_doc_content[:name] %> </h1>
+    <% if brs_doc_content[:functions].length > 0 %>
+    <h2> Functions: </h2>
+      <% brs_doc_content[:functions].each do |function| %>
+        <% if function[:deprecated] %>
+          <h3>Deprecated: <%= function[:deprecated] %></h3>
+        <% end %>
+        <h3> <%= function[:functionname] %> </h3>
+        <p> <%= function[:description].join(" ") %> </p>
+        <% if function[:params].length > 0 %>
+          <% function[:params].each do |param| %>
+            <h4> <%= param[:name] %> </h4>
+            <p>  <%= param[:description] %></p>
+          <% end %>
+        <% end %>
+        <% if function[:return] %>
+          <h3>Returns: </h3>
+          <p> <%= function[:return] %> </p>
+        <% end %>
+        <% if function[:since] %>
+          <h4>Added in <%= function[:since] %></h4>
+        <% end %>
+      <% end %>
+    <% end %>
+  </body>
+</html>

data/lib/rsg_doc/docgenTemplates/docgen.xml.html.erb

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html>
+  <head>
+
+  </head>
+  <body>
+    <h1><%= xml_html_content[:componentName] %></h1>
+    <h2>Extends: <%= xml_html_content[:componentExtendedClass] %></h2>
+
+    <% if xml_html_content[:brsfiles].length > 0 %>
+      <h2> Associated Brightscript: </h2>
+      <ul>
+        <% xml_html_content[:brsfiles].each do |brsfile| %>
+          <li><a href="<%= brsfile[:path] %>.html"><%= brsfile[:name] %></a></li>
+        <%end %>
+      </ul>
+    <% end %>
+
+    <% if xml_html_content[:fields].length > 0 %>
+      <h2> Fields: </h2>
+      <ul>
+        <% xml_html_content[:fields].each do |field| %>
+          <li><%= field[:id] %> : <%= field[:type] %></li>
+        <% end %>
+      </ul>
+    <% end %>
+
+    <% if xml_html_content[:functionalfields].length > 0 %>
+      <h2> Functional Fields: </h2>
+      <ul>
+        <% xml_html_content[:functionalfields].each do |functionalfield| %>
+          <li><a href="<%= functionalfield[:file] %>"></a><%= functionalfield[:name] %></li>
+        <% end %>
+      </ul>
+    <% end %>
+  </body>
+</html>

data/rsg_doc.gemspec

@@ -0,0 +1,23 @@
+#********** Copyright 2017 REDspace. All Rights Reserved. **********
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rsg_doc'
+
+Gem::Specification.new do |s|
+  s.name          = 'rsg_doc'
+  s.version       = RSGDoc::VERSION
+  s.summary       = "Generates documentation for Brightscript referenced in Scenegraph markup"
+  s.description   = ""
+  s.authors       = ["TyRud"]
+  s.email         = 'tyler.rudolph@redspace.com'
+  s.files         = `git ls-files -z`.split("\x0")
+  s.homepage      = "https://rubygems.org/gems/example"
+  s.license       = 'Apache-2.0'
+
+  s.bindir        = ["bin"]
+  s.executables   = ["rsg"]
+
+  s.required_ruby_version = "~> 2.3"
+
+  s.add_development_dependency "byebug", "~> 9.0"
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: rsg_doc
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- TyRud
+autorequire: 
+bindir:
+- bin
+cert_chain: []
+date: 2017-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: ''
+email: tyler.rudolph@redspace.com
+executables:
+- rsg
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE.txt
+- README.md
+- bin/rsg
+- lib/rsg_doc.rb
+- lib/rsg_doc/docgen.rb
+- lib/rsg_doc/docgenTemplates/docgen.brs.html.erb
+- lib/rsg_doc/docgenTemplates/docgen.xml.html.erb
+- rsg_doc.gemspec
+homepage: https://rubygems.org/gems/example
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Generates documentation for Brightscript referenced in Scenegraph markup
+test_files: []