docurium 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 254c929d02d15703e7a653b44957e8a6e57dfadb3a0d2b62a419e31f44e8cda1
-  data.tar.gz: 9dc4b04e2e9b705448e3ff50bb4480fb5fd5466472dcf24a6b2823fdcaf9219d
+  metadata.gz: 4ace5599ba2e3394f8edf0f6dbe0a388c163a11f3b55548c1048c386c8e18c54
+  data.tar.gz: e4bf9b423afd1a32079b8c5722ab64f7140da1d43072bc7d66418a9c8bfb9601
 SHA512:
-  metadata.gz: 60e0579913e6f55fc4d34b5c0858cdaca36948425419a5023f080c4903ad1ad22ae62b53c338beee74247654d21400527c3d95cc96a7b4d5ca6b9e5a7110007b
-  data.tar.gz: cb64247b31745da479be5599fcf04f8b02a6337ea4e4867acee517b424a9492b1f9cec04b7cf594fa1161008fcf4f7db31c7a9527992f94fdbfb88aa2582d519
+  metadata.gz: a0d4bf587364d3436d28dbab2f4bc5785c52510dcae70bae4f05ca89181786286e5b3072be86984ad5c216f64dccbbd76e02c35db8cb5022bef53907eba041f8
+  data.tar.gz: 0b7c46c6776e92c9dd233c8fe7b48fd9791dad0e26c105169fc3b8c8ff79ba57e9f72c152b8e6a53c0f8fcbdea8c9d2cc9eedb63b4eae91d70d76d7bbd958e74

data/.github/workflows/main.yml

@@ -0,0 +1,42 @@
+name: Docurium
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [head, 3.0, 2.7, 2.6]
+        llvm: ["6.0", 7, 8, 9, 10]
+        os: [ ubuntu-18.04 ]
+        include:
+          - os: macos-latest
+            ruby: 2.6
+            llvm: ~ # system
+
+    name: Ruby ${{ matrix.ruby }} / LLVM ${{ matrix.llvm }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install Linux packages
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt update
+          sudo apt install -y python-pygments libclang-${{ matrix.llvm }}-dev llvm-${{ matrix.llvm }} clang-${{ matrix.llvm }}
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: |
+          [ -x /usr/bin/llvm-config-${{ matrix.llvm }} ] && export LLVM_CONFIG=llvm-config-${{ matrix.llvm }}
+          bundle exec rake

data/Gemfile

@@ -1,7 +1,9 @@
 source "http://rubygems.org"
 
-platforms :rbx do
-  gem 'rubysl', '~> 2.2'
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.0.0')
+  platforms :rbx do
+    gem 'rubysl', '~> 2.2'
+  end
 end
 
 gemspec

data/bin/cm

@@ -14,12 +14,26 @@ desc 'Generate HTML documentation'
 long_desc 'Generate HTML docs from a Docurium config file'
 command :doc do |c|
   c.flag :for, :desc => "The version to generate", :multiple => true
+  c.switch [:n, "dry-run"], :desc => "Dry-run"
+  c.switch [:d, "debug"], :desc => "Enable debug log"
+  c.flag "debug-file", :desc => "Enable debug output for header", :multiple => true
+  c.flag "debug-function", :desc => "Show debug output when processing function", :multiple => true
+  c.flag "debug-type", :desc => "Show debug output when processing type", :multiple => true
   c.action do |global_options,options,args|
     file = args.first
     Docurium::CLI.doc(file, options)
   end
 end
 
+desc 'Check documentation for warnings'
+long_desc 'Check a project\'s documentation for issues'
+command :check do |c|
+  c.action do |global_options,options,args|
+    file = args.first
+    Docurium::CLI.check(file, options)
+  end
+end
+
 desc 'Generate Docurium config file template'
 long_desc 'Generate Docurium config file template'
 command :gen do |c|

data/docurium.gemspec

@@ -17,10 +17,11 @@ Gem::Specification.new do |s|
   s.add_dependency "mustache", "~> 1.1"
   s.add_dependency "rocco", "~>0.8"
   s.add_dependency "gli", "~>2.5"
-  s.add_dependency "rugged", "~>0.21"
+  s.add_dependency "rugged", "~>1.1"
   s.add_dependency "redcarpet", "~>3.0"
   s.add_dependency "ffi-clang", "~> 0.5"
-  s.add_development_dependency "rake", "~> 12"
+  s.add_dependency "parallel", "~> 1.20"
+  s.add_development_dependency "rake", "~> 13"
   s.add_development_dependency "minitest", "~> 5.11"
 
   s.files         = `git ls-files`.split("\n")

data/lib/docurium/cli.rb

@@ -2,8 +2,13 @@ class Docurium
   class CLI
 
     def self.doc(idir, options)
+      doc = Docurium.new(idir, options)
+      doc.generate_docs
+    end
+
+    def self.check(idir, options)
       doc = Docurium.new(idir)
-      doc.generate_docs(options)
+      doc.check_warnings(options)
     end
 
     def self.gen(file)

data/lib/docurium/debug.rb

@@ -0,0 +1,41 @@
+$debug_stack = [false]
+
+def debug_enabled
+  $debug_stack[-1]
+end
+
+def debug(str = nil)
+  puts str if debug_enabled
+end
+
+def debug_enable
+  $debug_stack.push true
+end
+
+def debug_silence
+  $debug_stack.push false
+end
+
+def debug_set val
+  $debug_stack.push val
+end
+
+def debug_pass
+  $debug_stack.push debug_enabled
+end
+
+def debug_restore
+  $debug_stack.pop
+end
+
+def with_debug(&block)
+  debug_enable
+  block.call
+  debug_restore
+end
+
+def without_debug(&block)
+  debug_silence
+  block.call
+  debug_restore
+end

data/lib/docurium/docparser.rb

@@ -1,46 +1,87 @@
 require 'tempfile'
 require 'fileutils'
 require 'ffi/clang'
+require 'open3'
 include FFI::Clang
 
 class Docurium
   class DocParser
-    # Entry point for this parser
-    # Parse `filename` out of the hash `files`
-    def parse_file(orig_filename, files)
+    # The include directory where clang has its basic type definitions is not
+    # included in our default search path, so as a workaround we execute clang
+    # in verbose mode and grab its include paths from the output.
+    def find_clang_includes
+      @includes ||=
+        begin
+          clang = if ENV["LLVM_CONFIG"]
+            bindir = `#{ENV["LLVM_CONFIG"]} --bindir`.strip
+            "#{bindir}/clang"
+          else
+            "clang"
+          end
+
+          output, _status = Open3.capture2e("#{clang} -v -x c -", :stdin_data => "")
+          includes = []
+          output.each_line do |line|
+            if line =~ %r{^\s+/(.*usr|.*lib/clang.*)/include}
+              includes << line.strip
+            end
+          end
+
+          includes
+        end
+    end
 
+    def self.with_files(files, opts = {})
+      parser = self.new(files, opts)
+      yield parser
+      parser.cleanup!
+    end
+
+    def initialize(files, opts = {})
       # unfortunately Clang wants unsaved files to exist on disk, so
       # we need to create at least empty files for each unsaved file
       # we're given.
 
-      tmpdir = Dir.mktmpdir()
-
-      unsaved = files.map do |name, contents|
-        full_path = File.join(tmpdir, name)
+      prefix = (opts[:prefix] ? opts[:prefix] + "-" : nil)
+      @tmpdir = Dir.mktmpdir(prefix)
+      @unsaved = files.map do |name, contents|
+        full_path = File.join(@tmpdir, name)
         dirname = File.dirname(full_path)
         FileUtils.mkdir_p(dirname) unless Dir.exist? dirname
         File.new(full_path, File::CREAT).close()
-
         UnsavedFile.new(full_path, contents)
       end
+    end
 
-      # Override the path we want to filter by
-      filename = File.join(tmpdir, orig_filename)
-      tu = Index.new.parse_translation_unit(filename, ["-DDOCURIUM=1"], unsaved, {:detailed_preprocessing_record => 1})
+    def cleanup!
+      FileUtils.remove_entry(@tmpdir)
+    end
 
-      FileUtils.remove_entry(tmpdir)
+    # Entry point for this parser
+    # Parse `filename` out of the hash `files`
+    def parse_file(orig_filename, opts = {})
 
-      cursor = tu.cursor
+      includes = find_clang_includes + [@tmpdir]
+
+      # Override the path we want to filter by
+      filename = File.join(@tmpdir, orig_filename)
+      debug_enable if opts[:debug]
+      debug "parsing #{filename} #{@tmpdir}"
+      args = includes.map { |path| "-I#{path}" }
+      args << '-ferror-limit=1'
+
+      tu = Index.new(true, true).parse_translation_unit(filename, args, @unsaved, {:detailed_preprocessing_record => 1})
 
       recs = []
 
-      cursor.visit_children do |cursor, parent|
-        #puts "visiting #{cursor.kind} - #{cursor.spelling}"
+      tu.cursor.visit_children do |cursor, parent|
         location = cursor.location
         next :continue if location.file == nil
         next :continue unless location.file == filename
 
-        #puts "for file #{location.file} #{cursor.kind} #{cursor.spelling} #{cursor.comment.kind} #{location.line}"
+        loc = "%d:%d-%d:%d" % [cursor.extent.start.line, cursor.extent.start.column, cursor.extent.end.line, cursor.extent.end.column]
+        debug "#{cursor.location.file}:#{loc} - visiting #{cursor.kind}: #{cursor.spelling}, comment is #{cursor.comment.kind}"
+
         #cursor.visit_children do |c|
         #  puts "  child #{c.kind}, #{c.spelling}, #{c.comment.kind}"
         #  :continue
@@ -57,25 +98,38 @@ class Docurium
           :tdef => nil,
         }
 
-        case cursor.kind
+        extract = case cursor.kind
         when :cursor_function
-          #puts "have function"
-          rec.merge! extract_function(cursor)
+          debug "have function #{cursor.spelling}"
+          rec.update extract_function(cursor)
         when :cursor_enum_decl
-          rec.merge! extract_enum(cursor)
+          debug "have enum #{cursor.spelling}"
+          rec.update extract_enum(cursor)
         when :cursor_struct
-          #puts "raw struct"
-          rec.merge! extract_struct(cursor)
+          debug "have struct #{cursor.spelling}"
+          rec.update extract_struct(cursor)
         when :cursor_typedef_decl
-          rec.merge! extract_typedef(cursor)
+          debug "have typedef #{cursor.spelling} #{cursor.underlying_type.spelling}"
+          rec.update extract_typedef(cursor)
         else
           raise "No idea how to deal with #{cursor.kind}"
         end
 
+        rec.merge! extract
+
         recs << rec
         :continue
       end
 
+      if debug_enabled
+        puts "parse_file: parsed #{recs.size} records for #{filename}:"
+        recs.each do |r|
+          puts "\t#{r}"
+        end
+      end
+
+      debug_restore
+
       recs
     end
 
@@ -149,15 +203,27 @@ class Docurium
 
     def extract_subject_desc(comment)
       subject = comment.child.text
-      paras = comment.find_all { |cmt| cmt.kind == :comment_paragraph }.drop(1).map { |p| p.map(&:text).join() }
+      debug "\t\tsubject: #{subject}"
+      paras = comment.find_all { |cmt| cmt.kind == :comment_paragraph }.drop(1).map { |p| p.text }
       desc = paras.join("\n\n")
+      debug "\t\tdesc: #{desc}"
       return subject, desc
     end
 
     def extract_function(cursor)
       comment = cursor.comment
 
-      #puts "looking at function #{cursor.spelling}, #{cursor.display_name}"
+      $buggy_functions = %w()
+      debug_set ($buggy_functions.include? cursor.spelling)
+      if debug_enabled
+        puts "\tlooking at function #{cursor.spelling}, #{cursor.display_name}"
+        puts "\tcomment: #{comment}, #{comment.kind}"
+        cursor.visit_children do |cur, parent|
+          puts "\t\tchild: #{cur.spelling}, #{cur.kind}"
+          :continue
+        end
+      end
+
       cmt = extract_function_comment(comment)
       args = extract_function_args(cursor, cmt)
       #args = args.reject { |arg| arg[:comment].nil? }
@@ -182,6 +248,7 @@ class Docurium
       decl = "#{ret[:type]} #{cursor.spelling}(#{argline})"
       body = "#{decl};"
 
+      debug_restore
       #puts cursor.display_name
       # Return the format that docurium expects
       {
@@ -200,6 +267,7 @@ class Docurium
 
     def extract_function_comment(comment)
       subject, desc = extract_subject_desc(comment)
+      debug "\t\textract_function_comment: #{comment}, #{comment.kind}, #{subject}, #{desc}"
 
       args = {}
       (comment.find_all { |cmt| cmt.kind == :comment_param_command }).each do |param|
@@ -275,7 +343,7 @@ class Docurium
         :continue
       end
 
-      #puts "struct value #{values}"
+      debug "\tstruct value #{values}"
 
       rec = {
         :type => :struct,

data/lib/docurium/layout.rb

@@ -1,7 +1,4 @@
 # adding some stuff I need
 class Rocco::Layout
   attr_accessor :version
-  def version
-    @version
-  end
 end

data/lib/docurium/version.rb

@@ -1,3 +1,3 @@
 class Docurium
-  Version = VERSION = '0.6.0'
+  Version = VERSION = '0.7.0'
 end