PolymerElements
Would like to link to a different doc page
I would like to refer to a the docs for a different element (potentially in the same repository) from a doc page.
Is there a reason not to just use full markdown links?
On Wed, May 27, 2015, 9:32 AM Aleksandar Totic [email protected] wrote:
Assigned #34 https://github.com/PolymerElements/iron-doc-viewer/issues/34 to @mbleigh https://github.com/mbleigh.
— Reply to this email directly or view it on GitHub https://github.com/PolymerElements/iron-doc-viewer/issues/34#event-315102014 .
How do we refer to docs for a different element? Will there be a canonical url somewhere on polymer-project? Even then, there are multiple versions.....
On Wed, May 27, 2015 at 9:55 AM, Michael Bleigh [email protected] wrote:
Is there a reason not to just use full markdown links?
On Wed, May 27, 2015, 9:32 AM Aleksandar Totic [email protected] wrote:
Assigned #34 https://github.com/PolymerElements/iron-doc-viewer/issues/34 to @mbleigh https://github.com/mbleigh.
— Reply to this email directly or view it on GitHub < https://github.com/PolymerElements/iron-doc-viewer/issues/34#event-315102014
.
— Reply to this email directly or view it on GitHub https://github.com/PolymerElements/iron-doc-viewer/issues/34#issuecomment-105992632 .
Yes, there will be canonical urls. I think versioning is something to worry about down the road
On Wed, May 27, 2015, 11:01 AM Aleksandar Totic [email protected] wrote:
How do we refer to docs for a different element? Will there be a canonical url somewhere on polymer-project? Even then, there are multiple versions.....
On Wed, May 27, 2015 at 9:55 AM, Michael Bleigh [email protected] wrote:
Is there a reason not to just use full markdown links?
On Wed, May 27, 2015, 9:32 AM Aleksandar Totic <[email protected]
wrote:
Assigned #34 https://github.com/PolymerElements/iron-doc-viewer/issues/34 to @mbleigh https://github.com/mbleigh.
— Reply to this email directly or view it on GitHub <
https://github.com/PolymerElements/iron-doc-viewer/issues/34#event-315102014
.
— Reply to this email directly or view it on GitHub < https://github.com/PolymerElements/iron-doc-viewer/issues/34#issuecomment-105992632
.
— Reply to this email directly or view it on GitHub https://github.com/PolymerElements/iron-doc-viewer/issues/34#issuecomment-106014618 .
See also #9. I think the correct solution from a tool point of view is to allow the author to link to ArbitraryElement with some specific syntax, like ArbitraryElement or {@link ArbitraryElement} and have hydrolysis/a doc merger script/some other tool resolve those links when you generate a batch of docs.
I think this already works with markdown, both with absolute and relative paths (to the current element). See https://github.com/PolymerElements/iron-icon/blob/master/iron-icon.html#L55 for an example.
This kinda works now, but it works more or less by accident. It works because in the catalog, each element has a path like elements/foo-element... Provided that the element is the main element in a package. (You can't, for example, link to [paper-textarea](paper-textarea) and have it work, because the URL for that is elements/paper-input?active=paper-textarea.
You can embed the catalog-specific URL in your doc, but then you can't serve it statically, where the URL will be something like:
my-elements.html#iron-icons
And if you want to link to a specific property on a specific element, getouttatown.
So, my napkin-sketch of how this could work:
- hydrolysis resolves {@link iron-input} or {@link iron-input#property-type} to a reference to a particular element or member and inserts (something) in the markup.
Or:
1a. We insert the (something) directly in the markup, in the form of, say, a special URL:
[iron-input](api:iron-input)
-
iron-doc-viewerintercepts anchor clicks for api: URLs and fires an event. -
iron-component-pageor the router of choice receives that event, translates it to the URL scheme in use, and navigates to it.
I'm fine with this being a low priority for now but I do think we need to solve it eventually. Probably blocked by: https://github.com/PolymerElements/iron-component-page/issues/57