XcodePages 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in XcodePages.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,86 @@
+= Xcode Pages
+
+The XcodePages gem helps you publish documentation from within Xcode using
+{Doxygen}[http://www.stack.nl/~dimitri/doxygen/].
+
+The term 'Pages' comes from the ultimate goal: to publish the HTML web pages on
+the Internet somewhere appropriate, e.g. on GitHub via the +gh-pages+ {branch
+feature}[http://pages.github.com/].
+
+The gem works for Objective-C projects built using Apple's {Xcode
+IDE}[http://developer.apple.com/xcode/]. It consequently focuses on
+documentation within Objective-C and Objective-C++ source files; files ending
+with extensions +h+, +m+ or +mm+.
+
+== How to Use Xcode Pages
+
+=== Step 1
+
+Add a new target to your Xcode project. Suppose your Xcode project has the name
++MyProject+. Add a new <em>External Build System</em> target called
++MyProjectPages+.
+
+=== Step 2
+
+Set the external build target up as follows.
+
+- Build Tool: <code>/bin/sh</code>
+- Arguments: <code>-c "$HOME/.rvm/bin/rvm-auto-ruby -r XcodePages -e XcodePages.doxygen_docset_install"</code>
+- Directory: None
+- Pass build setting in environment: Yes
+
+Leave Build Settings and Phases as defaults.
+
+Note that the arguments above tell the shell to run
+<code>$HOME/.rvm/bin/rvm-auto-ruby</code>. This assumes you are running
+{RVM}[http://beginrescueend.com/].
+
+Also, do not try to promote your Ruby path to the Build Tool setting unless you
+have a fixed path to Ruby, e.g. +/usr/bin/ruby+. Xcode does *not* make
+environment variables substitutions within the Build Tool setting.
+
+=== Step 3
+
+Set up a new +Doxyfile+ in your project's source root containing four Doxygen settings:
+
+* <code>DOCSET_FEEDNAME        = "My Project Documentation Set"</code>
+* <code>DOCSET_BUNDLE_ID       = com.domain.MyProjectDocSet</code>
+* <code>DOCSET_PUBLISHER_ID    = com.domain.MyProjectDocSet.documentation</code>
+* <code>DOCSET_PUBLISHER_NAME  = My Publisher Name</code>
+
++DOCSET_BUNDLE_ID+ is the most significant item for this determines the base
+name for the documentation set. Doxygen just adds extension +docset+ to make the
+file name.
+
+=== Step 4
+
+You can now switch target to +MyProjectPages+ and hit Build (Cmd+B) to compile
+the documentation. It will appear in folder +MyProjectPages+ within the source
+root folder and a new Xcode +docset+ will appear in
++~/Library/Developer/Shared/Documentation/DocSets+.
+
+You would normally have to reload Xcode to see the new documentation. As a
+courtesy, the last step tells the running Xcode application to pick up the new
+set.
+
+== Benefits
+
+* Takes the "fiddle" out of fiddling with Doxygen.
+* You can easily identify undocumented classes and methods.
+
+  Warning messages output by Doxygen make this possible. After building your
+  project Pages target, the build results contain warning about undocumented
+  elements within your project. Press the Cmd+\' (Jump to Next Issue command) to
+  navigate through the undocumented code.
+
+== Examples
+
+You can find examples of projects using XcodePages here:
+
+* {Active Support Kit}[https://github.com/royratcliffe/ActiveSupportKit]
+
+== Prerequisites
+
+* Xcode and associated Apple developer tools
+* Ruby and RubyGems package manager
+* Doxygen

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/XcodePages.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "XcodePages/version"
+
+Gem::Specification.new do |s|
+  s.name        = "XcodePages"
+  s.version     = XcodePages::VERSION
+  s.authors     = ["Roy Ratcliffe"]
+  s.email       = ["roy@pioneeringsoftware.co.uk"]
+  s.homepage    = ""
+  s.summary     = %q{Helps you publish documentation from within Xcode using Doxygen}
+  s.description = %q{
+    Helps you publish HTML web pages on the Internet somewhere appropriate, e.g.
+    on GitHub via the gh-pages branch feature.
+
+    Works for Objective-C projects built using Apple's Xcode IDE and
+    consequently focuses on documentation within Objective-C and Objective-C++
+    source files; files ending with extensions h, m or mm.}
+
+  s.rubyforge_project = "XcodePages"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rake"
+  s.add_runtime_dependency "activesupport"
+end

data/lib/XcodePages/version.rb

@@ -0,0 +1,3 @@
+module XcodePages
+  VERSION = "0.0.1"
+end

data/lib/XcodePages.rb

@@ -0,0 +1,145 @@
+# encoding: utf-8
+
+require "XcodePages/version"
+require 'active_support/core_ext/string'
+require 'tempfile'
+
+module XcodePages
+  # Prints the environment. Xcode passes many useful pieces of information via
+  # the Unix environment.
+  #
+  # This can be useful for testing. Add an external build target to Xcode. Make
+  # the Build Tool equal to /bin/sh and make the arguments equal to:
+  #
+  #   -c "$HOME/.rvm/bin/rvm-auto-ruby -r XcodePages -e XcodePages.print_env"
+  #
+  # and you will see all the Unix environment variables. This assumes that you
+  # are using RVM in your local account to manage Ruby.
+  def self.print_env
+    ENV.each { |key, value| puts "#{key}=#{value}" }
+  end
+
+  # Searches for all the available source files (files with h, m or mm
+  # extension) in the current working directory or below. Pulls out their
+  # directory names and answers an array of unique space-delimited relative
+  # folder paths. These directory names will become Doxygen input folders.
+  #
+  # The implementation assumes that the current working directory equals the
+  # Xcode source root. It also makes some simplifying assumptions about spaces
+  # in the paths: that there are *no* spaces. Doxygen uses spaces to delimit the
+  # files and directories listed for input. But what if the paths themselves
+  # contain spaces?
+  #
+  # Note that this method works correctly when the source root itself contains
+  # headers or sources. In this case, the answer will contain the "." directory.
+  def self.input
+    Dir.glob('**/*.{h,m,mm}').map { |relative_path| File.dirname(relative_path) }.uniq.join(' ')
+  end
+
+  # Answers the project "marketing version" using Apple's +agvtool+. The
+  # marketing version is the "bundle short version string" appearing in the
+  # bundle's +Info.plist+. Cocoa only uses this for display in the standard
+  # About panel.
+  def self.marketing_version
+    %x(agvtool mvers -terse1).chomp
+  end
+
+  # Answers the project build version using Apple's +agvtool+. This is the real
+  # version number, equating to +CURRENT_PROJECT_VERSION+.
+  def self.build_version
+    %x(agvtool vers -terse).chomp
+  end
+
+  # Answers what Doxygen calls the ‘project number.’ This is the revision
+  # number appearing beside the project name in the documentation title. Uses
+  # the marketing and build version numbers in the format +vMV (BV)+ where +MV+
+  # stands for marketing version and +BV+ stands for build version. Omits the
+  # build version if the project matches marketing and build version. No sense
+  # repeating the same number if they are the same.
+  def self.project_number
+    project_number = "v#{marketing_version}"
+    project_number << "&nbsp;(#{build_version})" if build_version != marketing_version
+  end
+
+  # Answers the path of the output directory. Doxygen outputs to this folder.
+  # HTML web pages appear in the +html+ sub-folder.
+  def self.output_directory
+    "#{ENV['PROJECT_NAME']}Pages"
+  end
+
+  # Answers the path to the +html+ output sub-folder where Doxygen writes the
+  # HTML web pages and the DocSet +Makefile+ when +GENERATE_DOCSET+ equals
+  # +YES+.
+  def self.html_output_directory
+    File.join(output_directory, 'html')
+  end
+
+  # Launches Doxygen.
+  #
+  # The implementation derives the Doxygen project name from the environment
+  # PROJECT_NAME variable. Xcode passes this variable. Typically, it is a
+  # camel-cased name. Using ActiveSupport (part of the Rails framework) the
+  # implementation below derives a humanised title; effectively puts spaces
+  # in-between the camels!
+  def self.doxygen
+    IO.popen('doxygen -', 'r+') do |doxygen|
+      doxygen.puts <<-EOF
+        PROJECT_NAME           = #{ENV['PROJECT_NAME'].titleize}
+        PROJECT_NUMBER         = #{project_number}
+        OUTPUT_DIRECTORY       = #{output_directory}
+        TAB_SIZE               = 4
+        EXTENSION_MAPPING      = h=Objective-C
+        INPUT                  = #{input}
+        SOURCE_BROWSER         = YES
+        HTML_TIMESTAMP         = NO
+        GENERATE_LATEX         = NO
+        HAVE_DOT               = YES
+      EOF
+
+      # Let the user override the previous defaults by loading up the Doxyfile
+      # if one exists. This should appear in the source root folder.
+      if File.exists?('Doxyfile')
+        doxygen.write File.read('Doxyfile')
+      end
+
+      # Close the write-end of the pipe.
+      doxygen.close_write
+
+      # Read the read-end of the pipe and send the lines to standard output.
+      puts doxygen.readlines
+    end
+  end
+
+  # Launches Doxygen and builds the Apple DocSet. It does not install the
+  # DocSet. The compiled documentation set remains in the +html+ sub-folder.
+  def self.doxygen_docset
+    doxygen
+    # Assume that doxygen succeeds. But what happens when it does not?
+    %x(cd #{html_output_directory} ; make)
+  end
+
+  # Runs Doxygen and installs the Apple DocSet in the current user's shared
+  # documentation folder. Finally, as a courtesy, it tells Xcode about the
+  # change; signalling an update in your running Xcode IDE. Documentation
+  # updates immediately.
+  def self.doxygen_docset_install
+    doxygen
+    %x(cd #{html_output_directory} ; make install)
+
+    script = Tempfile.open(['XcodePages', '.scpt']) do |script|
+      script.puts <<-EOF
+        tell application "Xcode"
+      EOF
+      Dir.glob(File.join(html_output_directory, '*.docset')).each do |docset_path|
+        script.puts <<-EOF
+        	load documentation set with path "#{ENV['HOME']}/Library/Developer/Shared/Documentation/DocSets/#{File.basename(docset_path)}"
+        EOF
+      end
+      script.puts <<-EOF
+        end tell
+      EOF
+      script.close
+      %x(osascript #{script.path})
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: XcodePages
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Roy Ratcliffe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70122300103820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70122300103820
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70122300091600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70122300091600
+description: ! "\n    Helps you publish HTML web pages on the Internet somewhere appropriate,
+  e.g.\n    on GitHub via the gh-pages branch feature.\n\n    Works for Objective-C
+  projects built using Apple's Xcode IDE and\n    consequently focuses on documentation
+  within Objective-C and Objective-C++\n    source files; files ending with extensions
+  h, m or mm."
+email:
+- roy@pioneeringsoftware.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- XcodePages.gemspec
+- lib/XcodePages.rb
+- lib/XcodePages/version.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: XcodePages
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Helps you publish documentation from within Xcode using Doxygen
+test_files: []
+has_rdoc: