Loopback-next: apidocs links are broken and anchors are non-descriptive
Description / Steps to reproduce / Feature proposal
After we moved loopback4 apidocs main page to this repo, the base link for it has been changed which invalidates our existing apidocs links in the docs.
Additionally, some of the links with anchors to them are non-descriptive and seem easily subject to change (e.g. link to apidocs for Context's get is http://apidocs.loopback.io/@loopback%2fdocs/context.html#216; the anchor is not #get). We should either address this directly by adjusting strong-docs, or have a standard procedure for linking to code/apidocs so that they're not prone to breaking.
Acceptance Criteria
- fix all broken apidocs links
- follow up with an issue for making the anchor generation more maintainable
_See Reporting Issues for more tips on writing good issues_
shimks
All 11 comments
sounds like a bug. Do we know enough to put down acceptance criteria? or should just put it in the backlog?
dhmlau
on 12 Jun 2018
There's two parts to this issue: fixing the links and finding a way to keep the links maintainable. Fixing the links themselves are straightforward enough, but making the links maintainable is a strong-docs issue (I think). @raymondfeng is there a limit to strong-docs on making this change not feasible to implement?
shimks
on 12 Jun 2018
In discussion with @raymondfeng @bajtos , fixing the links should be part of DP3.
For the longer term solution, we need to have a qualified names to make the function and properties unique. This should be part of Core-GA, if we cannot make it for DP3.
dhmlau
on 12 Jun 2018
Rejecting because @virkt25 raised the issue of hotfix being very short term since the links are volatile and may need numerous updates.
b-admike
on 19 Jun 2018
In JavaScript-based documentation (think LB 2.x/3.x), we are using descriptive anchors that don't change over time, for example http://apidocs.loopback.io/loopback/#app-listen for app.listen().
IMO, we should use a similar algorithm to build anchors for TypeScript-based documentation too. For Context.prototype.get(), I would expect an anchor like #context-get, not the current #216.
To me, that's the most important change/fix to do as part of this issue. The sooner we make that change, the less broken links we will have to update.
bajtos
on 21 Jun 2018
- make sure the generated id is unique
jannyHou
on 26 Jun 2018
[email protected] contains the fix to set anchor id with qualified name. For example:
- context.html#Context.get
- context.html#inject.getter
raymondfeng
on 27 Jun 2018
After we moved loopback4 apidocs main page to this repo, the base link for it has been changed which invalidates our existing apidocs links in the docs.
@shimks Please elaborate the issue ^^^.
raymondfeng
on 27 Jun 2018
An example of link to our apidocs in loopback.io: http://apidocs.loopback.io/@loopback%2fopenapi-v3/#29
The correct link: http://apidocs.loopback.io/@loopback%2fdocs/openapi-v3.html#233
We need to update the docs/READMEs so that these correctly point to the current apidocs.
shimks
on 27 Jun 2018
I searched through loopback-next but didn't find such links. Can you tell which file has the wrong link?
raymondfeng
on 27 Jun 2018
I took the example from Decorators.md. We might need to search for apidocs in our repository to make sure that all of the apidocs links are valid.
shimks
on 27 Jun 2018
Related issues
shahulhameedp
路
3Comments
rexliu0715
路
3Comments
kesavkolla
路
3Comments
acrodrig
路
3Comments
cloudwheels
路
3Comments
Most helpful comment
In JavaScript-based documentation (think LB 2.x/3.x), we are using descriptive anchors that don't change over time, for example http://apidocs.loopback.io/loopback/#app-listen for
app.listen().IMO, we should use a similar algorithm to build anchors for TypeScript-based documentation too. For
Context.prototype.get(), I would expect an anchor like#context-get, not the current#216.To me, that's the most important change/fix to do as part of this issue. The sooner we make that change, the less broken links we will have to update.