richardwlaub/docs

Documentation for all things Pulumi!

Pulumi Documentation Site

"Because knowing is half the battle."

Staging	Production

Contributing

Before adding new content, read CONTRIBUTING.md.

Toolchain

The website is statically built using Jekyll. So we have basic templating for generating HTML and the ability to write most files in Markdown.

TypeScript documentation is generated directly from source using TYPEDOC. We just check the resulting files directly into the repo under ./packages/.

Development

Prerequisites

• Install a recent version of Ruby
• Install the necessary Ruby Gems: gem install jekyll bundler
• Install a recent version of Go
• Install mustache: go get -u github.com/cbroglie/mustache

Run make configure to get the required Gem dependencies. (Assuming you have a recent Ruby installation on your system.

make build will generate the website (published to _site).

make serve will build the website and serve it to http://localhost:4000.

make docker will run build and serve in a docker container with all prerequisites installed.

make test runs a broken link checker tool against http://localhost:4000.

make generate will regenerate the TypeScript documentation if needed, as well as the CLI documentation in references/cli. The generated API documentation is placed in the packages folder. This is extremely hacky.

The following repos must be peers of docs, should be checked out to an appropriate branch, and should be built before running make generate:

• pulumi
• pulumi-aws
• pulumi-azure
• pulumi-cloud
• pulumi-gcp
• pulumi-kubernetes

Generating a change log

To generate a change log from closed pull requests, run the script /scripts/generate_changelog.sh. It generates a file using the rules documented here: Planning, Work Items, and Changelog.

1. Run ./scripts/update_repos.sh to pull down the latest tags for the repos pulumi, pulumi-cloud, pulumi-aws, pulumi-terraform, and pulumi-azure

2. Set the environment variable GITHUB_TOKEN to a token that has "repo" scope.

3. [Will be improved] Clone the repo at https://github.com/pulumi/github-pr-changelog and run npm i -g to globally install the command gh-changelog.

4. Generate a change log with the following command:

   ./scripts/generate_changelog.sh <from-git-tag> <to-git-tag> > output.file
   

   You can also use the optional flags --all-prs to print out all PRs (not just ones with the relevant labels) and --tab-output to print in a format that can be pasted to a Google Sheet.

Deploying updates

When changes are merged into master our staging website (https://staging.pulumi.io/) is automatically deployed. You can use the Travis UI to check on the status of the deployment. Once it has been deployed, browse around the staging website and ensure the changes you expected were made and render correctly. Then, open a Pull Request to merge master into production.

Design Reference

Web design is hard. Documentation is hard. Good web design for documentation is harder.

Examples of other sites and their docs as inspiration:

• https://kubernetes.github.io/
• https://devcenter.heroku.com/
• https://stripe.com/docs/api/curl#authentication
• http://developer.mailchimp.com/documentation/mailchimp/
• http://ionicframework.com/docs/
• https://www.twilio.com/docs/

Creating shortlinks

Shortlinks can be created as a permanent reference to documentation that may move around in the repo. This is particularly useful for troubleshooting links that are produced by CLI tools.

To create a shortlink, create a file under /shortlinks in the following format:

---
redirect_to: <link-to-current-docs-page>
permalink: <unique-6-character-shortlink>/
---

You can use the scripts/create_short_url.sh script to generate a new random shortlink:

./scripts/create_short_url.sh /reference/troubleshooting#ingress-status-loadbalancer ingress-status-loadbalancer

Created shortlink definition at <filepath>/ingress-status-loadbalancer.md
https://pulumi.io/xdv72s --> https://pulumi.io/reference/troubleshooting#ingress-status-loadbalancer

or you can choose a shortlink:

./scripts/create_short_url.sh /reference/troubleshooting#ingress-status-loadbalancer ingress-status-loadbalancer help/ingress-lbstaus


Created shortlink definition at <filepath>/ingress-status-loadbalancer.md
https://pulumi.io/help/ingress-lbstatus --> https://pulumi.io/reference/troubleshooting#ingress-status-loadbalancer

Here is a concrete example:

---
redirect_to: /reference/troubleshooting.html#ingress-status-loadbalancer
permalink: xdv72s/
---

With the above file in place, a redirect will be created from https://pulumi.io/xdv72s to https://pulumi.io/reference/troubleshooting.html#ingress-status-loadbalancer

Note that the trailing / on the permalink is required!