Improve documentation for GitHub modules (#334)

* Improve documentation for GitHub modules

- link to Terraform documentation of double-slash subdirectory notation
- link to Terraform and git documentation for selecting a reference
- ensure README includes examples of each feature above
- link to DAOS example which used a GitHub module
- add section on use of remote modules generally

modules/README.md

@@ -2,7 +2,11 @@
 
 This directory contains a set of core modules built for the HPC Toolkit. Modules
 describe the building blocks of an HPC deployment. The expected fields in a
-module are listed in more detail [below](#module-fields).
+module are listed in more detail [below](#module-fields). Blueprints can be
+extended in functionality by incorporating [modules from GitHub
+repositories][ghmods].
+
+[ghmods]: #github-modules
 
 ## All Modules
 
@@ -139,7 +143,7 @@ actual content of those files is determined by the [kind](#kind-required) of the
 module.
 
 A source can be a path which may refer to a module embedded in the `ghpc`
-binary or a local file. It can also be a URL pointing to a github path
+binary or a local file. It can also be a URL pointing to a GitHub path
 containing a conforming module.
 
 #### Embedded Modules
@@ -176,12 +180,12 @@ following module definition refers the local pre-existing-vpc modules.
 > directory, otherwise the path would need to be updated to point at the correct
 > directory.
 
-#### Github Modules
+#### GitHub Modules
 
-GitHub modules point to a module in GitHub. To use a GitHub module, set
-the source to a path starting with `github.com` (over HTTPS) or `[email protected]`
-(over SSH). For instance, the following module definitions are sourcing the
-vpc module by pointing at the HPC Toolkit github repository:
+To use a Terraform module available on GitHub, set the source to a path starting
+with `github.com` (over HTTPS) or `[email protected]` (over SSH). For instance, the
+following module definitions are sourcing the vpc module by pointing at the HPC
+Toolkit GitHub repository:
 
 Get module from GitHub over SSH:
 
@@ -199,6 +203,27 @@ Get module from GitHub over HTTPS:
     id: network1
 ```
 
+Both examples above use the [double-slash notation][tfsubdir] (`//`) to indicate
+the root directory of the git repository and the remainder of the path indicates
+the location of the Terraform module.
+
+Additionally, [specific revisions of a remote module][tfrev] can be selected by
+any valid [git reference][gitref]. Typically, these are a git branch, commit
+hash or tag. The [Intel DAOS blueprint][daos-cluster.yaml] makes extensive use
+of this feature. For example, to temporarily point to a development copy of the
+Toolkit vpc module, use:
+
+```yaml
+  - source: github.com/GoogleCloudPlatform/hpc-toolkit//modules/network/vpc?ref=develop
+    kind: terraform
+    id: network1
+```
+
+[tfrev]: https://www.terraform.io/language/modules/sources#selecting-a-revision
+[gitref]: https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_single_revisions
+[tfsubdir]: https://www.terraform.io/language/modules/sources#modules-in-package-sub-directories
+[daos-cluster.yaml]: ../community/examples/intel/daos-cluster.yaml
+
 ### Kind (Required)
 
 `kind` refers to the way in which a module is deployed. Currently, `kind` can be