Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Latest version doesn't install docset in XCode 5.0.1 #408

Closed
ExoticObjects opened this Issue · 21 comments

5 participants

@ExoticObjects

I don't think the issue is Xcode, though.

Symptom: Running Appledoc build does not result in docset being available in XCode's (still!) inferior docset viewer.

Resolution: Reverting to commit aaca91b fixes the issue.

@robvdveer
Collaborator
@ExoticObjects

Up to this commit, 011d5cc, when I build my documentation target, the docset will appear in /~/Library/Developer/Shared/Documentation/DocSets and also in the XCode Documentation and API Reference viewer.

If I checkout that commit, however, the docset still appears in the folder, but not in the viewer. If I go to that folder and try to open the docset with Dash, Dash says:

docset is invalid.

The docset does not have an index file. Maybe the docset has not been indexed?

This is most likely an improperly downloaded docset. Manually delete the docset and redownload it.

The commit comment reads: Separated finalizing a docset from installing it. By finalizing, I mean delivering it to the install path. By installing it, I mean handing it to Xcode.

This led me to think that maybe I wasn't explicitly telling appledoc to install my documentation in Xcode. But I was. I've tried both --publish-docset and --install-docset (with and without the new --finalize-docset) and none of the options installs the docset to XCode when using this build of appledoc.

The fact that Dash doesn't like the docset leads me to think that maybe something has gone wrong.

@tomaz
Owner

Does it work with --finalize-docset?

@ExoticObjects

As I mentioned above, I tried --finalize-docset in combination with --publish-docset and --install-docset (separately). Should I try it alone? If that works, a lot of people might be confused when their appledoc build doesn't install the documentation to XCode anymore.

The commit comment indicated that finalize was separate from install (make available in XCode viewer).

@tomaz
Owner

It seems linked to that feature, I checked the code and it seems ok on the surface. Will take another look.

@boredzo

--install implies --finalize (https://github.com/tomaz/appledoc/blob/011d5cc3d5a119b66fcc2eafc115199cc8d41f02/Application/GBAppledocApplication.m#L786), so specifying --finalize in addition to --install should not be necessary. (This is consistent with the other options that were already there.)

@dmcgloin

As a data point, I'm seeing this issue as well. I'm not seeing any failures building or installing the docset, but Xcode does not display it and Dash considers the docset invalid. Using Xcode version 5.0.1 (5A2053). Looking like I need to pull a version before this latest change.

@ExoticObjects

I believe 2e6c541 is the last version that will be viewable at all in XCode 5.01.

However, as far as I can tell, no appledoc version addresses issue #409.

@dmcgloin

Thanks @ExoticObjects !. Got it working with that version.

@boredzo

@ExoticObjects, @dmcgloin: Are the sources you're generating docs from public? I'd like to take a stab at fixing these bugs.

@ExoticObjects

Unfortunately, no...

I can include my build script, though, if you think it will help.

@boredzo

@ExoticObjects Sounds good.

@ExoticObjects

Here you go:

# Start constants
company="xxxxxxxxxx";
companyID="xxxxxxxxxx";
companyURL="xxxxxxxxxxx";
target="iphoneos";
outputPath="~/Sites/xcode_workspace/help/${PROJECT_NAME}";
# End constants

/usr/local/bin/appledoc \
--exit-threshold 2 \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/docs/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/docs/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/docs" \
--docset-platform-family "${target}" \
--include "${PROJECT_DIR}/Pods/Headers/LocalLibrary-lib" \
--index-desc "${PROJECT_DIR}/Documentation/appledoc/Top_level.markdown" \
--keep-intermediate-files \
--keep-undocumented-objects \
--keep-undocumented-members \
--logformat xcode \
--merge-categories \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--no-warn-undocumented-object \
--no-warn-undocumented-member \
--no-warn-empty-description \
--output "${outputPath}" \
--install-docset \
--print-information-block-titles \
--use-code-order \
--verbose 4 \
--ignore "*.m" \
--ignore "*.pch" \
--ignore "*.config" \
--ignore "*.xcconfig" \
--ignore "*.docset" \
--ignore "*.xcodeproj" \
--ignore "*.xcworkspace" \
--ignore "*.lock" \
--ignore "*.plist" \
--ignore "*.strings" \
--ignore "*.txt" \
--ignore "*.app" \
--ignore "*.podspec" \
--ignore "*.jnlp" \
--ignore "*.jar" \
--ignore "*.png" \
--ignore "*.jpg" \
--ignore "*.html" \
--ignore "*.xml" \
--ignore "*.sh" \
--ignore "*.gitignore" \
--ignore "Podfile" \
--ignore "ci_build" \
--ignore "LoadableCategory.h" \
--ignore ".idea" \
--ignore "build" \
--ignore "Documentation" \
--ignore "XXXXXX_Unit_Tests" \
--ignore "Jenkins" \
--ignore "Resources" \
--ignore "BuildHeaders" \
--ignore "Igor" \
--ignore "Kiwi" \
--ignore "Local Podspecs" \
--ignore "PublicAutomation" \
--ignore "SDWebImage" \
--ignore "SVProgressHUD" \
--ignore "SVPullToRefresh" \
--ignore "CocoaLumberjack" \
--ignore "Toast" \
--ignore "PonyDebugger" \
--ignore "PonyDebuggerLogger" \
--ignore "SocketRocket" \
"${PROJECT_DIR}"
@boredzo

@ExoticObjects: Are you running appledoc as part of an Xcode build phase?

@tomaz tomaz referenced this issue from a commit
@tomaz Fixed docset installation. Addressing #407, #408, #409 and #412.
The problem was due to template files copy step issued for each output generator. This code basically deletes output path and copies template files over. However in doing so after docset was already prepared, it invalidated all previous effort.

PS Don't worry about the number of addressed issues - these are (likely) pointing to the same problem!
877681c
@tomaz
Owner

I think I found the culprit, please verify and close the issue if so.

To keep merit where it belongs :) - it's not @boredzo code fault, the change he introduced merely exposed the weakness of generation system.

