will3942/registry

The global index of everything you can do with Pulumi.

Registry

Pulumi Registry is the global index of everything you can do with Pulumi.

We’re always eager to expand that index with new Pulumi Packages. Whether you want to author a new native provider, bridge a provider from the Terraform ecosystem, or create a cloud component with best practices and sensible defaults built in, we’d like to work with you to list it on Pulumi Registry.

Contact us to start publishing to Pulumi Registry. If you’d like, you can also get a head start by authoring a Pulumi Package.

About this repository

This repository is a Hugo module that doubles as a development server to make it easier to work on the pages that make up Pulumi Registry. It contains most of the Hugo content and layouts files comprising what you see at https://pulumi.com/registry -- but not everything. A few things you won't find in this repository include:

• Package-level how-to guides. These files are still built and checked into the pulumi/docs repository. (We're working on bringing them into this repository, though.)

• JavaScript, CSS, and web components. We build the JavaScript and CSS bundles that power the Pulumi website (and therefore the Registry) in the pulumi/theme repository.

• Layouts and content for pulumi.com marketing pages, CLI docs, the blog, etc., all of which are managed in the pulumi/pulumi-hugo repository.

  

You can, however, develop locally with this repository using content from these other Hugo-module repositories, either by loading their content remotely or pointing your Hugo development server to local clones of them. More on this below.

Using this repository

Prerequisites

We build the Pulumi website statically with Hugo, manage our Node.js dependencies with Yarn, and write most of our documentation in Markdown. Below is a list of the tools you'll need to run the website locally:

• Go (>= 1.15)
• Hugo (>= 0.81)
• Node.js (>= 1.14)
• Yarn (1.x)

Installing dependencies

First, run make ensure to check for the appropriate tools, versions, and install any dependencies. The script will let you know if you're missing anything important.

make ensure

Running Hugo locally

Once you've run make ensure successfully, you're ready to run the development server:

make serve

When you do this, Hugo will load the latest versions of:

• The pulumi/pulumi-hugo module, which contains our marketing pages, some docs content, the blog, etc.
• The pulumi/theme module, which contains our CSS and JavaScript bundles (web components, styles, etc.).

... and then start a development server at http://localhost:1313. Any changes you make to the content, layouts, or other Hugo component folders should be reloaded automatically.

Developing alongside another Hugo module

If you want to develop another module alongside this one -- e.g., add a new web component to use in the Registry, or to make changes to Registry-specific CSS -- you can point your development server to a local clone of pulumi/theme. To do that, first clone the repository, then add a replace line to the go.mod file at the root of this repository to override the existing reference to pulumi/theme temporarily. For instance:

module github.com/pulumi/pulumi-hugo

go 1.16

require (
	github.com/pulumi/theme v0.0.0-20211015193555-271ef1f67093 // indirect
)

// Add this line to tell Hugo to use your local clone of pulumi/theme.
replace github.com/pulumi/theme => ../theme

Tip: If you run make serve from the root of pulumi/theme (in another terminal tab) while also running make serve in this one, the changes you make to the CSS and JavaScript source files in pulumi/theme will be recompiled and reloaded in the browser automatically.

Be sure to remove the replace line before you commit.

Linking to pages that don't exist in this repository

If you want to link to a page that exists on https://pulumi.com but not in this repository, you can still use a Hugo relref in the usual way -- you'll just need to make sure the path you're linking to does exist (or will exist by the time you merge your change). For example, to add a link pointing to the Pulumi CLI documentation (which does not exist in this repository), you'd use:

{{< relref /docs/reference/cli >}}

... and just be aware while the link won't work for you locally, it will work once your change is merged and picked up by our website automation (see Merging and releasing] below for details). This works because we've suppressed Hugo's built-in relref validation locally to keep the module-development workflow as lightweight as possible.

Temporarily pulling in content from pulumi/docs

If the change you're working on requires content from pulumi/docs -- e.g., the aforementioned how-to guides -- you may want to be able to see some of that content as you develop. To do that, just copy the files you need from the content folder of pulumi/docs into the content folder of this repository, remembering to remove those files before you commit. For example:

# Copy the AWS how-to guides from a local/sibling clone of pulumi/docs.
cp ../docs/content/registry/packages/aws/how-to-guides ./themes/default/content/registry/packages/aws/

Temporarily generating API docs for packages

The API docs for packages can be generated on-demand using the resourcedocsgen tool. The PR build for this repo, for instance, generates the API docs for all packages from the latest commit hash of the PR being built. Likewise, as long as your branch is pushed up to GH, you can generate API docs using any commit hash from your PR branch locally as well. This is because the resourcedocsgen will attempt to clone the registry repo at the commit hash you specify in a temp location in order to read the package metadata files from it.

For example,

go install github.com/pulumi/docs/tools/resourcedocsgen@master

# Generate docs for a single package using your PR branch name locally.
resourcedocsgen docs registry "<package name>" \
    --branch "<your PR branch name>" \
    --baseDocsOutDir "themes/default/content/registry/packages" \
    --basePackageTreeJSONOutDir "themes/default/static/registry/packages/navs" \
    --logtostderr

or if you prefer using a specific commit hash use the --commitSha flag instead.

Run resourcedocsgen docs registry --help for help regarding its use. The README for the resourcedocsgen tool has more info on generating API docs.

Again, just be sure to remove these files before you commit:

# Remove the files we just added.
rm -rf ./themes/default/content/registry/packages/aws/api-docs/
rm -f ./themes/default/static/registry/packages/navs/aws.json

or if you copied the how-to-guides for a package from docs, remove the individual markdown files from the respective how-to-guides folder for that package.

Submitting, merging and releasing

When you're ready to submit a pull request, make sure you've removed anything that doesn't seem to belong (go.mod/go.sum changes, content from pulumi/docs, etc.) and submit the PR in the usual way.

If you're doing work in another repository that's associated with the changes in your PR, you can "pin" your PR branch to another module repository branch by pointing Hugo to that branch. To do that, use hugo mod get and pass a reference to the target branch:

hugo mod get github.com/pulumi/theme@my-special-branch

This will modify go.mod and go.sum accordingly and result in a PR preview that incorporates your changes from the other branch. Just be sure to remove these changes before you're ready to merge.

Once your PR is approved and merged into the default branch of this repository, an automated process that runs on pulumi/docs will detect your changes and produce a PR and integration build containing content from all other Hugo modules. Once that PR build completes and is approved and merged into pulumi/docs, your changes will be deployed to https://pulumi.com.