Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Create an Atom feed so that Xcode can load docset from URL #45

Closed
PrimaryFeather opened this Issue · 7 comments

2 participants

@PrimaryFeather

It would be great if that was possible. Here is an example of how this would look like:

Like this one:
http://aptocore.com/downloads/cocos2d/cocos2d-iphone-doc.atom

That way, people can add it to Xcode via Xcode / Preferences / Documentation / Add Publisher.

@tomaz
Owner

In the given file a href and size to compressed docset are included. This would require compressing docset. Although I'm not sure that is required by Xcode as a minimum. Will check Apple documentation.

@PrimaryFeather

I had a look at this, and thankfully it's relatively easy to create the compressed docset and the atom feed.

Here is the link to Apple's documentation:

http://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/Documentation_Sets/070-Acquiring_Documentation_Sets_Through_Web_Feeds/acquiring_docsets.html

Creating the feed and compressing the docset is done by 'docsetutil'. The relevant arguments are described here, at the bottom of the page:

http://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/Documentation_Sets/090-docsetutil_Reference/docsetutil.html

To test this feature, just execute the following call in the terminal, from the directory containing the docset. For some reason, you have to rename the "docset" directory to "docset.docset" - otherwise, Xcode did not accept it, at least in my experiments. Perhaps I've missed something. Anyway, that way it should work:

/Developer/usr/bin/docsetutil package -atom docset.atom -download-url http://www.some-url/my-lib.docset.xar -output my-lib.docset.xar docset.docset

This creates 2 files:

  • docset.atom
  • my-lib.docset.xar

When you upload those 2 files on a webserver and post Xcode to it, everything's settled. It would be great if AppleDoc would get the option of doing this automatically!

@tomaz
Owner

Great, if it's so simple it would make no sense to let users do it manually. As it seems to be little additional work and would fit appledoc purpose, I will add it to 2.0 release.

@tomaz
Owner

Implemented preparing for docset publishing. Closed by a28b2ff.

The feature must be enabled by --publish-docset (this was errouneously stated --package-docset previously!) and works by using the information from --docset-feed-url which is required by docsetutil when packaging. The result of using it is publish directory in output path with .xar and .atom files. If the .atom file is already there, it is updated if needed, otherwise it is created.

@PrimaryFeather

Sounds great!! That makes it extremely convenient to provide updated docs for a library. I will test this ASAP. Thanks a lot for your efforts!

@tomaz
Owner

Fixed atom file generation, please update to latest version. Basically had to add another command line switch for specifying URL of the xar file itself - see commit 895b881c48fbd5b35640 for more information.

@tomaz
Owner

Also updated online documentation with example on generating published files.

@tonklon tonklon referenced this issue from a commit in tonklon/appledoc
@tomaz Implemented preparing for docset publishing. Closes #45.
The feature must be enabled by --package-docset and works by using the information from --docset-feed-url which is required by docsetutil when packaging. The result of using it is publish directory in output path with .xar and .atom files. If the .atom file is already there, it is updated if needed, otherwise it is created.
a28b2ff
@tonklon tonklon referenced this issue from a commit in tonklon/appledoc
@tomaz Implemented proper docset packaging handling. Relates to #45.
Instead of relying on hardcoded docset filenames, the can now be supplied through command line switches. Additionally, all docset names can be used as placeholders, so specifying stuff like --docset-feed-url is simpler.
afef3b2
@tonklon tonklon referenced this issue from a commit in tonklon/appledoc
@tomaz Fixed published atom file handling. Closes #45.
The problem was with using the value of `--docset-feed-url` as `-download-url` for docsetutil when generating package. That parameter expected the URL of the xar, not of the feed itself. By adding additional command line switch `--docset-package-url`, we can now distinguish between the two!

With this commit, packaging docset should become usable. However I haven't tested it myself.

Also added command line switched for changing docset bundle, atom and package filenames. Although this isn't necessary for publishing (default values should work just fine), it adds options for power users. And these options were available in GBApplicationSettingsProvider anyway.
895b881
This issue was closed.
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.