build(docs): add scripts for fast previews of LB4 doc changes

Add a script `docs/bin/build-preview-site.sh` that creates a subset
of loopback.io site with just enough content to support fast previews
of LB4 documentation.

Add monorepo-level npm scripts to simplify usage of the new build
script.

Usage:

1. Run the script to create a new Jekyll site in `docs/_preview` dir:

    $ npm run docs:prepare

2. Follow the instructions printed by the script to start Jekyll:

    $ npm run docs:start

3. View the documentation.

4. Make changes to documentation files in `docs/site`.

5. Restart Jekyll (stop the running process and go to step 2).

The good parts:

- Initial build of LB4-only docs takes about 6 seconds.
  (Compare to ~4 minutes for the entire docs site!)

- Incremental rebuild after changing a single file takes less
  than a second.

Downsides:

- Watch mode does not work. AFAICT, Jekyll cannot watch
  symlinked files stored outside of `source` directory.

Signed-off-by: Miroslav Bajtoš <[email protected]>

Author: bajtos

.eslintignore

@@ -3,3 +3,5 @@ dist/
 coverage/
 /sandbox
 **/*.d.ts
+/docs/_preview
+/docs/_loopback.io

.gitignore

@@ -32,3 +32,6 @@ packages/tsdocs/fixtures/monorepo/packages/pkg1/docs
 # ESLint cache
 .eslintcache
 
+# Docs preview
+docs/_loopback.io/
+docs/_preview/

.prettierignore

@@ -2,6 +2,8 @@
 /coverage
 /docs/apidocs
 /docs/site/apidocs
+/docs/_loopback.io/
+/docs/_preview/
 packages/cli/generators/*/templates
 packages/cli/snapshots/
 packages/tsdocs/fixtures/monorepo/docs

docs/bin/build-jekyll-preview-config.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+const src = process.argv[2];
+const dest = process.argv[3] || src;
+
+if (!src) {
+  console.log(`
+Missing required argument: path to original Jekyll config');
+
+Usage:
+
+  node %s <source _config.yml> [dest path]', process.argv[1]);
+
+`);
+  process.exit(1);
+}
+
+console.log('Reading Jekyll config from %s', src);
+const config = yaml.safeLoad(fs.readFileSync(src, 'utf8'));
+
+config.sidebars = ['lb4_sidebar'];
+config.defaults[0].values.sidebar = 'lb4_sidebar';
+config.plugins = config.plugins.filter(p => p !== 'jekyll-sitemap');
+
+console.log('Writing Jekyll config to %s', dest);
+fs.writeFileSync(dest, yaml.dump(config), 'utf8');

docs/bin/build-preview-site.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# This scripts builds a small Jekyll site to preview LB4 documentation changes.
+# The idea is to get as close to `strongloop/loopback.io` configuration as
+# possible, while removing as many non-LB4 pages as possible.
+
+# Set `-e` so that non-zero exit code from any step will be honored
+set -e
+
+# Make sure we use the correct repo root dir
+DIR=`dirname $0`
+DOCS_ROOT=$DIR/..
+REPO_ROOT=$DIR/../..
+
+pushd $DOCS_ROOT > /dev/null
+
+SOURCE_DIR=_loopback.io
+if [ ! -d $SOURCE_DIR ]; then
+  echo "Shadow cloning the strongloop/loopback.io github repo"
+  git clone --depth 1 https://github.com/strongloop/loopback.io.git $SOURCE_DIR
+else
+  echo "Found existing loopback.io clone, pulling latest changes"
+  (cd $SOURCE_DIR && git pull)
+fi
+
+echo "Installing setup dependencies"
+npm install --no-save js-yaml
+
+JEKYLL_DIR=_preview
+rm -rf $JEKYLL_DIR
+mkdir $JEKYLL_DIR
+
+node bin/build-jekyll-preview-config $SOURCE_DIR/_config.yml $JEKYLL_DIR/_config.yml
+
+echo "Copying LB4 readmes"
+node bin/copy-readmes
+
+echo "Copyping Gemfile, index.html and data files"
+rm -rf $JEKYLL_DIR/{_data,_includes,_layouts}
+cp -r $SOURCE_DIR/Gemfile* $JEKYLL_DIR/
+cp -r $SOURCE_DIR/index.html $JEKYLL_DIR/
+cp -r $SOURCE_DIR/_data $JEKYLL_DIR/
+cp -r $SOURCE_DIR/_includes $JEKYLL_DIR/
+cp -r $SOURCE_DIR/_layouts $JEKYLL_DIR/
+
+echo "Copying static assets"
+cp -r $SOURCE_DIR/{css,images,dist,js,fonts} $JEKYLL_DIR/
+rm -rf $JEKYLL_DIR/doc
+mkdir -p $JEKYLL_DIR/doc
+cp -r $SOURCE_DIR/doc/index.md $JEKYLL_DIR/doc
+
+echo "Setting up LB4 doc pages",
+rm -rf $JEKYLL_DIR/pages
+ln -s $PWD/site $JEKYLL_DIR/pages
+
+echo "Setting up sidebar(s)"
+rm -rf $JEKYLL_DIR/_data/sidebars
+ln -s $PWD/site/sidebars $JEKYLL_DIR/_data/sidebars
+
+echo "Installing Ruby dependencies"
+(cd $JEKYLL_DIR && bundle install)
+
+echo "Done. Run the following command to start the site:"
+echo ""
+echo "  npm run docs:start"
+echo ""
+echo "NOTE: Watch mode is not supported yet."

