DaveOnCode » ide

Generate beautiful code documentation with a simple shortcut using AppleDoc, Xcode custom behaviors and AppleScript!

Davide Zanotti — Thu, 08 Dec 2011 10:48:15 +0000

This time I realized something really great and I’m truly satisfied about it!
Few days ago I discovered a fantastic open source project from GentleBytes called AppleDoc by reading a post on Cocoanetics.
This is a tool that generate an Apple-like HTML documentation from source files (by using the proper comment style) and it also generates installable docsets and Atom feeds for the download from a remote host.
After a couple of tests and document generations my big question was: “how can I automatize the process without launching a script every time and for each project I want to document?”.
The first obvious answer was “add a Run Script in the build phases!”… but it’s not a smart idea to launch a similar long script for every build, because it takes several seconds and potentially minutes depending on the amount of classes to analyze, and it’s often unnecessary to update a documentation if method signatures remain the same. So I searched for an alternative way to execute scripts from Xcode only when desired, by focusing my efforts on its “Behaviors” (Xcode > Behaviors > Edit Behaviors > +). Behaviors can be triggered by events (only default behaviors), using menu or with a custom shortcut and a behavior can perform several actions like running a script…
and here I started to waste a lot of time in order to realize what I had in mind (create a single auto-runnable script to generate code documentation for each project without hard-coding paths and names), because the environment variables I was using in Xcode build phases as a test can’t be used in external scripts (since they are not attached to the Xcode process as far I understood).
So the problem was: “how can I retrieve this variables dynamically from our beloved ide? is it possible?”… it’s been an hard google search plus a couple of questions asked on StackOverflow (Did I tell you how much I love that site? I really love it!) in order to clear my dubs… and yes, it’s possible thanks to AppleScript! Xcode exposes several objects that can be queried by this funny script language, so in this way I first realized an AppleScript to retrieve the variables I need (project name, project path and company) and then I invoked my old and refactored bash script passing them.
In conclusion I’m now able to launch document generation for each project I’m working on, by simply press ALT+CMD+D (a custom shortcut of my choice), I also configured a submarine sound effect and the display of a bezel alert… really wonderful!

This is the AppleScript used for the behavior that invoke the bash script by sending it the necessary arguments:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

#!/usr/bin/osascript

tell application "Xcode"
tell first project

-- variables to export
set projectName to (get name)
set projectDir to (get project directory)
set company to (get organization name)

-- invoke script passing extracted variables
do shell script ("sh /PATH_TO_SCRIPT/appledoc.generate.sh " & projectName & " " & projectDir & " " & company)

end tell
end tell