@dmcgloin

@tomaz - you rock! Confirmed fix with latest. thanks very much!

@ExoticObjects

Still not working for me. Seems like it's probably my fault somehow, but I'll post the details in case it's an edge case that helps someone else.

What happens: docset is installed, but still no navigation on the left in Xcode. When viewed in Dash, navigation is there. So this build solves #408 for me, but not #409.

Here's my appledoc script. I removed as many of the --ignore directives as I could, on the off chance that they were messing something up. @boredzo , yes, it's part of an XCode build phase:

#appledoc Xcode script

# Start constants
company="xxxxxxxx";
companyID="xxxxxxxx";
companyURL="xxxxxxxx";
target="iphoneos";
#target="macosx";
outputPath="~/Sites/xcode_workspace/_help/${PROJECT_NAME}";
# End constants

/usr/local/bin/appledoc \
--exit-threshold 2 \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/docs/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/docs/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/docs" \
--docset-platform-family "${target}" \
--keep-intermediate-files \
--keep-undocumented-objects \
--keep-undocumented-members \
--logformat xcode \
--merge-categories \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--no-warn-undocumented-object \
--no-warn-undocumented-member \
--no-warn-empty-description \
--output "${outputPath}" \
--install-docset \
--print-information-block-titles \
--use-code-order \
--verbose 4 \
--ignore "*.m" \
--ignore "LoadableCategory.h" \
--ignore "BuildHeaders" \
--ignore "Igor" \
--ignore "Kiwi" \
--ignore "PublicAutomation" \
--ignore "SDWebImage" \
--ignore "SVProgressHUD" \
--ignore "SVPullToRefresh" \
--ignore "CocoaLumberjack" \
--ignore "Toast" \
--ignore "PonyDebugger" \
--ignore "PonyDebuggerLogger" \
--ignore "SocketRocket" \
"${PROJECT_DIR}"

Anybody see anything wrong with the script?

If I change --install-docset to publish-docset, I get the error described in #412:

Preparing DocSet for publishing...
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

The thing is, the script DOES define a feed URL for itself.


Here's my appledoc version:

$ appledoc --version
appledoc version: 2.2 (build 961)

I'm running the 5.01 seed of XCode:

Version 5.0.1 (5A2034a)

Maybe that's it? I'll upgrade XCode and see. Maybe they fixed something in the Docset viewer...

I'll post progress if there is any. In the meantime I'll upgrade to the latest release of XCode and see if that fixes it.

@ExoticObjects

After upgrading XCode through the App store, no change.

Version 5.0.1 (5A2053)

@boredzo

@ExoticObjects:

So this build solves #408 for me, but not #409.

Did you mean to post that on #409, then?

@ExoticObjects

I suppose I could, but the discussion that led to the issues being fixed or mostly fixed occurred on this thread. To preserve context, I put it here.

@tomaz
Owner

The error is from docsetutil. I tried it myself and I can reproduce the error (if failing to provide cmd line switches for docset that seem to be fine in your script). With this new fix it works. Give it a go and comment on #409 (closing this issue to keep focus - it's referenced on #409 anyway).

@tomaz tomaz closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.