build: Build docs after packaging (#520)

Use the standard "sphinx" jsii target to produce
sphinx documentation during "package", so all .rst
files will end up under "pack/sphinx".

Then, convert the docs directory from "packages/aws-cdk-docs" to just
"docs", and not it's not an npm module anymore. It will collect the
reference .rst from pack/sphinx and produce the output to pack/docs.

Docs are now built outside of the normal build process, which also allows
us to perform builds in node.js-only systems like Travis.ci

It also improves performance of bootstrapping a repo.

Delete the publish-docs.sh and publish-npm.sh scripts - they are now part
of our CI/CD repository.

For non-jsii modules, modified cdk-package to delete the target before
moving the tarball in there.

* pkglint: allow expected JSON to be a non-primitive (always return string)

build-docs.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+
+# render docs to docs/dist
+(cd docs && ./build-docs.sh)
+
+# deploy output to 'pack/docs'
+rm -fr pack/docs
+mkdir pack/docs
+rsync -av docs/dist/ pack/docs/

buildspec.yaml

@@ -10,6 +10,7 @@ phases:
   post_build:
     commands:
       - "[ -f .BUILD_COMPLETED ] && /bin/bash ./pack.sh"
+      - "[ -f .BUILD_COMPLETED ] && /bin/bash ./build-docs.sh"
       - "[ -f .BUILD_COMPLETED ] && /bin/bash ./bundle.sh"
 artifacts:
   files:

create-missing-libraries.sh

@@ -130,6 +130,6 @@ EOM
 
         git add packages/${P}
 
-        echo "✅ Have fun with your new package ${P} (⚠️ don't forget to add it to 'aws-cdk-all')"
+        echo "✅ Have fun with your new package ${P}"
     fi
 done

packages/aws-cdk-docs/build-docs.sh → docs/build-docs.sh

@@ -16,7 +16,8 @@ export PATH=${PYTHON_DEPS}/bin:$PATH
 #----------------------------------------------------------------------
 # CONFIG
 staging=".staging"
-output="dist/docs"
+output="dist"
+refsrc="../pack/sphinx"
 refdocs="refs"
 refdocsdir="${staging}/${refdocs}"
 refs_index="${staging}/reference.rst"
@@ -36,10 +37,15 @@ echo "Staging Sphinx doc site under ${staging}"
 mkdir -p ${staging}
 rsync -av src/ ${staging}
 
-for p in $(find-jsii-packages); do
-    echo "Generating reference docs for $p to ${staging}/${refdocs}"
-    jsii-pacmak -t sphinx --outdir ${refdocsdir} $p
-done
+echo "Copying generated reference documentation..."
+if [ ! -d "${refsrc}" ]; then
+    echo "Cannot find ${refsrc} in the root directory of this repo"
+    echo "Did you run ./pack.sh?"
+    exit 1
+fi
+
+rm -fr ${refdocsdir}/
+rsync -av ${refsrc}/ ${refdocsdir}/
 
 echo "Generating reference docs toctree under ${refs_index}..."
 cat ${refs_index}.template > ${refs_index}

packages/aws-cdk-docs/src/_includes.txt → docs/src/_includes.txt

@@ -1,51 +1,51 @@
-.. project-specific includes for this project.
-
-.. |cdk| replace:: AWS CDK
-.. |cdk-long| replace:: AWS Cloud Development Kit
-.. |toolkit| replace:: |cdk| Toolkit
-
-.. |cx| replace:: cdk
-.. |cx-bold| replace:: **cdk**
-.. |cx-code| replace:: :code:`cdk`
-.. |cx-deploy-bold| replace:: **cdk deploy**
-.. |cx-synth-bold| replace:: **cdk synth**
-.. |cx-synth-code| replace:: :code:`cdk synth`
-
-.. |cx-json| replace:: *cdk.json*
-
-.. |at-aws-cdk| replace:: **@aws-cdk/**
-.. |xxxx| replace:: *xxxx*
-.. |xxxx-scope| replace:: |at-aws-cdk| |xxxx|
-
-.. |construct-class| replace:: :py:class:`Construct <@aws-cdk/cdk.Construct>`
-.. |app-construct| replace:: :py:class:`Stack <@aws-cdk/cdk.Stack>`
-.. |app-class| replace:: :py:class:`App <@aws-cdk/cdk.App>`
-.. |this| replace:: **this**
-.. |parent| replace:: **parent**
-.. |stack| replace:: :py:class:`Stack <@aws-cdk/cdk.Stack>`
-.. |stack-class| replace:: |stack|
-.. |stack-construct| replace:: |stack|
-.. |storagelayer| replace:: *StorageLayer*
-.. |storagelayer-construct| replace:: |storagelayer|
-
-.. |resource-construct| replace:: *Resource*
-
-.. |aws-home| replace:: https://aws.amazon.com
-
-.. Installation entities
-
-.. |npm-package| replace:: aws-cdk-tools
-.. |nuget-package| replace:: aws-cdk
-.. |maven-id| replace:: aws-cdk
-.. |git-repo| replace:: https://github.com/awslabs/aws-cdk
-.. |npm-cmd| replace:: npm
-
-.. Construct levels
-
-.. |l1| replace:: CloudFormation Resource
-.. |l2| replace:: AWS Construct Library
-.. |l3| replace:: Purpose-built Library
-
-.. So back-to-back entities have a space between them
-
-.. |space| unicode:: 0x20
+.. project-specific includes for this project.
+
+.. |cdk| replace:: AWS CDK
+.. |cdk-long| replace:: AWS Cloud Development Kit
+.. |toolkit| replace:: |cdk| Toolkit
+
+.. |cx| replace:: cdk
+.. |cx-bold| replace:: **cdk**
+.. |cx-code| replace:: :code:`cdk`
+.. |cx-deploy-bold| replace:: **cdk deploy**
+.. |cx-synth-bold| replace:: **cdk synth**
+.. |cx-synth-code| replace:: :code:`cdk synth`
+
+.. |cx-json| replace:: *cdk.json*
+
+.. |at-aws-cdk| replace:: **@aws-cdk/**
+.. |xxxx| replace:: *xxxx*
+.. |xxxx-scope| replace:: |at-aws-cdk| |xxxx|
+
+.. |construct-class| replace:: :py:class:`Construct <@aws-cdk/cdk.Construct>`
+.. |app-construct| replace:: :py:class:`Stack <@aws-cdk/cdk.Stack>`
+.. |app-class| replace:: :py:class:`App <@aws-cdk/cdk.App>`
+.. |this| replace:: **this**
+.. |parent| replace:: **parent**
+.. |stack| replace:: :py:class:`Stack <@aws-cdk/cdk.Stack>`
+.. |stack-class| replace:: |stack|
+.. |stack-construct| replace:: |stack|
+.. |storagelayer| replace:: *StorageLayer*
+.. |storagelayer-construct| replace:: |storagelayer|
+
+.. |resource-construct| replace:: *Resource*
+
+.. |aws-home| replace:: https://aws.amazon.com
+
+.. Installation entities
+
+.. |npm-package| replace:: aws-cdk-tools
+.. |nuget-package| replace:: aws-cdk
+.. |maven-id| replace:: aws-cdk
+.. |git-repo| replace:: https://github.com/awslabs/aws-cdk
+.. |npm-cmd| replace:: npm
+
+.. Construct levels
+
+.. |l1| replace:: CloudFormation Resource
+.. |l2| replace:: AWS Construct Library
+.. |l3| replace:: Purpose-built Library
+
+.. So back-to-back entities have a space between them
+
+.. |space| unicode:: 0x20

packages/aws-cdk-docs/src/concepts.rst → docs/src/concepts.rst

@@ -1,48 +1,48 @@
-.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-
-   This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
-   International License (the "License"). You may not use this file except in compliance with the
-   License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
-
-   This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
-   either express or implied. See the License for the specific language governing permissions and
-   limitations under the License.
-
-.. _concepts:
-
-##############
-|cdk| Concepts
-##############
-
-This topic describes some of the concepts (the why and how)
-behind the |cdk|.
-It also discusses the advantages of a |l2| over a low-level |l1|.
-
-|cdk| apps are represented as a hierarchal structure we call the *construct
-tree*. Every node in the tree is a |construct-class| object. The
-root of an |cdk| app is typically an |app-class| construct. Apps
-contain one or more |stack-class| constructs, which are deployable
-units of your app.
-
-This composition of constructs gives you the flexibility to architect your app, such as
-having a stack deployed in multiple regions. Stacks represent a collection of AWS resources, either directly or
-indirectly through a child construct that itself represents an AWS resource, such as an |SQS|
-queue, an |SNS| topic, an |LAM| function, or an |DDB| table.
-
-This composition of constructs also means you can easily create sharable constructs,
-and make changes to any construct and have those changes available to consumers
-as shared class libraries.
-
-.. toctree::
-   :titlesonly:
-   :caption: Topics
-   :maxdepth: 1
-
-   constructs
-   stacks
-   logical-ids
-   environments
-   apps
-   context
-   assets
-   applets
+.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+   This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+   International License (the "License"). You may not use this file except in compliance with the
+   License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
+
+   This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+   either express or implied. See the License for the specific language governing permissions and
+   limitations under the License.
+
+.. _concepts:
+
+##############
+|cdk| Concepts
+##############
+
+This topic describes some of the concepts (the why and how)
+behind the |cdk|.
+It also discusses the advantages of a |l2| over a low-level |l1|.
+
+|cdk| apps are represented as a hierarchal structure we call the *construct
+tree*. Every node in the tree is a |construct-class| object. The
+root of an |cdk| app is typically an |app-class| construct. Apps
+contain one or more |stack-class| constructs, which are deployable
+units of your app.
+
+This composition of constructs gives you the flexibility to architect your app, such as
+having a stack deployed in multiple regions. Stacks represent a collection of AWS resources, either directly or
+indirectly through a child construct that itself represents an AWS resource, such as an |SQS|
+queue, an |SNS| topic, an |LAM| function, or an |DDB| table.
+
+This composition of constructs also means you can easily create sharable constructs,
+and make changes to any construct and have those changes available to consumers
+as shared class libraries.
+
+.. toctree::
+   :titlesonly:
+   :caption: Topics
+   :maxdepth: 1
+
+   constructs
+   stacks
+   logical-ids
+   environments
+   apps
+   context
+   assets
+   applets