docurium 0.4.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ef759fe2bcc48694d8393ed1812d996149cd6852
-  data.tar.gz: 12bbee6302d4f68c66af27c231a28cf0f9e306fc
+SHA256:
+  metadata.gz: 4ace5599ba2e3394f8edf0f6dbe0a388c163a11f3b55548c1048c386c8e18c54
+  data.tar.gz: e4bf9b423afd1a32079b8c5722ab64f7140da1d43072bc7d66418a9c8bfb9601
 SHA512:
-  metadata.gz: 077054ce5ca5c84bf529597a0e5345729fb329cef5e934bfc3deba2dcecdf8dfcdb24b2bf01d19d3ff21f85670a87cc6d0bdd1a1b5c02dacaa47dff9eb6ac289
-  data.tar.gz: 5b7e76e3f66ebaed25c234135bf3c16db099f5f892796dbf9190a3297049255126eac7123f990263524d5e9af69d8e9b1aa64614cb2bcd5b0bf69a303438d533
+  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,11 +1,11 @@
 source "http://rubygems.org"
 
-platforms :rbx do
-  gem 'rubysl', '~> 2.0'
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.0.0')
+  platforms :rbx do
+    gem 'rubysl', '~> 2.2'
+  end
 end
 
 gemspec
 
-gem 'ffi-clang', :git => 'https://github.com/ioquatix/ffi-clang.git'
-
 # vim:ft=ruby

data/README.md

@@ -57,21 +57,6 @@ Docurium will write your docs directly into the specified Git branch.
 
     $ gem install docurium
 
-# Screenshots
-
-## Main Page
-
-![Main Page](https://img.skitch.com/20110614-c98pp6c9p9mn35jn4iskjim7hk.png)
-
-Each version of your app has a landing page that lists out all the functions available.  Functions that are new in that version from the previous version are highlighted in green, functions that have changed signatures are in orange.
-
-## Function Page
-
-![Func Page](https://img.skitch.com/20110614-mdasyhip3swxtngwxrce8wqy3h.png)
-
-Each function has a page showing all the relevant info for that function including metadata extracted from Doxygen-style comments.  I also list all the versions of the library that this function is included in and in which versions the signature changed.
-
-
 # Contributing
 
 If you want to fix or change something, please fork on GitHub, push your change to a branch named after your change and send me a pull request.

data/bin/cm

@@ -13,12 +13,27 @@ version Docurium::Version
 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|
@@ -34,8 +49,10 @@ pre { |global,command,options,args| true }
 post { |global,command,options,args| true }
 
 on_error do |exception|
-  puts exception
-  puts exception.backtrace
+  if !exception.is_a?(SystemExit)
+    puts exception
+    puts exception.backtrace
+  end
 end
 
 exit run(ARGV)

data/docurium.gemspec

@@ -13,15 +13,16 @@ Gem::Specification.new do |s|
   s.description = s.summary
   s.license = 'MIT'
 
-  s.add_dependency "version_sorter", "~>1.1"
-  s.add_dependency "mustache", "~> 0.99"
+  s.add_dependency "version_sorter", "~>2.0"
+  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.2"
-  s.add_development_dependency "bundler",   "~>1.0"
-  s.add_development_dependency "rake", "~> 10.1"
+  s.add_dependency "ffi-clang", "~> 0.5"
+  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")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/docurium/cli.rb

@@ -2,10 +2,15 @@ class Docurium
   class CLI
 
     def self.doc(idir, options)
-      doc = Docurium.new(idir)
+      doc = Docurium.new(idir, options)
       doc.generate_docs
     end
 
+    def self.check(idir, options)
+      doc = Docurium.new(idir)
+      doc.check_warnings(options)
+    end
+
     def self.gen(file)
 
 temp = <<-TEMPLATE

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.exists? dirname
+        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, [], 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,14 +203,27 @@ class Docurium
 
     def extract_subject_desc(comment)
       subject = comment.child.text
-      desc = (comment.find_all { |cmt| cmt.kind == :comment_paragraph }).drop(1).map(&:text).join("\n\n")
+      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? }
@@ -181,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
       {
@@ -199,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|
@@ -274,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.4.1'
+  Version = VERSION = '0.7.0'
 end