Permalink
Browse files

Implemented Rake tasks for generating documentation via Appledoc very…

… simply. refs #48

* Implemented `rake docs:install` for generating and installing a docset
* Implemented `rake docs:upload` for posting generated documentation to restkit.org
* Introduced new VERSION file for coordinating the version of the library. To be used in forthcoming release automation.
* Added notes about API documentation to the README
  • Loading branch information...
blakewatters committed Apr 14, 2011
1 parent 695c262 commit 462cf35be456269b500d9221ce96700e6283d4a6
View
@@ -2,6 +2,7 @@
Build
build
DerivedData
+Docs/API
# temp nibs and swap files
*~.nib
View
@@ -48,6 +48,12 @@ Documentation & Example Code
Documentation and example code is being added as quickly as possible. Please check the Docs/ and Examples/ subdirectories to see what's available. The [RestKit Google Group](http://groups.google.com/group/restkit) is an invaluable resource for getting help working with the library.
+RestKit has API documentation available on the web. You can access the documentation in several ways:
+
+1. Online in your web browser. Visit http://restkit.org/api/
+1. Directly within Xcode. Visit your Xcode Preferences and view the Documentation tab. Click + and add the RestKit feed: http://restkit.org/api/org.restkit.RestKit.atom
+1. Generate the documentation directly from the project source code. Run `rake docs` to generate and `rake docs:install` to install into Xcode
+
Installation
=========================
View
106 Rakefile
@@ -38,21 +38,109 @@ namespace :uispec do
end
end
+def restkit_version
+ @restkit_version ||= ENV['VERSION'] || File.read("VERSION").chomp
+end
+
+def apple_doc_command
+ "Vendor/appledoc/appledoc -t Vendor/appledoc/Templates -o Docs/API -p RestKit -v #{restkit_version} -c \"Two Toasters\" " +
+ "--company-id org.restkit --warn-undocumented-object --warn-undocumented-member --warn-empty-description --warn-unknown-directive " +
+ "--warn-invalid-crossref --warn-missing-arg --no-repeat-first-par "
+end
+
+def run(command)
+ puts "Executing: `#{command}`"
+ system(command)
+end
+
desc "Run all specs"
task :default => 'uispec:all'
desc "Build RestKit for iOS and Mac OS X"
task :build do
- system("xcodebuild -workspace RestKit.xcodeproj/project.xcworkspace -scheme RestKit -sdk iphoneos4.3")
- system("xcodebuild -workspace RestKit.xcodeproj/project.xcworkspace -scheme RestKit -sdk macosx10.6")
+ run("xcodebuild -workspace RestKit.xcodeproj/project.xcworkspace -scheme RestKit -sdk iphoneos4.3 clean build")
+ run("xcodebuild -workspace RestKit.xcodeproj/project.xcworkspace -scheme RestKit -sdk macosx10.6 clean build")
end
desc "Generate documentation via appledoc"
-task :docs do
- # TODO: Read the version
- # TODO: Build doc-set
- # TODO: Customize the
- system("Vendor/appledoc/appledoc -o Docs/API -p RestKit -v 0.9 -h --no-create-docset -c \"Two Toasters\" -h " +
- "--warn-undocumented-object --warn-undocumented-member --warn-empty-description --warn-unknown-directive " +
- "--warn-invalid-crossref --warn-missing-arg Code/")
+task :docs => 'docs:generate'
+
+namespace :docs do
+ task :generate do
+ command = apple_doc_command << " --no-create-docset --keep-intermediate-files --create-html Code/"
+ run(command)
+ puts "Generated HTML documentationa at Docs/API/html"
+ end
+
+ desc "Check that documentation can be built from the source code via appledoc successfully."
+ task :check do
+ command = apple_doc_command << " --no-create-html Code/"
+ run(command)
+ if $? != 0
+ puts "Documentation failed to generate with exit code #{$?}"
+ exit($?)
+ else
+ puts "Documentation processing with appledoc was successful."
+ end
+ end
+
+ desc "Generate & install a docset into Xcode from the current sources"
+ task :install do
+ command = apple_doc_command << " --install-docset Code/"
+ run(command)
+ end
+
+ desc "Build and upload the documentation set to the remote server"
+ task :upload do
+ version = ENV['VERSION'] || File.read("VERSION").chomp
+ puts "Generating RestKit docset for version #{version}..."
+ command = apple_doc_command <<
+ " --keep-intermediate-files" <<
+ " --docset-feed-name \"RestKit #{version} Documentation\"" <<
+ " --docset-feed-url http://restkit.org/api/%DOCSETATOMFILENAME" <<
+ " --docset-package-url http://restkit.org/api/%DOCSETPACKAGEFILENAME --publish-docset Code/"
+ run(command)
+ if $? == 0
+ puts "Uploading docset to restkit.org..."
+ command = "rsync -rvpPe ssh --delete Docs/API/html/ restkit.org:/var/www/public/restkit.org/public/api/#{version}"
+ run(command)
+
+ if $? == 0
+ command = "rsync -rvpPe ssh Docs/API/publish/ restkit.org:/var/www/public/restkit.org/public/api/"
+ run(command)
+ end
+ end
+ end
+end
+
+def is_port_open?(ip, port)
+ require 'socket'
+ require 'timeout'
+
+ begin
+ Timeout::timeout(1) do
+ begin
+ s = TCPSocket.new(ip, port)
+ s.close
+ return true
+ rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+ return false
+ end
+ end
+ rescue Timeout::Error
+ end
+
+ return false
+end
+
+task :ensure_server_is_running do
+ unless is_port_open?('127.0.0.1', 4567)
+ puts "Unable to find RestKit Specs server listening on port 4567. Run `rake uispec:server` and try again."
+ exit(-1)
+ end
+end
+
+desc "Validate a branch is ready for merging by checking for common issues"
+task :validate => [:build, 'docs:check', :ensure_server_is_running, 'uispec:all'] do
+ puts "All tests passed OK. Proceed with merge."
end
View
@@ -0,0 +1 @@
+0.9
@@ -0,0 +1 @@
+This is used only as placeholder for location of Documents directory!
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<DocSetNodes version="1.0">
+ <TOC>
+ <Node type="folder">
+ <Name>{{projectName}}</Name>
+ <Path>{{indexFilename}}</Path>
+ <Subnodes>
+ {{#hasClasses}}
+ <Node type="folder">
+ <Name>{{strings/docset/classesTitle}}</Name>
+ <Path>{{indexFilename}}</Path>
+ <Subnodes>
+ {{#classes}}{{>NodeRef}}
+ {{/classes}}
+ </Subnodes>
+ </Node>
+ {{/hasClasses}}
+ {{#hasCategories}}
+ <Node type="folder">
+ <Name>{{strings/docset/categoriesTitle}}</Name>
+ <Path>{{indexFilename}}</Path>
+ <Subnodes>
+ {{#categories}}{{>NodeRef}}
+ {{/categories}}
+ </Subnodes>
+ </Node>
+ {{/hasCategories}}
+ {{#hasProtocols}}
+ <Node type="folder">
+ <Name>{{strings/docset/protocolsTitle}}</Name>
+ <Path>{{indexFilename}}</Path>
+ <Subnodes>
+ {{#protocols}}{{>NodeRef}}
+ {{/protocols}}
+ </Subnodes>
+ </Node>
+ {{/hasProtocols}}
+ </Subnodes>
+ </Node>
+ </TOC>
+ <Library>
+ {{#classes}}{{>Node}}
+ {{/classes}}
+ {{#categories}}{{>Node}}
+ {{/categories}}
+ {{#protocols}}{{>Node}}
+ {{/protocols}}
+ </Library>
+</DocSetNodes>
+
+Section Node
+ <Node id="{{id}}"{{#type}} type="{{type}}"{{/type}}>
+ <Name>{{name}}</Name>
+ <Path>{{path}}</Path>
+ </Node>
+EndSection
+
+Section NodeRef
+ <NodeRef refid="{{id}}"/>
+EndSection
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Tokens version="1.0">
+ <File path="{{filePath}}">
+ {{#object}}
+ <Token>
+ {{>TokenIdentifier}}
+ {{>Abstract}}
+ {{>DeclaredIn}}
+ {{>RelatedTokens}}
+ {{#refid}}<NodeRef refid="{{refid}}"/>{{/refid}}
+ </Token>
+ {{/object}}
+ {{#members}}
+ <Token>
+ {{>TokenIdentifier}}
+ {{>Abstract}}
+ {{>DeclaredIn}}
+ {{>RelatedTokens}}
+ <Declaration>{{>MethodDeclaration}}</Declaration>
+ {{#hasParameters}}<Parameters>
+ {{#parameters}}<Parameter>
+ <Name>{{name}}</Name>
+ {{>Abstract}}
+ </Parameter>{{/parameters}}
+ </Parameters>{{/hasParameters}}
+ {{#returnValue}}<ReturnValue>{{>Abstract}}</ReturnValue>{{/returnValue}}
+ {{#anchor}}<Anchor>{{anchor}}</Anchor>{{/anchor}}
+ </Token>
+ {{/members}}
+ </File>
+</Tokens>
+
+Section TokenIdentifier
+ <TokenIdentifier>{{identifier}}</TokenIdentifier>
+EndSection
+
+Section DeclaredIn
+ <DeclaredIn>{{declaredin}}</DeclaredIn>
+EndSection
+
+Section RelatedTokens
+ {{#hasRelatedTokens}}
+ <RelatedTokens>
+ {{#relatedTokens}}<TokenIdentifier>{{.}}</TokenIdentifier>
+ {{/relatedTokens}}
+ </RelatedTokens>
+ {{/hasRelatedTokens}}
+EndSection
+
+Section Abstract
+<Abstract>{{#abstract}}{{>GBCommentComponentsList}}{{/abstract}}</Abstract>
+EndSection
+
+Section MethodDeclaration
+{{#formattedComponents}}{{value}}{{/formattedComponents}}
+EndSection
+
+Section GBCommentComponentsList
+{{#components}}{{&textValue}}{{/components}}
+EndSection
+
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDevelopmentRegion</key>
+ <string>en</string>
+ {{#bundleIdentifier}}<key>CFBundleIdentifier</key>
+ <string>{{bundleIdentifier}}</string>{{/bundleIdentifier}}
+ {{#bundleName}}<key>CFBundleName</key>
+ <string>{{bundleName}}</string>{{/bundleName}}
+ {{#bundleVersion}}<key>CFBundleShortVersionString</key>
+ <string>{{bundleVersion}}</string>
+ <key>CFBundleVersion</key>
+ <string>{{bundleVersion}}</string>{{/bundleVersion}}
+ {{#certificateIssuer}}<key>DocSetCertificateIssuer</key>
+ <string>{{certificateIssuer}}</string>{{/certificateIssuer}}
+ {{#certificateSigner}}<key>DocSetCertificateSigner</key>
+ <string>{{certificateSigner}}</string>{{/certificateSigner}}
+ {{#description}}<key>DocSetDescription</key>
+ <string>{{description}}</string>{{/description}}
+ {{#fallbackURL}}<key>DocSetFallbackURL</key>
+ <string>{{fallbackURL}}</string>{{/fallbackURL}}
+ {{#feedName}}<key>DocSetFeedName</key>
+ <string>{{feedName}}</string>{{/feedName}}
+ {{#feedURL}}<key>DocSetFeedURL</key>
+ <string>{{feedURL}}</string>{{/feedURL}}
+ {{#minimumXcodeVersion}}<key>DocSetMinimumXcodeVersion</key>
+ <string>{{minimumXcodeVersion}}</string>{{/minimumXcodeVersion}}
+ {{#platformFamily}}<key>DocSetPlatformFamily</key>
+ <string>{{platformFamily}}</string>{{/platformFamily}}
+ {{#publisherIdentifier}}<key>DocSetPublisherIdentifier</key>
+ <string>{{publisherIdentifier}}</string>{{/publisherIdentifier}}
+ {{#publisherName}}<key>DocSetPublisherName</key>
+ <string>{{publisherName}}</string>{{/publisherName}}
+ {{#copyrightMessage}}<key>NSHumanReadableCopyright</key>
+ <string>{{copyrightMessage}}</string>{{/copyrightMessage}}
+</dict>
+</plist>
Oops, something went wrong.

0 comments on commit 462cf35

Please sign in to comment.