Error trying to install AppleDoc tool

[Jonathan Sachs]

I'm a technical writer responsible for documenting an SDK that's being developed for iOS. I have programming background, but none with iOS or Objective C, and not a lot with the Mac.

I've installed Xbase (v6.1 beta, required for this project). I'm now trying to install the AppleDoc tool.

I downloaded the AppleDoc installer and ran 'sudo sh install-appledoc.sh' in a terminal window. (I don't know what version this is. The appledoc.m file says, "Created... on 22.7.10.")

I got the following message:

Building…
Xcode-select: error: tool ‘xcodebuild’ requires Xcode, but active developer directory ‘/Library/Developer/CommandLineTools’ is a command line tools instance

Could someone please help me understand what this means and what to do about it?

[Tom @ Gentle Bytes]

It's probably install script that's hard wired into specific Xcode path. I didn't write the script, so not sure about exact implementation, but there are other ways of installing, homebrew for example. Or just use Xcode and build from source (in this case you'll need to manually copy template files to one of the expected folders).

Hope this gives you a headstart...

Cheers, Tom 

--
You received this message because you are subscribed to the Google Groups "appledoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email to appledoc+u...@googlegroups.com.
To post to this group, send email to appl...@googlegroups.com.
Visit this group at http://groups.google.com/group/appledoc.
For more options, visit https://groups.google.com/d/optout.

[Jonathan Sachs]

Thank you, Tom. I hope you'll be patient with me; since my OS X background is limited, I may not understand some things that you think should be obvious.

Your post implied that AppleDoc is bundled with Xcode. I originally assumed it would be, but the documentation I found appeared to say it is not. I'd be happy to learn that I misunderstood.

There's no appledoc file (or any similarly named file) in the Applications folder, where the Xcode executable lives. The terminal window doesn't recognize appledoc as a command. If AppleDoc is bundled with Xcode, it seems be bundled in such a way that it isn't accessible from the command line. That alone creates problems, since the AppleDoc documentation only explains how to use it from the command line 9with switches for setting the output folder, etc). I didn't see any provision in Xcode's menu system for performing such operations through the GUI.

I tried building the project. I don't know where the AppleDoc output should appear, but I poked around the subfolders in the folder that contains the .xcodeproj file, and I didn't see anything that looked likely.

So right now I'm not sure what to do, or even what kind of measure to look for. Any further direction you can give me will be welcome and appreciated.

[Tom @ Gentle Bytes]

Appledoc is not bundled with Xcode (it doesn’t come with Xcode app), you need to download its sources from GitHub and build it yourself or use alternative means to install such as homebrew.

In general compiling with Xcode will produce executable on ~/Library/Developer/Xcode/DerivedData (~ stands for your user account home folder which depends on your user name. For you it could be /Users/Jonathan or something along the line). After compiler is done, you’ll see appledoc-xxxxxxxxxx folder (xxxxxxx is some kind of random salt Xcode adds). In there you’ll see a bunch of folders and files, navigate to Build/Products/Release (or Debug) which is where you’ll find appledoc executable. You could leave it in there, but then you’ll always need to provide whole path when invoking it, so it’s recommended you copy it to one of folders which are searched for when launching executables on OS X. These are usually standard UNIX folders such as /usr/bin etc. (you can find whole list by running “echo $PATH” in Terminal - individual folders are separated by colons in this list). To copy appledoc binary in one of those (I’d go with /usr/bin), open Terminal, then:

- Navigate to Xcode derived data folder for appledoc as described above

- Open Terminal

- Type “cp “ (note there’s space after “cp”

- Drag appledoc binary from Finder to Terminal - this will append the path to cp command

- Back to Terminal, type  and /usr/bin (in full, the command would be “cp <dragged path> /usr/bin”)

- Press enter

Now you should be able to simply type “appledoc” and it’ll find and launch the program. Since a while ago template files are bundled within appledoc binary (another contribution), so this may be all that’s needed, but otherwise you’ll need to copy templates from appledoc source into ~/Library/Application Support/appledoc folder.

As mentioned there is install.sh script included with appledoc sources. It’ll basically perform above steps for you - from compile to copy files. It’s contribution and I never maintained it so it may be out of date.

Homebrew (http://brew.sh) is another solution for installing appledoc without fiddling with Xcode. It’s probably the simplest of all (after you install brew program or if you already happen to have it installed). I’m not sure if it installs the latest version though.

Hope this helps, let me know otherwise…

Best, Tom

[Jonathan Sachs]

Tom, first, let me say that you don't need to explain what ~ means and how to copy a file with cp. I am grounded in basic Linux concepts and operations. When it comes to OS X specific stuff and iOS, though, I'll appreciate having everything spelled out at that level!

I gather from your explanation that appledoc has to be separately installed, but once it is installed it is integrated into Xcode's build process. If that's correct, then my immediate problem is the one I brought here: how to accomplish the appledoc install. I'd like to concentrate on that issue for now, since I can't act on any others until it is resolved.

You originally said, "It's probably [an] install script that's hard wired into specific Xcode path.... not sure about exact implementation, but there are other ways of installing, homebrew for example."

Let's see how we can approach this task. Ideally I'd like to use the method that appledoc's publisher intended -- the installer -- but if that isn't feasible I'm open to any alternative. Can you advise me on that?

I've never heard of "homebrew" (in this context) before. I looked it up, so now I know what it is, but at this stage in my OS X education, installing and using it looks rather daunting. I foresee problems; for example, to support another project my Mac runs a beta version of Ruby rather than the one it came with. I'm game to try it, though, if you think it's the best approach for me and you're game to help.

Skipping ahead a bit, I was confused by your explanation of where to look for the appledoc executable. In summary, you said that after the build I'd find it in ~/Library/Developer/Xcode/DerivedData/Build/Products/{Release|Debug}. But it's a development tool -- not a part of the project -- so I don't understand why it should be there, and if it is, where it comes from. Did I misunderstand something about what "appledoc" is?

[Tom @ Gentle Bytes]

Hi Jonathan!

Wasn’t sure to what extent you were comfortable with command line etc. - sorry if I was being too child-stepping with you (on the other hand, sometimes I do get questions from folks who in fact don’t know anything about UNIX cmd line :)

On 24 Sep 2014, at 23:20, Jonathan Sachs via appledoc <appledoc+noreply-APn2wQdr3d6zfW6...@googlegroups.com> wrote:

Tom, first, let me say that you don't need to explain what ~ means and how to copy a file with cp. I am grounded in basic Linux concepts and operations. When it comes to OS X specific stuff and iOS, though, I'll appreciate having everything spelled out at that level!

I gather from your explanation that appledoc has to be separately installed, but once it is installed it is integrated into Xcode's build process. If that's correct, then my immediate problem is the one I brought here: how to accomplish the appledoc install. I'd like to concentrate on that issue for now, since I can't act on any others until it is resolved.

About automatic Xcode integration: regardless of method of installation (direct compile with Xcode + copying of files into appropriate paths / install.sh script / homebrew). Once appledoc is installed you must run it over your source files in order to generate documentation. How you do that is up to you; it can be manual process, running appledoc from command line whenever you want to generate documentation. Alternatively you could add script build phase to your Xcode project that will do it for you on every build. See sidebar on the right on http://gentlebytes.com/appledoc/ to get links to various tutorials.

You originally said, "It's probably [an] install script that's hard wired into specific Xcode path.... not sure about exact implementation, but there are other ways of installing, homebrew for example."

Let's see how we can approach this task. Ideally I'd like to use the method that appledoc's publisher intended -- the installer -- but if that isn't feasible I'm open to any alternative. Can you advise me on that?

I intended appledoc to be installed via Xcode. That is, build sources and copy files manually (as described in my previous email). As mentioned in past emails, install.sh script and homebrew were community contributions. They are there for less experienced developers, but I never looked into that in depth so I can’t provide much but basic support. That said, install script you used to install appledoc probably relies on Xcode being properly installed (possibly in exact folder - /Applications most likely). But other than that, it should work (otherwise I’d be getting tons of support questions :) All in all, install script is just a convenience wrapper over manual installation: it compiles appledoc, copies binary to a folder in PATH and copies template files to expected location. You could do everything manually but would of course be more tedious.

I've never heard of "homebrew" (in this context) before. I looked it up, so now I know what it is, but at this stage in my OS X education, installing and using it looks rather daunting. I foresee problems; for example, to support another project my Mac runs a beta version of Ruby rather than the one it came with. I'm game to try it, though, if you think it's the best approach for me and you're game to help.

Skipping ahead a bit, I was confused by your explanation of where to look for the appledoc executable. In summary, you said that after the build I'd find it in ~/Library/Developer/Xcode/DerivedData/Build/Products/{Release|Debug}. But it's a development tool -- not a part of the project -- so I don't understand why it should be there, and if it is, where it comes from. Did I misunderstand something about what "appledoc" is?

Yes and no. Appledoc is of course not part of the SDK project you’re documenting, but it’s also Xcode project itself. Perhaps you weren’t aware of it, but the thing you downloaded from github was appledoc source files (I assume you downloaded from there, otherwise you wouldn't have install.sh script). In essence, appledoc is as much of a Xcode project as any other tool or app. It’s a bunch of source files and instructions of how they should be built to generate executable. You can open appledoc.xcodeproj in Xcode and compile it there. After compiling, Xcode will put executable to indicated folder (note that you ommited appledoc-xxxxxxxxxx folder in your example path above. xxxxxxx is some “gibberish" Xcode adds, on my computer full path is ~/Library/Developer/Xcode/DerivedData/appledoc-bxwomlxuvkgdsufjkyfnakbiqwku/Build/Products/Debug, it will be just like this on your computer except for the random letters after dash).

Hope this provides enough insight to get you started…

Cheers, Tom

[Jonathan Sachs]

I built the project, copied the executable to ~/Applications, and changed its name to "Appledoc."

The next question is how to run it? I've found numerous web pages that purport to explain that, but some are so specific that I can't apply them to my situation, and others are so comprehensive that I can't understand them at my current level of of OS X knowledge.

I gather there are two ways to run it: from the command line, using switches that I can't find explained clearly, and from Xcode, using project management dialogs that presuppose a working knowledge of Xcode.

I think I'll eventually want to use both methods, but right now I'd settle for getting either one to work! Can you give me advice?

-- Jonathan

[Tom @ Gentle Bytes]

Hi Jonathan!

See my answers inline...

On 01 Oct 2014, at 22:45, Jonathan Sachs via appledoc <appledoc+noreply-APn2wQdr3d6zfW6...@googlegroups.com> wrote:

I built the project, copied the executable to ~/Applications, and changed its name to "Appledoc."

Both of these are fine by themselves, just take care if using online resources/tutorials; they typically assume appledoc executable is lowercase (as other UNIX command line tools) AND it is located on bash PATH (one of folders from PATH that is). So instead of using "appledoc", you should be using "/Applications/Appledoc"...

The next question is how to run it? I've found numerous web pages that purport to explain that, but some are so specific that I can't apply them to my situation, and others are so comprehensive that I can't understand them at my current level of of OS X knowledge.

To run, simply type "appledoc" in Terminal (remember, you need to use "/Applications/Appledoc") to verify everything is fine. This should show version but then complain because it's missing required arguments. You can use my old website to get you going: https://web.archive.org/web/20120818121541/http://gentlebytes.com/appledoc/ (see sidebar on the right - I added the link to my new website, but somehow managed to discard it)

I gather there are two ways to run it: from the command line, using switches that I can't find explained clearly, and from Xcode, using project management dialogs that presuppose a working knowledge of Xcode.

I think I'll eventually want to use both methods, but right now I'd settle for getting either one to work! Can you give me advice?

As mentioned above, use my old website to get you started. You should find links to various online tutorials to help you setup Xcode script on http://gentlebytes.com/appledoc

-- Jonathan

[Jonathan Sachs]

I'm sorry about my long silence. I got some assistance from one of the people whose project I'm supposed to be working on, and while that was happening, all I could have said was "please hold." My helper seems to have gone away again, leaving me in better shape than before but not yet good to go.

My helper reinstalled both Xcode and Appledoc and gave me a script to run Appledoc, generating a set of HTML files for the project. When I run the script I get a bunch of error messages, but no output. The error message are:

1. "pathname:linenumber: warning: somename is not documented!" repeated a couple of dozen times. I assume that these warnings are caused by omissions in the source files; they aren't preventing Appledoc from generating output; and therefore I can ignore them for the present.

2. The following messages:

--docset-package-url is required for publishing DocSet; placeholder will be used in '~/Documents/BeaconLibDocs/publish/com.paypal.PayPalBeacon.framework.atom'!
!> Unable to generate atom feed, because docset does not define a feed URL for itself.
!> Failed to generate atom feed for package
Generation step 5/5 failed: GBDocSetPublishGenerator failed generating output, aborting!
docsetutil failed to package the documentation set!
Unable to generate atom feed, because docset does not define a feed URL for itself.
Failed to generate atom feed for package

These messages aren't meaningful to me. Can you help me understand what went wrong?

[Tom @ Gentle Bytes]

Hi Jonathan!

See my answers inline!

Best? Tomaz

On 16. okt. 2014, at 18.49, Jonathan Sachs via appledoc <appledoc+noreply-APn2wQdr3d6zfW6...@googlegroups.com> wrote:

I'm sorry about my long silence. I got some assistance from one of the people whose project I'm supposed to be working on, and while that was happening, all I could have said was "please hold." My helper seems to have gone away again, leaving me in better shape than before but not yet good to go.

My helper reinstalled both Xcode and Appledoc and gave me a script to run Appledoc, generating a set of HTML files for the project. When I run the script I get a bunch of error messages, but no output. The error message are:

1. "pathname:linenumber: warning: somename is not documented!" repeated a couple of dozen times. I assume that these warnings are caused by omissions in the source files; they aren't preventing Appledoc from generating output; and therefore I can ignore them for the present.

Exactly! Appledox expects all classes and methods are documented; if not, it prints out these warnings as a reminder. If you'll be adding comments, that's fine, but otherwise you can use --no-warn-undocumented-objects and --no-warn-undocumented-methods command line argument to prevent appledoc from writing out these warnings.

2. The following messages:

--docset-package-url is required for publishing DocSet; placeholder will be used in '~/Documents/BeaconLibDocs/publish/com.paypal.PayPalBeacon.framework.atom'!
!> Unable to generate atom feed, because docset does not define a feed URL for itself.
!> Failed to generate atom feed for package
Generation step 5/5 failed: GBDocSetPublishGenerator failed generating output, aborting!
docsetutil failed to package the documentation set!
Unable to generate atom feed, because docset does not define a feed URL for itself.
Failed to generate atom feed for package

These messages aren't meaningful to me. Can you help me understand what went wrong

Appledoc tries to generate docset but needs additional parameters for that. For now just tell it not to generate docset with --no-create-docset. This will only generate html files; should be enough for testing documentation.

[Jonathan Sachs]

Thank you for the additional advice. I added --no-create-docset to the command and deleted a couple of switches that looks unnecessary (possibly conflicting) with it. The errors following "...is not defined!" went away, but I'm still not getting HTML output.

Here's the script with possibly sensitive material obfuscated:

#!/bin/bash

/usr/local/bin/appledoc \
--project-name "Obfuscated.framework" \
--project-company "Obfusc" \
--company-id "com.obfusc" \
--output "~/Documents/ObfuscatedLibDocs" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-create-docset \
--no-warn-invalid-crossref \
--ignore "*.m" \
--index-desc index.md \
--include . \
../ObfuscatedLib/API

As I understand this, Appledoc should create the HTML files in ~/Documents/ObfuscatedLibDocs. After I ran the script I observed that the ObfuscatedLibDocs folder didn't exist; I created it and ran the script again, but it still didn't create anything there.

[Tom @ Gentle Bytes]

Hi Jonathan!

Sorry for long delay, had too much work…

Check if there’s some header files on “../ObfuscatedLib/API” path; that should be relative to path where you launch appledoc from. You can first just try and put absolute path to API files.

If that doesn’t help try adding --verbose 3 to get some more verbose logging. Then check output - it should state what folders and files it’s scanning and what kind of data it parses in there.

Best, Tom