test: build loopback.io submodule to ensure it works with docs

[virkt25]

loopback.io has broken multiple times because of formatting errors in @loopback/docs as jekyll is not able to build the site with invalid syntax in markdown files.

This PR introduces loopback.io as a submodule of loopback-next and a Travis Stage is added that attempts to build the loopback.io site. If the build fails, the CI will fail and we can look at the error.

Travis Stages will look as follows: https://travis-ci.org/strongloop/loopback-next/builds/365796133?utm_source=github_status&utm_medium=notification

This also allows us to locally test the changes in docs against a local copy of loopback.io as the bootstrapped repo will link to the local copy of @loopback/docs. You must initialize the loopback.io submodule by running the following command:

git submodule update --init --recursive

Then in loopback.io you must run the fetch-readmes script and use npm run start to start the site.

---

CON: Travis CI Builds will take an additional ~3-5 minutes for the new stage.

If we want to go ahead with this PR, the following needs to take place (In loopback.io):

• loopback.io/packagae.json devDependency on @loopback/docs needs to be changed from latest to * as lerna doesn't play nice with latest (it installs it from npm instead of local). * will install the latest published version from npm in production and link to local copy in loopback-next.
• loopback.io/update-lb4-docs.js Remove the lines that delete the sidebar folder from source (not sure why we are even doing this ... but in the mono-repo after bootstrapping to local it means removing it from our @loopback/docs package.

Checklist

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

[shimks]

You must initialize the loopback.io submodule by running the following command: git submodule update --init --recursive

Is there a way to have this done automatically?

[virkt25]

Is there a way to have this done automatically?

Not that I'm aware of ... but we can write some scripts to automate this locally. (You only need to do this if you want to run the loopback.io submodule locally).

[b-admike]

This is great! I've seen how many times we had to go fix up loopback.io after small syntax issues were introduced from our @loopback/docs. The overhead of ~3-5mins sounds reasonable for the peace of mind we will get from this extra stage. If we do decide to go with this, I suggest you write some instructions on how to test locally as you have described in the this PR.

[b-admike]

it knows to run npm install and npm test automatically in this stage right?

[virkt25]

See #1254 for the new PR. npm test is not run in the loopback.io (that's what the test stage is for). install happens as part of bootstrap.

[raymondfeng]

Have you evaluated git subtree? I know git submodule is big trouble maker and we should avoid it as much as possible.

[raymondfeng]

Maybe we just have to find a simple way to test loopback-next/docs with loopback.io.

[b-admike]

@raymondfeng that reminds me, when I was spiking on moving docs, I remember not pursuing git submodules because of how loopback.io and loopback-next are structured and because of how big the monorepo was (I was trying to make loopback-next a submodule of loopback.io), but didn't look further. It'd definitely help to know the drawbacks of using it.

[virkt25]

@raymondfeng Have a look at #1254

I had not evaluated git subtree since I wasn't aware that was a thing. Anyways, I don't think it can get simpler than the new PR which just clones loopback.io for testing.

[virkt25]

Closing this in favor of #1254