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.
This commit is contained in:
Jesse Rosenberger
2018-01-29 17:09:43 +02:00
parent 540dc00230
commit 06c90caf8a

View File

@@ -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: