Links into api documentation don't work in safari on iOS

[gordonwoodhull]

Trying to help someone on SO, I noticed that the following link works in chrome but not safari on iOS:

https://github.com/dc-js/dc.js/blob/develop/web/docs/api-latest.md#dc.baseMixin+minWidth

I wonder if there is some timing issue with the markdown rendering?

[gordonwoodhull]

Seems not to be an issue with Chrome, or with either browser on OSX. Maybe it's just a browser issue and there's nothing we can do about it. Still, it's annoying.

[75lb]

it was awkward enough getting the links to work in Chrome (as github modifies the target anchor tag's name attribute, adding its own prefix).. ordinarily we'd point the link at an id of a heading element but github strips ids entirely.. still, i'll revisit this at some point.

[75lb]

still, it's odd that the links with in Safari but not Mobile Safari..

[gordonwoodhull]

@75lb, ugh, really? I thought the links at least worked on Chrome.

Maybe the markdown is just too big, especially with the new jsdoc2md tooling. The new HTML Documentation might be a solution, but it still needs a lot of work - some content is missing due to stuff we don't know how to configure right.

[75lb]

the links do work on Chrome, i'm saying it was awkward to get them working to begin with (i wrote jsdoc2md).

cool, will check out the html docs thanks.

[gordonwoodhull]

Ah, got it! Thanks for the cool tool.

[75lb]

welcome.. i'm about half done on version 2 - it's a total rewrite.. if you have any feedback, now's a good time..

your docs are very nice - comprehensive.. but the first thing i noticed was the massive surface-area of the dc API.. we need a standard solution to make large APIs more digestible.. will look into it.

[gordonwoodhull]

Yes, the docs are pretty unwieldy. The project grew exponentially from a cool demo into a misshapen sort of platform, just because we get so many contributions. It may not be wise to keep everything on one page anyway.

Ah, now this is interesting: since you mentioned it, I was curious if GitHub was breaking the links or if it was the markdown itself. So I temporarily enabled Jekyll on the github.io page, and the formatting is broken, but links totally work!

http://dc-js.github.io/dc.js/docs/api-latest#dc.baseMixin+renderLabel

[75lb]

heh, yes the links will work outside of Github.. the target anchor in the jsdoc2md output looks like:

<a name="ansi-escape-sequences.cursor.down"></a>

but Github modifies it to:

<a name="user-content-module_ansi-escape-sequences.cursor.down"></a>

remarkably, this doesn't break linking functionality in most browsers..

i'm sure dc could be refactored into a more digestible shape (e.g. a "core" module with additional, external extensions available as required).. this would be good for encapsulation and the docs but as usual it's time!

[gordonwoodhull]

I see. Wow. I had no idea you could get away with that.

Well I guess in theory just switching to github.io + Jekyll for the docs is an okay solution, if we fix the formatting. I don't think we get very much from hosting the docs inside the GitHub UI, except for the free style sheet.

Yes, d3 itself is breaking up in a dozen or so modules, so it will make sense for dc.js to do that eventually. I'm kind of stalling for ES6 to actually happen.

And yes, time!

[gordonwoodhull]

That would be one artifact we could stop checking into the main branches, too...

[75lb]

ordinarily, modules ship with an API ref but yeah, each revision of the dc API doc adds 0.25mb to the repo history..

jsdoc2md is scriptable, for example here is a recipe for splitting docs by class.. but it depends on having an effective strategy for breaking up the API..

[mtraynham]

It's such a small world 😄

@75lb Thanks again for the tool! dc is, for the most part, split up by mixin or chart type, so the scripting maybe a huge help in splitting things out. I bet we could find a way to support linking between the files as well. I put together the original PR for dc.js' migration to JSDoc with jsdoc2md, so if you have any other recommendations, I would love to hear it!

It looks like we haven't explored all the options for making the docs a bit simpler. I imagine removing the TOC links (which get duplicated per sub-section) and some of the unnecessary information, such as Kind: instance property of baseMixin would help reduce the size.

[75lb]

@mtraynham thanks, i'm glad you like the tool..

you could split by mixin and link between files, no probs.. jsdoc2md v1 is scriptable but has a stream API which puts some people off (initially it made sense this way to handle the flow of data stdin -> jsdoc -> jsdoc-parse -> dmd -> stdout, but in hindsight it makes scripting more complex, less instant)..

v2 has sync, async and stream APIs but is not quite ready to share.. will get back to you..

yes, you could look into customising dmd to achieve quick wins like removing the Kind: blah line or member-index..

good shout moving to jsdoc.. none of the current doc solutions give me everything i need but jsdoc3 is my preferred option, for now..

[gordonwoodhull]

This really seems to be a crazy github issue, so closing.