Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

TOC headings not created in latest version of XCode. #409

Open
ExoticObjects opened this Issue · 28 comments

6 participants

@ExoticObjects

(Programming Guides, Class References, Category References, and Protocol References) used to be displayed in TOC in XCode 4.5 and greater. But they are not displayed in XCode 5.0.1.

Dash displays Classes, Protocols, Categories, Methods, Properties, Types and Constants.

@robvdveer
Collaborator
@ExoticObjects

Unfortunately I can only make a screenshot of this issue NOT working. To show it working I'd need to download XCode 4.6 again. XCode 5 has no documentation browser.

At any rate, here's what the left menu looks like in the documentation browser in XCode 5.0.1:

screen shot 2013-10-19 at 1 40 07 pm

Note that the XCode 5 doc set has menu items that can be selected, but Jalapeno Documentation does not. It used to! (Programming Guides, Class References, Category References, and Protocol References)

Also, I used to be able to add my own user guide that would appear in the menu by creating and including a template.markdown file, like so

--include "${PROJECT_DIR}/Documentation/appledoc/Using Jalapeno-template.markdown" \

That also has stopped working.

Thanks!

@tomaz
Owner

This might be linked to #409

@ExoticObjects

Erm, unless I'm missing something, this IS issue #409 :-)

@tomaz
Owner

Haha, my bad, meant #408...

@ExoticObjects

I've read through enough of the issues here to understand that we probably shouldn't hope for a quick fix to this. I don't have time to work on appledoc. But people have done so in the past... @robvdveer, for example, has done great work on issues dating all the way back to #2!

The argument I'm trying to make is this: a lot of people use appledoc. Currently, the latest version is unusable with the latest version of xcode. Docset won't display at all. Roll back a few versions and you can get a version that will install a docset, but no table of contents (TOC). This means that navigation is harder, of course, but it also means that some content is completely inaccessible - comments on enums, for example. Doesn't that inconvenience a lot of people? Dunno...

I wish I could allocate the resources, and might have to figure out how to. But at any rate, I just wanted to raise an alert that, as issues #408, #409 and #412 seem to confirm, the current thing is busted. Hopefully those who have fixed it and extended it in the past might find some time to have a look...

@boredzo

I'm working on a presentation I'm giving in a week, but I'll take a break at some point to look into all three issues.

@robvdveer
Collaborator
@ExoticObjects

Feel better @robvdveer...

Thanks @boredzo!

And of course, thanks to @tomaz! appledoc is awesome. Just needs a little nudge...

@tomaz
Owner
@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.

@tomaz tomaz referenced this issue from a commit
@tomaz Fixed docset publish default values case. Addressing #409 and #412.
This commit makes docsetutil tool compile the xar file, however I did not test the results. Plus the code may potentially introduce Dash compatibility issues added with commit 75a3907.
ab45696
@ExoticObjects

@tomaz, unfortunately I don't understand your comment from #408. I'm commenting here as that issue is closed.

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).

You were able to reproduce #409 by failing to provide cmd line switches? If so, which switches? As you say, they seem to be fine in my script (see #408). If my script is fine, what can I do differently? Using latest build and still no left side nav in docset...

@tomaz
Owner

Internally appledoc uses docsetutil to prepare xar file; docsetutil requires a bunch of parameters, -download-url (which corresponds to --docset-package-url) among others. Latest commit fixes default case - when not providing custom docset package url. In such case appledoc falls down to default value which prevents docsetutil error.

I was more or less fixing #412 hoping it would also "automagically" fix this issue :) Will take another look as soon as I can.

@ExoticObjects

So, am I the only one having this issue? Can we confirm that it's a bug? If it's an anomaly of my script or setup, I'd be happy to know that...

@robvdveer
Collaborator
@ExoticObjects

I deleted the templates directory (which is ~/.appledoc, as you said), reinstalled appledoc with

sudo ./install-appledoc.sh -t default

still no deal...

@robvdveer
Collaborator
@tomaz
Owner

It's a bug it happens to me too. My bet is there was a change in how Xcode5 handles docsets - docset guide is now marked as legacy, but I couldn't find any new documentation on subject.

@ExoticObjects

So, can we help you try to find documentation? Maybe send a note to Tim Cook?

@tomaz
Owner

bugreport.apple.com should be better first step :)

@ExoticObjects

I think that might take too long...

FWIW, I believe Doxygen is borked in XCode 5 as well. My Box2D, Chipmunk and various other docsets don't work - can only open folders, can't open files. I mention this because maybe you've corresponded with the Doxygen guy in the past? (I've seen Stackoverflow threads where the two of you chimed in...) Presumably, he's trying to figure it out as well. There aren't a lot of people who've made document readers like this... :wink:

@tomaz
Owner

:) It may take long, but would at least get signal to Apple that we need this. I still didn't get to check how Apple's own docsets are implemented in Xcode 5. So far they used tokens.xml file(s) to describe TOC structure. They may have changed the format, or use completely different method for describing it.

@ExoticObjects

FWIW, Doxygen is fixed in latest XCode preview.

@ExoticObjects

Ok, on one level I think it's kind of pointless to report a bug to Apple. It will probably take a year before it's addressed. When I finally did resign myself to the idea, it occurred to me that it would make a lot more sense for you (@tomaz) to report the bug. As someone who's written a document reader, you'll be able to inform the report with a lot more detail that will be useful to them. All I can say is 'the table of contents doesn't show up.'

So any chance of getting this fixed? As it stands, I can't use appledoc, as documentation without a table of contents gives the impression of being 'broken', which nobody wants... I'm guessing I'm not the only one.

The last commit here says "This commit makes docsetutil tool compile the xar file, however I did not test the results."

Really? I can't imagine committing code without testing if it works.

@tomaz
Owner

No point in being condemning :) I do my best, but was simply too occupied in the past year to make anything substantial. I am connecting with other developers though, so hopefully next year there will bring better progress.

As to my commit message: I was referring to #412; I implemented docset publishing upon user request. Appledoc only generates xar and atom files, but doesn't handle upload. I also don't test publishing and subsequent integration with Xcode, it's just too much time and variables here to be able to support and cover them. But I do test that files are created and that they look fine. This is what my comment was about, it wasn`t the best choice of words though :)

If I can be a bit sarcastic: appledoc is open source, and as such anyone can step in and address things. Not pointing fingers to anyone, there were sure tons of great folks contributing to the project and it definitely wouldn't be where it is now without their help!

@ExoticObjects

I misinterpreted your comment, but as you note, it was open for misinterpretation! Sorry - I also could have chosen my words better...

Here's what I'm trying to say. I could spend 1-4 weeks spinning up on appledoc. From what I've seen, it appears to be really well written, but it's undeniably complex. I might get lucky and fix the problem quickly, but most likely would not. It's irrelevant, unfortunately, as there's no way I can spare that time... So, while it's true that appledoc is open source and anyone can step in and address things, most people are in my position - too busy to even consider it.

Where does that leave appledoc? Well, maybe it doesn't bother anyone else that the left menu navigation is broken... In which case, lots of people will continue to use it. But for me, this is a deal-breaker. Or, maybe Apple is finally going to properly implement documentation - it's pathetic that they never really have - in which case people will switch to whatever that is. Or, maybe people will be happy with Doxygen - but I already know that we all like appledoc better :-) Whatever the case, I don't see Apple thinking that their failure to publish changes to the way XCode handles docsets is a 'bug.' It seems extremely unlikely that they'll remedy this situation anytime soon.

So someone has to dive in - it seems a shame for the thing to stay broken. I'm hoping you can find some time @tomaz, or perhaps some of the other committers can step in. It's a great piece of work. Thanks for creating it in the first place! I hope it can get over this bump...

@tomaz tomaz added this to the 3.0 milestone
@tomaz tomaz added the Known label
@wittedhaddock

What is this issue's status? Any recent developments that would address this?

@Czajnikowski

The same issue here, isn't it related to some temp/cache files? I was able to create a proper docset but I think after I deleted stuff in ~/Library/Developer/Shared/Documentation/DocSets it seem to break

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.