Use appledoc to build the documentation.

[tiennou]

This also closes #822. Note that you won't be able to build the docs from master because of the weird -_contents accessor in QSCatalogEntry (fixed by #1601, so you can only use it on that one for now).

The ./Tools/build_docs.sh script builds HTML documentation in ./Docs by default, and an Xcode docset if you pass it -d.

[tiennou]

Okay good to go ;-). You should be able to give it a go by switching to the "Build Documentation" target, then ⌥-doubleclick on various symbols to get the documentation viewer for that symbol.

[skurfer]

Pretty cool. Now we just have one or two descriptions to write. 😉

[skurfer]

BTW, we should mention brew install appledoc in the build instructions on the wiki once this is merged. And the script. Hmmm. Maybe it should just have its own wiki entry.

[pjrobertson]

Maybe some documentation somewhere would be good?
I had to ask Mr Skurfer how to actually read the docs :( (although now I realise I don't need to do anything with the files themselves, just opt-click a method!)

I'm happy, just need #1601 as Rob has said

[pjrobertson]

One other thing: can you drag the "Quicksilver Distribution" target to the top of the list of targets in the project view? It's always annoying having to scroll to the bottom. Plus it might help noobs opening the project for the 1st time.

I'm asking here so it doesn't cause any merge conflicts

[HenningJ]

Can one of the admins verify this patch?

[skurfer]

ok to test

[HenningJ]

Well...this failing does highlight that we need to mention brew install appledoc somewhere. :)

[tiennou]

BTW, brew install appledoc is needed (damn, too late they found out :-D).

[HenningJ]

this is ok to test

[HenningJ]

hmm...I did a brew install appledoc and look what it got me:

Oops, something went wrong...
AppledocException: Failed merging -[QSCatalogEntry contents] to @propertyQSCatalogEntry.contents; getter or setter doesn't match
  @ 0   CoreFoundation                      0x00007fff8d00f41c __exceptionPreprocess + 172
  @ 1   libobjc.A.dylib                     0x00007fff946bae75 objc_exception_throw + 43
  @ 2   CoreFoundation                      0x00007fff8d00f1f8 +[NSException raise:format:arguments:] + 104
  @ 3   appledoc                            0x0000000108c70533 appledoc + 42291
  @ 4   appledoc                            0x0000000108c7f6c9 appledoc + 104137
  @ 5   appledoc                            0x0000000108c7f781 appledoc + 104321
  @ 6   CoreFoundation                      0x00007fff8cf43639 __53-[__NSArrayM enumerateObjectsWithOptions:usingBlock:]_block_invoke + 137
  @ 7   CoreFoundation                      0x00007fff8cf42ddf -[__NSArrayM enumerateObjectsWithOptions:usingBlock:] + 319
  @ 8   appledoc                            0x0000000108c7d005 appledoc + 94213
  @ 9   appledoc                            0x0000000108c7854d appledoc + 75085
  @ 10  appledoc                            0x0000000108c7562c appledoc + 63020
  @ 11  appledoc                            0x0000000108c74961 appledoc + 59745
  @ 12  appledoc                            0x0000000108c72866 appledoc + 51302
  @ 13  appledoc                            0x0000000108c70e6f appledoc + 44655
  @ 14  appledoc                            0x0000000108c71c74 appledoc + 48244
  @ 15  appledoc                            0x0000000108c70bed appledoc + 44013
  @ 16  appledoc                            0x0000000108c6973e appledoc + 14142
  @ 17  appledoc                            0x0000000108c682f3 appledoc + 8947
  @ 18  appledoc                            0x0000000108c684d7 appledoc + 9431
  @ 19  appledoc                            0x0000000108c679d4 appledoc + 6612
  @ 20  ???                                 0x000000000000001d 0x0 + 29
Command /bin/sh failed with exit code 250

Is that supposed to happen?

[skurfer]

Is that supposed to happen?

I wouldn’t go that far, but it’s a known problem. See @tiennou’s initial comment when he opened this request. Also see one of @pjrobertson’s previous comments on another issue.

[HenningJ]

Oh right. Maybe I should read some of the comments on the pull requests before I pitch in ;-)

[tiennou]

Okay, don't merge that in yet. After writing some documentation for #1601 I think I missed a few settings so I'll have to investigate some more. Right now it has a tendency to put links to words that correspond to methods, which looks a little weird (I'll push what I have written so you guys can see).

[tiennou]

Also, https://github.com/onevcat/VVDocumenter-Xcode

[pjrobertson]

VVDocumenter is cool. I will start using it :)

Anybody else wanting to use it but not bothered with building it, put this file in ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins

[HenningJ]

ok to test

[skurfer]

Has anyone else lost the ability to ⌥-click and things like that (even for the built-in Apple methods)? It started around the time I tested this, so I suspect it’s related. Could Xcode now be looking for files that don’t exist?

[pjrobertson]

Just tested, and I get a fancy animation, then the window just turns into a small arrow and I can’t see the actual docs.
I think it’s been a bug for a while. I haven’t used opt-click for a while now, probably because it was broken

On 25 Chwef 2014, at 22:05, Rob McBroom notifications@github.com wrote:

Has anyone else lost the ability to ⌥-click and things like that (even for the built-in Apple methods)? It started around the time I tested this, so I suspect it’s related. Could Xcode now be looking for files that don’t exist?

—
Reply to this email directly or view it on GitHub.

[skurfer]

I get a fancy animation, then the window just turns into a small arrow and I can’t see the actual docs.

Yeah, that’s exactly what I see. Some searching revealed this:

defaults delete com.apple.dt.Xcode WebKitJavaScriptEnabled

Either that, or keep it and set it to YES.

[tiennou]

Closing because appledoc has been removed from brew (bc no Xcode 5.1 support). I still plan on adding documentation comments, so maybe someday we'll have nice documentation ;-).