From 06c90caf8a0deb31e4e49d66893e22914f39bcd3 Mon Sep 17 00:00:00 2001
From: Jesse Rosenberger <git@jro.cc>
Date: Mon, 29 Jan 2018 17:09:43 +0200
Subject: [PATCH] Attempt to generate "docs" during CircleCI tests.

There have been a number of occasions where I have gone to bump the
Meteor docs to the next major version, only to find that the docs
deployment (which occurs in a separate repository; found at
https://github.com/meteor/docs) fails due to code-refactoring which has
taken place in its submodule (`code`, which is this Meteor codebase).

In order to provide early warning when a JSDoc declaration in the Meteor
code is going to (eventually) break the docs deployment which occurs in
a separate repository (https://github.com/meteor/docs), this commit
introduces a simple checkout and doc generation, in the same manner as
the docs would in its own repository, within the CircleCI workflow.

It's been configured in a way where it will not stop the normal Meteor
test-suite from running, however it will show a separate indicator on
GitHub pull-requests as to whether the generation of docs was successful
or not.
---
 .circleci/config.yml | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 34c54df45d..1bae59a2ab 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -456,10 +456,50 @@ jobs:
       - store_artifacts:
           path: /tmp/memuse.txt
 
+  # Test the JSDoc declarations which live within this codebase against the
+  # Meteor Docs (https://github.com/meteor/docs) repository, where they'll
+  # eventually be consumed.  This test aims to provide an early warning of
+  # potentially breaking changes, so they aren't discovered when the docs are
+  # next updated, which generally occurs during major Meteor version releases
+  # (for example, 1.4 to 1.5, 1.5 to 1.6).
+  Docs:
+    docker:
+      # This Node version should match that in the meteor/docs CircleCI config.
+      - image: circleci/node:8
+    environment:
+      CHECKOUT_METEOR_DOCS: /home/circleci/test_docs
+    steps:
+      - run:
+          name: Cloning "meteor/docs" Repository's "master" branch
+          command: |
+            git clone https://github.com/meteor/docs.git ${CHECKOUT_METEOR_DOCS}
+      # The "docs" repository normally brings in the Meteor code as a Git
+      # submodule checked out into the "code" directory.  As the goal of this
+      # test is to run it against the _current_ repository's code, we'll move
+      # the "code" directory out of the way and move the checkout (of meteor)
+      # into that directory, rather than the default $CIRCLE_WORKING_DIRECTORY.
+      - checkout
+      - run:
+          name: Move Meteor checkout into docs repository's "code" directory
+          command: |
+            rmdir "${CHECKOUT_METEOR_DOCS}/code"
+            # $CIRCLE_WORKING_DIRECTORY uses a tilde, so expand it to $HOME.
+            mv "${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}" \
+              "${CHECKOUT_METEOR_DOCS}/code"
+      # Run almost the same steps the meteor/docs repository runs, minus deploy.
+      - run:
+          name: Generating Meteor documentation for JSDoc testing
+          command: |
+            cd ${CHECKOUT_METEOR_DOCS}
+            npm install
+            npm run predeploy
+            npx hexo generate
+
 workflows:
   version: 2
   Build and Test:
     jobs:
+      - Docs
       - Get Ready
       - Group 0:
           requires: