Loopback-next: Add @loopback/rest package to API docs

[dhmlau]

From @crandmck in this GH issue:

We also need to update the API docs, specifically we need to add the new package to https://github.com/strongloop-internal/apidocs.strongloop.com/blob/master/ts-repos.json

[crandmck]

Did initial work in https://github.com/strongloop-internal/apidocs.strongloop.com/tree/add-rest-pkg branch. Kevin added https://github.com/strongloop/loopback-next/blob/master/packages/rest/docs.json which is the other requirement.

However, I don’t see the rest pkg docs when I run the site locally…. I’m stumped, because packages/@loopback%[email protected] is there so it’s being downloaded….

[dhmlau]

I'm thinking if it has something to do with how we publish to npmjs.org.
I was trying out a similar changes. Got the same problem as @crandmck. Also, same problem happened for @loopback/authentication.
For @loopback/authentication, 4.0.0-alpha.10 returns empty page, but things are working fine for 4.0.0-alpha.8. For other @loopback packages, they are working fine in all versions.

@kjdelisle, would you be able to shed some light on this?

[crandmck]

Also @bajtos might have some insight, since he often publishes our stuff to npm...

[bajtos]

I checked @loopback/[email protected] by comparing its package files against @loopback/[email protected]. I don't see any difference, both packages have api-docs directory included, and there is no docs.json file in both packages.

Based on https://github.com/strongloop-internal/apidocs.strongloop.com/pull/77, which added lb-next packages to the website, I think we need to add @loopback%2frest to this file: https://github.com/strongloop-internal/apidocs.strongloop.com/blob/master/ts-repos.json

[dhmlau]

@crandmck , i'm thinking we might need to get @mpatsute to have a look. @loopback/authentication has the same problem too, even on the APIDoc strongloop.com: http://apidocs.strongloop.com/@loopback%2fauthentication/v/4.0.0-alpha.10/

[crandmck]

@bajtos I added it to ts-repos.json in the working branch, but the problem still occurs, and as @dhmlau points out, the same thing happens with @loopback/authentication.

I'll see if @mpatsute can help.

[mpatsute]

