Spike: Move documentation to monorepo

[bajtos]

It would be great to have the documentation for loopback-next in the monorepo, so that we can keep documentation changes together with all other changes (runtime, CLI templates, API docs, etc.).

Spike Goals

Assuming the monorepo has a docs package:

• Where will it live?
• What technologies will it use?
• How will we update it?
• Can we make it a self-contained testable site? (like the current loopback.io's local jekyll run)

[bajtos]

I think the important (and possibly difficult) requirement is that we want a single place aggregating documentation for all major versions of LoopBack (2.x, 3.x, 4.x and beyond). If we keep the docs in the monorepo, then we need a solution that can fetch markdown files from different monorepo branches (master, 4.x, etc.). I am not sure if the current approach leveraging GitHub pages and static-site generator supports such workflow. Maybe if we switched from GitHub pages to Netlify then we could leverage their Continuous Deployment (docs)?

[raymondfeng]

There is preliminary support to pull in markdown files from git/npm into loopback.io repo: https://github.com/strongloop/loopback.io/blob/gh-pages/update-v4-readmes.sh. It supports different branches.

One thing missing is to relink markdown files if they reference each other.

[b-admike]

Problem Description

It would be great to have the documentation for loopback-next in the monorepo,
so that we can keep documentation changes together with all other changes
(runtime, CLI templates, API docs, etc.).

Current Approach Overview

Aggregated documentation for LoopBack 2.x, 3.x, and 4.x lives in loopback.io
module. Each release has static pages which have info on different features as
.md files. Changes to readmes from the different repositories associated with
different releases are picked up by bash
scripts
and commited to loopback.io as part of Jenkins' builds as slnode. Any
documentation update for LoopBack requires a PR to be submitted in loopback.io
for the specific feauture/fix it aims to address. To learn more, here it how it
works.

Assumptions/considerations

• @loopback/docs to house static pages from loopback.io pertaining to
  LoopBack4 content.
• source of truth to be @loopback/docs, so documentation updates should not be
  made in loopback.io. That is, updates go only one way; from @loopback/docs
  to loopback.io.
• Use master branch in loopback-next as the current release version. Thus,
  when we release LoopBack v5, docs for LoopBack4 will be contained in 4.x
  branch

Proposal

• [EDIT: not part of revised proposal] Strip out minimal needed js/css/html etc. files to run a website for lb4 docs
  from loopback.io. Landing page will be the current
  http://loopback.io/doc/en/lb4/. This is going to be used for testing changes
  to the docs in loopback-next before being promoted to loopback.io. Tests
  will be local jekyll runs as they currently are run for loopback.io. We
  could also run them as part of Netlify's Continuous
  Deployment feature (it's
  included under their free offering!). Their support for
  Webhooks would allow us to bake it
  into our pipeline. We can also use http2live, which is an open source static web site
  hosting service which comes in a module and invoked using CLI. It can run as
  part of CI, but discarding of stale instances would be manual. Another
  alternative is surge, but it does not offer a lot for
  free, so would need to pay $13/month for things like Unlimited Publishing.
• Create a new @loopback/docs package in loopback-next
  • top level -> same as
    pages/en/lb4
    in loopback.io
  • the rest of the package will use
    get-md-docs and filter out
    certain .md files such as those in test
    folders
    and mimic monorepo structure
• Create a script (or modify existing ones) to pull changes from
  @loopback/docs into loopback.io

Spike Questions

1. Where will it live?
   A new package @loopback/docs as part of loopback-next monorepo.
2. What technologies will it use?
   Current stack used at loopback.io (Jekyll, Liquid, etc.), get-md-docs
   module created by @kjdelisle, possibly Netlify or http2live.
3. How will we update it?
   We will update it as part of our feature, fix, etc. PR in loopback-next.
4. Can we make it a self-contained testable site? (like the current
   loopback.io's local jekyll run)
   Yes, it's possible to do so as outlined in the Proposal.