website: working on registry docs

website/docs/modules/create.html.markdown

@@ -14,6 +14,11 @@ the Terraform files you're applying comprise what is called the _root module_. T
 
 Therefore, you can enter the source of any module, satisfy any required variables, run `terraform apply`, and expect it to work.
 
+Modules that are created for reuse should follow the
+[standard structure](#standard-structure). This structure enables tooling
+such as the [Terraform Registry](/docs/registry/index.html) to inspect and
+generate documentation, read examples, and more.
+
 ## An Example Module
 
 Within a folder containing Terraform configurations, create a subfolder called `child`. In this subfolder, make one empty `main.tf` file. Then, back in the root folder containing the `child` folder, add this to one of your Terraform configuration files:
@@ -89,3 +94,7 @@ variables and outputs you require.
 The [get command](/docs/commands/get.html) will automatically get all nested modules.
 
 You don't have to worry about conflicting versions of modules, since Terraform builds isolated subtrees of all dependencies. For example, one module might use version 1.0 of module `foo` and another module might use version 2.0, and this will all work fine within Terraform since the modules are created separately.
+
+## Standard Structure
+
+TODO

website/docs/modules/sources.html.markdown

@@ -7,14 +7,17 @@ description: Explains the use of the source parameter, which tells Terraform whe
 
 # Module Sources
 
-As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`. The `source` parameter tells Terraform where the module can be found and what constraints to put on the module. Constraints can include a specific version or Git branch.
+As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`.
 
+The `source` parameter tells Terraform where the module can be found.
 Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from.
 
 Terraform supports the following sources:
 
   * Local file paths
 
+  * [Terraform Registry](/docs/registry/index.html)
+
   * GitHub
 
   * Bitbucket
@@ -39,6 +42,27 @@ module "consul" {
 
 Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available.
 
+## Terraform Registry
+
+The [Terraform Registry](https://registry.terraform.io) is an index of modules
+written by the Terraform community.
+The Terraform Registry is the easiest
+way to get started with Terraform and to find modules to start with.
+The registry is integrated directly into Terraform:
+
+```hcl
+module "consul" {
+  source = "hashicorp/consul/aws"
+}
+```
+
+The above example would use the
+[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
+from the public registry.
+
+You can learn more about the registry at the
+[Terraform Registry documentation section](/docs/registry/index.html).
+
 ## GitHub
 
 Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:

website/docs/modules/usage.html.markdown

@@ -11,16 +11,21 @@ Using modules in Terraform is very similar to defining resources:
 
 ```shell
 module "consul" {
-  source  = "github.com/hashicorp/consul/terraform/aws"
+  source  = "hashicorp/consul/aws"
   servers = 3
 }
 ```
 
 You can view the full documentation for configuring modules in the [Module Configuration](/docs/configuration/modules.html) section.
 
-In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its variables.
+In modules we only specify a name rather than a name and a type (as in resources). This name can be used elsewhere in the configuration to reference the module and its outputs.
 
-The existence of the above configuration will tell Terraform to create the resources in the `consul` module which can be found on GitHub at the given URL. Just like a resource, the module configuration can be deleted to remove the module.
+The source tells Terraform what to create. In this example, we create
+the [Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
+from the [Terraform Registry](https://registry.terraform.io). You can learn
+more about the [source configuration below](#source).
+
+Just like a resource, the module configuration can be deleted to remove the module.
 
 ## Multiple instances of a module
 
@@ -62,8 +67,14 @@ The resource names in your module  get prefixed by `module.<module-instance-name
 
 ## Source
 
-The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where the module can be downloaded, updated, etc. Terraform comes with support for a variety of module sources. These
-are documented in the [Module sources documentation](/docs/modules/sources.html).
+The only required configuration key for a module is the `source` parameter. The value of this tells Terraform where the module can be downloaded, updated, etc. Terraform comes with support for a variety of module sources. The recommended source for modules is a
+[Terraform Registry](/docs/registry/index.html) since this enables additional
+features for modules such as versioning.
+
+Terraform can also download modules directly from various storage providers
+and version control systems. These sources do not support versioning and other
+registry benefits. The full list of available sources
+are documented in the [module sources documentation](/docs/modules/sources.html).
 
 Prior to running any Terraform command with a configuration that uses modules, you'll have to [get](/docs/commands/get.html) the modules. This is done using the [get command](/docs/commands/get.html).
 

website/docs/registry/index.html.md

@@ -0,0 +1,35 @@
+---
+layout: "registry"
+page_title: "Terraform Registry"
+sidebar_current: "docs-registry-home"
+description: |-
+  The Terraform Registry is a repository of modules written by the Terraform community.
+---
+
+# Terraform Registry
+
+The [Terraform Registry](https://registry.terraform.io) is a repository
+of modules written by the Terraform community. The registry can be used to
+help you get started with Terraform more quickly, see examples of how
+Terraform is written, and find pre-made modules for infrastructure components
+you require.
+
+The Terraform Registry is integrated directly into Terraform to make
+consuming modules easy. The following example shows how easy it is to
+build a fully functional [Consul](https://www.consul.io) cluster using the
+[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws).
+
+```hcl
+module "consul" {
+	source = "hashicorp/consul/aws"
+}
+```
+
+You can also publish your own modules on the Terraform Registry. You may
+use the [public registry](https://registry.terraform.io) for public modules.
+For private modules, you must use [Terraform Enterprise](https://www.hashicorp.com/products/terraform).
+You can use modules without a registry by
+[sourcing modules directly](/docs/modules/sources.html), however non-registry
+modules do not support versioning, documentation generation, and more.
+
+Use the navigation to the left to learn more about using the registry.

website/layouts/docs.erb

@@ -510,8 +510,8 @@
             <a href="/docs/modules/sources.html">Sources</a>
           </li>
 
-          <li<%= sidebar_current("docs-modules-registry") %>>
-            <a href="/docs/modules/registry.html">Registry</a>
+          <li<%= sidebar_current("docs-registry") %>>
+            <a href="/docs/registry/index.html">Registry</a>
           </li>
 
           <li<%= sidebar_current("docs-modules-create") %>>

website/layouts/registry.erb

@@ -0,0 +1,40 @@
+<% wrap_layout :inner do %>
+	<% content_for :sidebar do %>
+		<ul class="nav docs-sidenav">
+			<li<%= sidebar_current("docs-home") %>>
+				<a class="back" href="/docs/index.html">Documentation Home</a>
+			</li>
+
+			<li<%= sidebar_current("docs-registry-home") %>>
+				<a class="back" href="/docs/registry/index.html">Terraform Registry</a>
+			</li>
+
+			<hr>
+
+			<li class="active">
+				<a href="#">Modules</a>
+				<ul class="nav">
+					<li<%= sidebar_current("docs-registry-use") %>>
+						<a href="/docs/registry/modules/use.html">Finding and Using Modules</a>
+					</li>
+
+					<li<%= sidebar_current("docs-registry-use") %>>
+						<a href="/docs/registry/modules/use.html">Publishing Modules</a>
+					</li>
+				</ul>
+			</li>
+
+			<hr>
+
+			<li<%= sidebar_current("docs-registry-api") %>>
+				<a href="/docs/registry/api.html">API</a>
+			</li>
+
+			<li<%= sidebar_current("docs-registry-support") %>>
+				<a href="/docs/registry/support.html">Support</a>
+			</li>
+		</ul>
+	<% end %>
+
+	<%= yield %>
+<% end %>