Linking to API docs.

[nene]

We want to link at the Ext JS and Touch API docs. Previously @link tag has worked well:

{@link Ext.data.Store#add}

But this kind of link needs to have a context of whether to link to Touch or Ext API docs.

One possibility is to define the context of the @link elements for the whole guide. Perhaps inside the JSON config file. Or at the level of the whole docs set as a command line option.

Another way would be to introduce some kind of syntax to specify the context of the link:

{@link touch:Ext.data.Store#add}

This will be useful for guides that need to refer to both Ext and Touch. Architect being the prominent example here.

[branflake2267]

When do you think this will get implemented? Currently I'm adding todos into the docs. :)

[branflake2267]

I'm going to try and provide relative links to the other guides. So no hurry. :)

[nene]

So, currently you can use the @link tag to refer to classes:

{@link Ext.SomeClass}

Then you can pass in --link-url option, like:

guider --link-url=http://docs.sencha.com/ext-js/4-2/

And the above link gets transformed into:

http://docs.sencha.com/ext-js/4-2/#!/api/Ext.SomeClass

I'll make it work for class members shortly. The syntax will then be:

{@link Ext.SomeClass#cfg-someName}
{@link Ext.SomeClass#property-someName}
{@link Ext.SomeClass#method-someName}
{@link Ext.SomeClass#event-someName}

Or at least, that syntax will surely work, as I need to keep it compatible with JSDuck.

[branflake2267]

I guess it doesn't make sense yet, b/c I'm working with guides and not classes. I suppose maybe a conversion is in the works?

[branflake2267]

It makes sense appending the url, b/c what happens currently. Sounds good.

[nene]

Yeah. Linking to guides is a different issue. I think I'll stick with plain markdown links. At least that's how the guides are currently linked together, so I need to support that.

[branflake2267]

What I'm trying to do, I wonder if you could append replace the tilda?

<a href="~/ui/data/propertyaccess/PropertyAccess.html">PropertyAccess&lt;M&gt;</a>

[nene]

Replace the tilde with what?

I suggest you just use relative URL.

[branflake2267]

The relative url won't work b/c the guide that I want to link to sits in another deep directory. :) I was thinking append the --link-url given. I don't mind linking to another document in the format above, but I'm not sure how that lays out yet in the guider system. :)

[nene]

Hmm... yeah... you have a really-really-really deeply nested dir structure. Hadn't thought of that...

[branflake2267]

:) yeah

[branflake2267]

Have you decided on a internal guides linking format?

Would it be possible to do something like one of these?

[article](path/to/Readme.md)
[article](~/path/to/Readme.md)
<a href="path/to/Readme.md">article</a>
<a href="~/path/to/Readme.md">article</a>

[nene]

I still need to think about this whole links-between-guides thing. I've had lots of other stuff on my shoulders, and not nearly as much time for this little project as I would have liked to.

[nene]

OK. So now one can write links to guides in JSDuck-compatible way:

[article](#!/guide/path/to/guide.md)

The important bit is to prefix the link with #!/guide/ and one can then sensibly reference the guides relative to root dir.

Not the best solution, but as I need to transition docs from JSDuck to guider, I need to support these old style links.

Moving forward, I want to add something better than this, but this hopefully solves the most of the pain for now.

[branflake2267]

Sounds good to me. I don't mind as I have an option to move forward. :) Good job!