docs/site/DEVELOPING.md

@@ -18,6 +18,7 @@ See [Monorepo overview](./MONOREPO.md) for a list of all packages.
 - [Coding rules](#coding-rules)
 - [Working with dependencies](#working-with-dependencies)
 - [File naming convention](#file-naming-convention)
+- [Documentation](#documentation)
 - [API documentation](#api-documentation)
 - [Commit message guidelines](#commit-message-guidelines)
 - [Making breaking changes](#making-breaking-changes)
@@ -213,6 +214,85 @@ src/__tests__/integration/user.controller.integration.ts
 src/__tests__/unit/application.unit.ts
 ```
 
+## Documentation
+
+The documentation available at [http://loopback.io/doc/en/lb4](loopback.io)
+website is powered by Jekyll and Markdown. The main site content and Jekyll
+configuration is hosted in
+[loopback.io](https://github.com/strongloop/loopback.io) repository on GitHub.
+
+LoopBack 4 documentation is hosted inside this monorepo in the
+[/docs](https://github.com/strongloop/loopback-next/tree/master/docs) directory.
+This allows us to change both implementation and the documentation in a single
+pull request.
+
+### Publishing changes
+
+To prevent documentation changes going live before the changes in the
+implementation have been published, we have set up the following build pipeline:
+
+1. As part of the LoopBack 4 release process, the content of `docs` directory is
+   bundled and published to npmjs.org as `@loopback/docs` package.
+
+2. We have a CI/CD pipeline to pick a new `@loopback/docs` version and commit
+   the updated content to `loopback.io` repository. The job is run every night.
+
+### Previewing loopback-next docs only
+
+> This workflow is not available on Windows (unless you use Windows Subsystem
+> for Linux).
+
+When making change to our documentation, it's useful to quickly check how is the
+updated markdown content going to be rendered on the website. To make this flow
+as fast as possible, we have a script to prepare a subset of our website with
+LoopBack 4 content only. This provides the fastest feedback loop possible, at
+the cost of occasional breakage when the script is not updated to accommodate
+changes made in the `loopback.io` repository.
+
+As the initial setup, run the following command once, before you start making
+documentation changes:
+
+```sh
+$ npm run docs:prepare
+```
+
+This command will create `docs/_preview` directory with a Jekyll project and
+configure symlinks to let Jekyll automatically pick any changes made in
+`docs/site` files.
+
+Whenever you want to (re)render documentation, just (re)start the following
+command:
+
+```sh
+$ npm run docs:start
+```
+
+The first run will be slightly longer because Jekyll has to render all doc
+pages. Subsequent runs should be very fast because only changed files are
+re-rendered thanks to Jekyll `incremental` mode.
+
+### Viewing the full website
+
+> This workflow is not available on Windows (unless you use Windows Subsystem
+> for Linux).
+
+It is also possible to verify the full build setup, including validation of
+Markdown & Jekyll (liquid) syntax.
+
+Run the following command to clone `loopback.io` repository to
+`sandbox/loopback.io` and get the current documentation from loopback-next
+copied in the right places in the Jekyll project:
+
+```sh
+npm run build:site
+```
+
+You can also run the documentation tests exactly as our CI pipeline does:
+
+```sh
+npm run verify:docs
+```
+
 ## API Documentation
 
 We use

package.json

@@ -59,6 +59,8 @@
     "test:ci": "node packages/build/bin/run-nyc npm run mocha --scripts-prepend-node-path",
     "verify:docs": "npm run build:site -- --verify",
     "build:site": "./bin/build-docs-site.sh",
+    "docs:prepare": "./docs/bin/build-preview-site.sh",
+    "docs:start": "cd docs/_preview && bundle exec jekyll serve --no-w --i",
     "mocha": "node packages/build/bin/run-mocha \"packages/*/dist/__tests__/**/*.js\" \"extensions/*/dist/__tests__/**/*.js\" \"examples/*/dist/__tests__/**/*.js\" \"packages/cli/test/**/*.js\" \"packages/build/test/*/*.js\"",
     "posttest": "npm run lint"
   },