@dhmlau @crandmck @bajtos . Looks like one of the recent changes (PR: https://github.com/strongloop/loopback-next/pull/594) is causing document generation ("npm run build:apidocs" command) to fail with following errors. Check with @raymondfeng if there is any alternative to the code in PR #594, that will not break document generation. Also, I suggest making document generation run as a part of the CI, so that issues if any that break document generation will be caught by the CI

Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(36)
 Type '"Transient"' is not assignable to type 'BindingScope'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(61)
 Type '"Context"' is not assignable to type 'BindingScope'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(84)
 Type '"Singleton"' is not assignable to type 'BindingScope'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(88)
 Type '"Constant"' is not assignable to type 'BindingType'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(89)
 Type '"DynamicValue"' is not assignable to type 'BindingType'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(90)
 Type '"Class"' is not assignable to type 'BindingType'.
Error: /Users/[email protected]/works/git-code/loopback-next/packages/context/src/binding.ts(91)
 Type '"Provider"' is not assignable to type 'BindingType'.
Could not create project for file: undefined

[crandmck]

Thanks @mpatsute
Definite +1 for adding document generation to CI...
Meantime, lets see if we can fix this asap.

[raymondfeng]

@mpatsute The string enum is introduced by TypeScript 2.4. See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-4.html. Maybe your package has an earlier version of TS.

[raymondfeng]

See https://github.com/strongloop/strong-docs/pull/98

[mpatsute]

Thanks @raymondfeng The doc generation is working fine with the change you made. We can merge the PR!

[dhmlau]

@crandmck , with @raymondfeng 's fix, i believe your branch will be working.

https://github.com/strongloop/loopback-next/issues/622#issuecomment-335952793

[crandmck]

@dhmlau I did npm install -s strong-docs under my apidocs-strongloop.com checkout (my branch), but I still see the same problem. Do I need to do something more? Are you able to see the doc for the missing packages/version?

[raymondfeng]

The strong-docs dependency is declared by https://github.com/strongloop/loopback-next/blob/master/package.json#L29. Running npm build:apidocs will generate the apidocs for loopback-next.

Do you use a global installation of strong-docs for apidocs-strongloop.com? What version of strong-docs are you getting? It should be 1.6.0.

[shimks]

I don't see npm build:apidocs in https://github.com/strongloop/loopback-next/blob/master/package.json. What's the script supposed to run?

[crandmck]

@shimks npm build:apidocs is defined in loopback-next/packages/<pkg-name>/package.json,
e.g. https://github.com/strongloop/loopback-next/blob/master/packages/authentication/package.json#L14

It runs https://github.com/strongloop/loopback-next/blob/master/bin/generate-apidocs.js

[shimks]

@crandmck I was able to verify that the docs will be built correctly in https://github.com/strongloop/loopback-next/tree/master/packages/rest, but not in apidocs-strongloop.com.

[crandmck]

@dhmlau
Should we land https://github.com/strongloop-internal/apidocs.strongloop.com/pull/78 ?
I can't confirm that it fixes the problem, and apparently neither can @shimks but AFAICT it doesn't make anything worse or introduce any new problems, so what have we got to lose?

[dhmlau]

sure.
I thought if we cannot verify the problem is fixed locally, it's gonna work in the public site? Either way, i think it's good to land.

[crandmck]

I thought if we cannot verify the problem is fixed locally

I believe @raymondfeng was able to verify, but I and @shimks were not... so, not clear.

[shimks]

Seems like the application goes to this link to download the docs: http://registry.npmjs.org/@loopback/rest/-/rest-4.0.0-alpha.3.tgz. Considering the html file is in this package, I'm going to fathom a guess that the documentation is manually built somewhere else and then updated to npm. If anyone can shed more light onto this, please do.

[crandmck]

the documentation is manually built somewhere else and then updated to npm. If anyone can shed more light onto this, please do.

The apidocs app should download published tgz packages from npm, then generate the API docs from them using strong-docs.

Since we recently landed https://github.com/strongloop-internal/apidocs.strongloop.com/pull/78, we should be able to view API docs for the rest package in staging: http://apidocs.strongoops.com/ (note strongOOPS.com). However, http://apidocs.strongoops.com/@loopback%2frest/v/4.0.0-alpha.3/ still shows up empty as before, as does http://apidocs.strongoops.com/@loopback%2fauthentication/v/4.0.0-alpha.10/.

This is the behavior I was seeing in my local build. IIUC @raymondfeng was able to view these packages in his local build, but @shimks and I were not able to.... Since the staging site does not show them, it looks like @raymondfeng's experience was an anomaly. So, back to the drawing board...

Why is http://apidocs.strongoops.com/@loopback%2fauthentication/v/4.0.0-alpha.10/ empty but http://apidocs.strongoops.com/@loopback%2fauthentication/v/4.0.0-alpha.8/ is not??
https://www.npmjs.com/package/@loopback/authentication shows 4.0.0-alpha.10 was published a few weeks ago.

[shimks]

From Kevin

Figured out the issue with strong-docs
typedoc uses [email protected] and there's a compiler failure with our code using that version (which is why it can't make docs for rest and authentication)
We use [email protected], so we've probably written code that runs aground on a compiler bug in 2.4.1 which has since been fixed.
There's a PR in typedoc to update to 2.5.3, but I'm not sure how long that will take, since they've stated that they pin their compiler versions to ensure that users have a version of typedoc they can use with their chosen version of typescript

The issue seems to be blocked until https://github.com/TypeStrong/typedoc/pull/626 can be merged

[crandmck]

Thanks for figuring it out @kjdelisle.

@dhmlau I guess we should see what they TypeDoc folks say...
Should we have a workaround ready (or at least determine if possible) if they don't reply soon or if they are not going to land that PR soon...?

[dhmlau]

@crandmck, what would be the workaround?
From what @shimks described, it seems like the docs can actually be generated when running the strong docs command at the package level. Are you suggesting the workaround be putting the generated content up to the public site, instead of having it generated on the fly?

[crandmck]

IIUC, Raymond has implemented a workaround in https://github.com/strongloop/loopback-next/pull/674

[dhmlau]

I believe this is already fixed. Closing it.