Of course you have to replace “/PATH_TO_SCRIPT/appledoc.generate.sh” according to your path.
If you decide to create your own AppleScript script using the default editor (/Applications/Utilities/Apple Script Editor), remember to save it as a plain text and to include the proper header declaration (#!/usr/bin/osascript), otherwise Xcode will throw an exception trying to run it!

…and this is ~~Sparta~~ the bash (I added a couple of say commands in order to debug the process… remove comments to hear your mac speak!):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

#! /bin/sh

# Input arguments:
# $1 -> project name
# $2 -> project path
# $3 -> company name

# dynamic variables
docsURL="http://www.$3.com/docs";
projectsPath="$2/../";
docsPath="${projectsPath}/AppleDocOutput";

#say "project is: $1";
#say "path is: $2";
#say "company is: $3";
#say "project path is: ${projectsPath}";

# create AppleDocOutput folder if not exists
if [ ! -d $docsPath ];
then
#say "create output folder";
mkdir "${docsPath}";
fi

#say "run appledoc";

#invoke appledoc passing computed arguments
/usr/bin/appledoc \
--project-name "$1" \
--output "${docsPath}/$1/" \
--docset-feed-url "${docsURL}/%DOCSETATOMFILENAME" \
--docset-package-url "${docsURL}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${docsURL}/$1Doc/" \
--ignore "$1Tests" \
"$2" > "${docsPath}/AppleDoc.log"

the bash invokes AppleDoc by assuming its location on /usr/bin/appledoc, the arguments passed are few since I use the GlobalSettings.plist for the main setting and I override only certain options (read GentleBytes reference for more info).
I also redirect the output of the command to a log file for an easy debug.
Remember to make both scripts executable (chmod +x) in order to use them!

…that’s all! If you want more info leave a comment (it’s free)

Xcode key bindings: how to create a custom shortcut to convert upper case text to lower case and viceversa

Davide Zanotti — Fri, 04 Nov 2011 14:41:11 +0000

Since one of the most visited post on my blog is that one about case conversion in Eclipse, I decided to share how to implement 2 custom shortcuts to do the same in Xcode.
In “Preferences” panel, there is a tab called “Key Bindings“, here we can configure keys used for shortcuts. By default the most are already configured, but that’s not the case for text case conversion. By typing “case” to filter the long list, you can see 2 commands: “Lowercase word” and “Uppercase word“, all you have to do is to click on the “key” column and register your shortcut.
To avoid conflicts and to make them simple to remember I did choose “SHIFT + CTRL + L” for the first and “SHIFT + CTRL + U” for the second (but you can register your own one).

Installing Eclipse + Aptana + Subclipse SVN

Davide Zanotti — Wed, 04 Nov 2009 21:18:14 +0000

Recently I’ve updated my Eclipse version and I installed certain plugin which has created some kind of conflict and confusion in my workspace. What I was trying to do was installing an SVN plugin in order to work on a google code SVN repository, but I had several errors and I lost several hours trying to figure out what was wrong. So I decided to do a fresh and clean installation, once understood the problem. So, I would like to write a sort of tutorial which will explain how to get a sound and working installation of Eclipse, Aptana and Subclipse (which as far I read, is actually the best plugin available for SVN on Eclipse).

Install Eclipse

If you have already Eclipse installed, backup your workspace folder somewhere, then delete eclipse installation folder and the old workspace (you will use the old projects folder after by skipping the “.metadata” folder that is the place where Eclipse stores informations about settings and plugins installed). Go to http://eclipse.org/downloads/ and download the Eclipse edition you prefer (I use Eclipse Classic), after extracting the archive, place folder “eclipse” where you like (usually “Programs” folder on windows and “Applications” on Mac). Create a link to the executable file on your desktop (or Mac OS X dock), then launch the program. Since this is the first time you run Eclipse, it will ask where to locate the workspace, choose the destination and folder name you prefer (I use “eclipse-workspace” under my documents). Ok, at this point you should see a welcome screen, close it and choose Help > Install new software… from the top menu (we are going to install Aptana).

Install Aptana

Click on Add… and paste this url in the “Location” field: “http://download.aptana.org/tools/studio/plugin/install/studio” (don’t paste quotes!), write a name for the location entered (I simply called it “Aptana”). Go on, selecting Aptana packages check-boxes and clicking on Next, then accept the terms and click on Finish. It will takes several seconds, then Eclipse will inform you that installation is complete and it will suggest you to restart the program… obey!

Install Subclipse (through Aptana)

Ok, we have Aptana installed and running into Eclipse, now we can select Help > Install Aptana Features from the top menu, then select Others > SCM Plugins > Subclipse and from here select the following package: Core SVNKit library, Optional JNA library, Subclipse. After the routine “next, agree, finish, restart” we have now our beloved ide ready to be used!

IDE configuration

Now that all the stuff is installed, we should spent some time to configure it properly, depending on our needs and taste. Eclipse is a complex and powerfull software and is it possible to set a lot of options: font used, colors, code suggestion, indentation, code collapsing, autoupdate, file encoding, workspace and a lot more. If you never take an in depth look at the preferences panel, I suggest you to spent at list 5 minutes… it deserve the time spent!

Possible issues and resolutions

- If during installation an alert saying “WARNING: you are installing software that contains unsigned content” will appear, just choose ok and you shouldn’t get any problems.

- If you get problems to download from the update site(s), maybe you are blocked by a firewall, you should go to Window > Preferences > General > Network and set the right proxy configuration. If you don’t know how to configure it, you can download the archive version (a .jar or .zip file containing all plugin’s packages) from vendor site.

- If you are trying to add a new SVN repository (by using the installed Subclipse plugin) and you get an error saying “RA layer request failed“, go to Window > Preferences > Team > SVN and in the “SVN interface” choose SVNKit as client instead of JavaHL (default option)… this should solve the problem (in my case it did). If you still get that error or a similar one, maybe is due to firewall limitations, if you can’t change the configuration properly… google and good luck :^)

Aptana’s Javascript editor is too cool!

Davide Zanotti — Fri, 06 Mar 2009 15:03:38 +0000

I’ve just discovered that the last version of the Aptana Studio (in my case the Eclipse plugin version) has an integrated support for javadoc syntax inside js files. The beauty of this feature is that, once you have defined a function, you can just type /** and press enter and Aptana will generate automatically all the comments for you:

Furthermore it will show tips including parameters description when you will use your previous defined function:

…and if you want to add extra “@tag”, the editor will suggest you all tags available:

Too cool!!! I love Aptana :-)

Associate custom file extensions to the default Aptana’s text editor

Davide Zanotti — Mon, 24 Nov 2008 13:06:16 +0000

In a project which I’m working on, the team make an intensive use of text file to include with SSI, and these files are named conventionally .inc, Aptana by default opens these custom extensions with the default system’s editor (notepad on windows). We can tell Aptana to open the .inc or whatever extension we want with the Aptana’s text editor by simply doing the following: Choose window/preferences/Aptana/Editors/Generic Text, click add and then type our desired extension (in my case *.inc). Now if we double click over a .inc file in the project tree view, it will be opened inside Aptana.
ps. The path to the settings panel may change according to the version of Aptana/Eclipse installed (I’m using the Aptana plugin for Eclipse 3.4.1)