Merge pull request #642 from samalba/docs-stdlib

Docs stdlib

docs/reference/universe/alpine.md

@@ -4,8 +4,12 @@ sidebar_label: alpine
 
 # dagger.io/alpine
 
+Base package for Alpine Linux
+
 ## #Image
 
+Base image for Alpine Linux
+
 ### #Image Inputs
 
 _No input._

docs/reference/universe/aws/README.md

@@ -4,6 +4,8 @@ sidebar_label: aws
 
 # dagger.io/aws
 
+AWS base package
+
 ## #CLI
 
 Re-usable aws-cli component
@@ -22,7 +24,7 @@ _No output._
 
 ## #Config
 
-Base AWS Config
+AWS Config shared by all AWS packages
 
 ### #Config Inputs
 

docs/reference/universe/aws/cloudformation.md

@@ -4,6 +4,8 @@ sidebar_label: cloudformation
 
 # dagger.io/aws/cloudformation
 
+AWS Cloud Formation
+
 ## #Stack
 
 AWS CloudFormation Stack

docs/reference/universe/aws/ecr.md

@@ -4,6 +4,8 @@ sidebar_label: ecr
 
 # dagger.io/aws/ecr
 
+Amazon Elastic Container Registry (ECR)
+
 ## #Credentials
 
 Convert AWS credentials to Docker Registry credentials for ECR

docs/reference/universe/aws/ecs.md

@@ -3,3 +3,5 @@ sidebar_label: ecs
 ---
 
 # dagger.io/aws/ecs
+
+AWS Elastic Container Service (ECS)

docs/reference/universe/aws/eks.md

@@ -4,6 +4,8 @@ sidebar_label: eks
 
 # dagger.io/aws/eks
 
+AWS Elastic Kubernetes Service (EKS)
+
 ## #KubeConfig
 
 KubeConfig config outputs a valid kube-auth-config for kubectl client

docs/reference/universe/aws/elb.md

@@ -4,9 +4,11 @@ sidebar_label: elb
 
 # dagger.io/aws/elb
 
+AWS Elastic Load Balancer (ELBv2)
+
 ## #RandomRulePriority
 
-Returns a non-taken rule priority (randomized)
+Returns an unused rule priority (randomized in available range)
 
 ### #RandomRulePriority Inputs
 

docs/reference/universe/aws/rds.md

@@ -4,8 +4,12 @@ sidebar_label: rds
 
 # dagger.io/aws/rds
 
+AWS Relational Database Service (RDS)
+
 ## #CreateDB
 
+Creates a new Database on an existing RDS Instance
+
 ### #CreateDB Inputs
 
 | Name                 | Type                | Description                                                  |
@@ -16,7 +20,7 @@ sidebar_label: rds
 |*name*                | `string`            |DB name                                                       |
 |*dbArn*               | `string`            |ARN of the database instance                                  |
 |*secretArn*           | `string`            |ARN of the database secret (for connecting via rds api)       |
-|*dbType*              | `string`            |-                                                          |
+|*dbType*              | `string`            |Database type MySQL or PostgreSQL (Aurora Serverless only)    |
 
 ### #CreateDB Outputs
 
@@ -26,6 +30,8 @@ sidebar_label: rds
 
 ## #CreateUser
 
+Creates a new user credentials on an existing RDS Instance
+
 ### #CreateUser Inputs
 
 | Name                 | Type                | Description                                                  |
@@ -37,8 +43,8 @@ sidebar_label: rds
 |*password*            | `string`            |Password                                                      |
 |*dbArn*               | `string`            |ARN of the database instance                                  |
 |*secretArn*           | `string`            |ARN of the database secret (for connecting via rds api)       |
-|*grantDatabase*       | `*"" \| string`     |-                                                          |
-|*dbType*              | `string`            |-                                                          |
+|*grantDatabase*       | `*"" \| string`     |Name of the database to grants access to                      |
+|*dbType*              | `string`            |Database type MySQL or PostgreSQL (Aurora Serverless only)    |
 
 ### #CreateUser Outputs
 
@@ -48,6 +54,8 @@ sidebar_label: rds
 
 ## #Instance
 
+Fetches information on an existing RDS Instance
+
 ### #Instance Inputs
 
 | Name                 | Type                | Description                    |

docs/reference/universe/aws/s3.md

@@ -4,9 +4,11 @@ sidebar_label: s3
 
 # dagger.io/aws/s3
 
+AWS Simple Storage Service
+
 ## #Put
 
-S3 file or Directory upload
+S3 Bucket upload (file or directory)
 
 ### #Put Inputs
 
@@ -27,7 +29,7 @@ S3 file or Directory upload
 
 ## #Sync
 
-S3 Sync
+S3 Bucket sync
 
 ### #Sync Inputs
 

docs/reference/universe/docker.md

@@ -4,6 +4,8 @@ sidebar_label: docker
 
 # dagger.io/docker
 
+Docker container operations
+
 ## #Build
 
 Build a Docker image from source, using included Dockerfile
@@ -40,8 +42,8 @@ Build a Docker image from the provided Dockerfile contents
 
 | Name             | Type                  | Description                     |
 | -------------    |:-------------:        |:-------------:                  |
-|*dockerfile*      | `string`              |-                   |
-|*context*         | `dagger.#Artifact`    |-                   |
+|*dockerfile*      | `string`              |Dockerfile passed as a string    |
+|*context*         | `dagger.#Artifact`    |Build context                    |
 
 ### #ImageFromDockerfile Outputs
 

docs/reference/universe/gcp/README.md

@@ -4,6 +4,8 @@ sidebar_label: gcp
 
 # dagger.io/gcp
 
+Google Cloud Platform
+
 ## #Config
 
 Base Google Cloud Config

docs/reference/universe/gcp/gcr.md

@@ -4,6 +4,8 @@ sidebar_label: gcr
 
 # dagger.io/gcp/gcr
 
+Google Container Registry
+
 ## #Credentials
 
 Credentials retriever for GCR

docs/reference/universe/gcp/gke.md

@@ -4,6 +4,8 @@ sidebar_label: gke
 
 # dagger.io/gcp/gke
 
+Google Kubernetes Engine
+
 ## #KubeConfig
 
 KubeConfig config outputs a valid kube-auth-config for kubectl client

docs/reference/universe/git.md

@@ -4,6 +4,8 @@ sidebar_label: git
 
 # dagger.io/git
 
+Git operations
+
 ## #CurrentBranch
 
 Get the name of the current checked out branch or tag
@@ -12,13 +14,13 @@ Get the name of the current checked out branch or tag
 
 | Name             | Type                  | Description        |
 | -------------    |:-------------:        |:-------------:     |
-|*repository*      | `dagger.#Artifact`    |-                   |
+|*repository*      | `dagger.#Artifact`    |Git repository      |
 
 ### #CurrentBranch Outputs
 
 | Name             | Type              | Description        |
 | -------------    |:-------------:    |:-------------:     |
-|*name*            | `string`          |-                   |
+|*name*            | `string`          |Git branch name     |
 
 ## #Repository
 
@@ -44,10 +46,10 @@ List tags of a repository
 
 | Name             | Type                  | Description        |
 | -------------    |:-------------:        |:-------------:     |
-|*repository*      | `dagger.#Artifact`    |-                   |
+|*repository*      | `dagger.#Artifact`    |Git repository      |
 
 ### #Tags Outputs
 
 | Name             | Type              | Description        |
 | -------------    |:-------------:    |:-------------:     |
-|*tags*            | `[]`              |-                   |
+|*tags*            | `[]`              |Repository tags     |

docs/reference/universe/go.md

@@ -4,8 +4,12 @@ sidebar_label: go
 
 # dagger.io/go
 
+Go build operations
+
 ## #Build
 
+Go application builder
+
 ### #Build Inputs
 
 | Name             | Type                    | Description                      |
@@ -33,7 +37,7 @@ A standalone go environment
 | Name             | Type                                | Description                                             |
 | -------------    |:-------------:                      |:-------------:                                          |
 |*version*         | `*"1.16" \| string`                 |Go version to use                                        |
-|*source*          | `dagger.#Artifact`                  |-                                                        |
+|*source*          | `dagger.#Artifact`                  |Source code                                              |
 |*image.from*      | `"docker.io/golang:1.16-alpine"`    |Remote ref (example: "index.docker.io/alpine:latest")    |
 
 ### #Container Outputs
@@ -42,6 +46,8 @@ _No output._
 
 ## #Go
 
+Re-usable component for the Go compiler
+
 ### #Go Inputs
 
 | Name             | Type                   | Description                  |

docs/reference/universe/io.md

@@ -4,6 +4,8 @@ sidebar_label: io
 
 # dagger.io/io
 
+IO operations
+
 ## #Dir
 
 Standard interface for directory operations in cue
@@ -30,6 +32,8 @@ _No output._
 
 ## #ReadWriter
 
+Standard ReadWriter interface
+
 ### #ReadWriter Inputs
 
 _No input._
@@ -40,6 +44,8 @@ _No output._
 
 ## #Reader
 
+Standard Reader interface
+
 ### #Reader Inputs
 
 _No input._
@@ -50,6 +56,8 @@ _No output._
 
 ## #Writer
 
+Standard Writer interface
+
 ### #Writer Inputs
 
 _No input._

docs/reference/universe/js/yarn.md

@@ -8,7 +8,7 @@ Yarn is a package manager for Javascript applications
 
 ## #Package
 
-A Yarn package.
+A Yarn package
 
 ### #Package Inputs
 
@@ -18,8 +18,8 @@ A Yarn package.
 |*package*         | `struct`                |Extra alpine packages to install                                                      |
 |*cwd*             | `*"." \| string`        |working directory to use                                                              |
 |*env*             | `struct`                |Environment variables                                                                 |
-|*writeEnvFile*    | `*"" \| string`         |Write the contents of `environment` to this file, in the "envfile" format.             |
-|*buildDir*        | `*"build" \| string`    |Read build output from this directory (path must be relative to working directory).    |
+|*writeEnvFile*    | `*"" \| string`         |Write the contents of `environment` to this file, in the "envfile" format             |
+|*buildDir*        | `*"build" \| string`    |Read build output from this directory (path must be relative to working directory)    |
 |*script*          | `*"build" \| string`    |Run this yarn script                                                                  |
 |*args*            | `*[] \| []`             |Optional arguments for the script                                                     |
 
@@ -27,4 +27,4 @@ A Yarn package.
 
 | Name             | Type              | Description              |
 | -------------    |:-------------:    |:-------------:           |
-|*build*           | `struct`          |-                   |
+|*build*           | `struct`          |Build output directory    |

docs/reference/universe/kubernetes/README.md

@@ -4,8 +4,12 @@ sidebar_label: kubernetes
 
 # dagger.io/kubernetes
 
+Kubernetes client operations
+
 ## #Kubectl
 
+Kubectl client
+
 ### #Kubectl Inputs
 
 _No input._

docs/reference/universe/kubernetes/kustomize.md

@@ -4,6 +4,8 @@ sidebar_label: kustomize
 
 # dagger.io/kubernetes/kustomize
 
+Kustomize config management
+
 ## #Kustomization
 
 ### #Kustomization Inputs

docs/reference/universe/netlify.md

@@ -4,9 +4,11 @@ sidebar_label: netlify
 
 # dagger.io/netlify
 
+Netlify client operations
+
 ## #Account
 
-A Netlify account
+Netlify account credentials
 
 ### #Account Inputs
 
@@ -21,7 +23,7 @@ _No output._
 
 ## #Site
 
-A Netlify site
+Netlify site
 
 ### #Site Inputs
 

docs/reference/universe/random.md

@@ -4,16 +4,7 @@ sidebar_label: random
 
 # dagger.io/random
 
-Random generation utilities.
-
-Example:
-
-```cue
-str: random.#String & {
-  seed: "str"
-  length: 10
-}
-```
+Random generation utilities
 
 ## #String
 

docs/reference/universe/terraform.md

@@ -4,14 +4,18 @@ sidebar_label: terraform
 
 # dagger.io/terraform
 
+Terraform operations
+
 ## #Configuration
 
+Terraform configuration
+
 ### #Configuration Inputs
 
 | Name             | Type                     | Description            |
 | -------------    |:-------------:           |:-------------:         |
-|*version*         | `*"latest" \| string`    |-                   |
-|*source*          | `dagger.#Artifact`       |-                   |
+|*version*         | `*"latest" \| string`    |Terraform version       |
+|*source*          | `dagger.#Artifact`       |Source configuration    |
 
 ### #Configuration Outputs
 

stdlib/alpine/alpine.cue

@@ -1,3 +1,4 @@
+// Base package for Alpine Linux
 package alpine
 
 import (
@@ -6,6 +7,7 @@ import (
 
 let defaultVersion = "3.13.5@sha256:69e70a79f2d41ab5d637de98c1e0b055206ba40a8145e7bddb55ccc04e13cf8f"
 
+// Base image for Alpine Linux
 #Image: {
 	package: [string]: true | false | string
 	version: string | *defaultVersion

stdlib/aws/aws.cue

@@ -1,3 +1,4 @@
+// AWS base package
 package aws
 
 import (
@@ -6,7 +7,7 @@ import (
 	"dagger.io/alpine"
 )
 
-// Base AWS Config
+// AWS Config shared by all AWS packages
 #Config: {
 	// AWS region
 	region: string @dagger(input)

stdlib/aws/cloudformation/cloudformation.cue

@@ -1,3 +1,4 @@
+// AWS Cloud Formation
 package cloudformation
 
 import (

stdlib/aws/ecr/ecr.cue

@@ -1,3 +1,4 @@
+// Amazon Elastic Container Registry (ECR)
 package ecr
 
 import (

stdlib/aws/ecs/run-task.cue

@@ -1,10 +1,11 @@
+// AWS Elastic Container Service (ECS)
 package ecs
 
 import (
 	"dagger.io/aws"
 )
 
-// RunTask implement ecs run-task
+// RunTask implements ecs run-task for running a single container on ECS
 #RunTask: {
 
 	// AWS Config

stdlib/aws/eks/eks.cue

@@ -1,3 +1,4 @@
+// AWS Elastic Kubernetes Service (EKS)
 package eks
 
 import (

stdlib/aws/elb/elb.cue

@@ -1,3 +1,4 @@
+// AWS Elastic Load Balancer (ELBv2)
 package elb
 
 import (
@@ -5,7 +6,7 @@ import (
 	"dagger.io/aws"
 )
 
-// Returns a non-taken rule priority (randomized)
+// Returns an unused rule priority (randomized in available range)
 #RandomRulePriority: {
 	// AWS Config
 	config: aws.#Config

stdlib/aws/rds/rds.cue

@@ -1,3 +1,4 @@
+// AWS Relational Database Service (RDS)
 package rds
 
 import (
@@ -6,6 +7,7 @@ import (
 	"dagger.io/aws"
 )
 
+// Creates a new Database on an existing RDS Instance
 #CreateDB: {
 	// AWS Config
 	config: aws.#Config
@@ -19,6 +21,7 @@ import (
 	// ARN of the database secret (for connecting via rds api)
 	secretArn: string @dagger(input)
 
+	// Database type MySQL or PostgreSQL (Aurora Serverless only)
 	dbType: "mysql" | "postgres" @dagger(input)
 
 	// Name of the DB created
@@ -79,6 +82,7 @@ import (
 	}
 }
 
+// Creates a new user credentials on an existing RDS Instance
 #CreateUser: {
 	// AWS Config
 	config: aws.#Config
@@ -95,8 +99,10 @@ import (
 	// ARN of the database secret (for connecting via rds api)
 	secretArn: string @dagger(input)
 
+	// Name of the database to grants access to
 	grantDatabase: string | *"" @dagger(input)
 
+	// Database type MySQL or PostgreSQL (Aurora Serverless only)
 	dbType: "mysql" | "postgres" @dagger(input)
 
 	// Outputed username
@@ -185,6 +191,7 @@ import (
 	}
 }
 
+// Fetches information on an existing RDS Instance
 #Instance: {
 	// AWS Config
 	config: aws.#Config

stdlib/aws/s3/s3.cue

@@ -1,3 +1,4 @@
+// AWS Simple Storage Service
 package s3
 
 import (
@@ -6,7 +7,7 @@ import (
 	"dagger.io/aws"
 )
 
-// S3 file or Directory upload
+// S3 Bucket upload (file or directory)
 #Put: {
 
 	// AWS Config
@@ -91,7 +92,7 @@ import (
 	}
 }
 
-// S3 Sync
+// S3 Bucket sync
 #Sync: {
 	// AWS Config
 	config: aws.#Config

stdlib/dagger/dagger.cue

@@ -6,7 +6,6 @@ import (
 
 // An artifact such as source code checkout, container image, binary archive...
 // May be passed as user input, or computed by a buildkit pipeline
-
 #Artifact: {
 	@dagger(artifact)
 	#up: [...op.#Op]

stdlib/docker/docker.cue

@@ -1,3 +1,4 @@
+// Docker container operations
 package docker
 
 import (
@@ -102,7 +103,10 @@ import (
 // Build a Docker image from the provided Dockerfile contents
 // FIXME: incorporate into #Build
 #ImageFromDockerfile: {
+	// Dockerfile passed as a string
 	dockerfile: string @dagger(input)
+
+	// Build context
 	context: dagger.#Artifact @dagger(input)
 
 	#up: [

stdlib/gcp/gcp.cue

@@ -1,3 +1,4 @@
+// Google Cloud Platform
 package gcp
 
 import (

stdlib/gcp/gcr/gcr.cue

@@ -1,3 +1,4 @@
+// Google Container Registry
 package gcr
 
 import (

stdlib/gcp/gke/gke.cue

@@ -1,3 +1,4 @@
+// Google Kubernetes Engine
 package gke
 
 import (

stdlib/git/git.cue

@@ -1,3 +1,4 @@
+// Git operations
 package git
 
 import (
@@ -35,7 +36,11 @@ import (
 
 // Get the name of the current checked out branch or tag
 #CurrentBranch: {
+
+	// Git repository
 	repository: dagger.#Artifact @dagger(input)
+
+	// Git branch name
 	name: {
 		string
 		@dagger(output)
@@ -74,7 +79,11 @@ import (
 
 // List tags of a repository
 #Tags: {
+
+	// Git repository
 	repository: dagger.#Artifact @dagger(input)
+
+	// Repository tags
 	tags: {
 		[...string]
 		@dagger(output)

stdlib/go/go.cue

@@ -1,3 +1,4 @@
+// Go build operations
 package go
 
 import (
@@ -10,8 +11,11 @@ import (
 
 // A standalone go environment
 #Container: {
+
 	// Go version to use
 	version: *"1.16" | string @dagger(input)
+
+	// Source code
 	source: dagger.#Artifact @dagger(input)
 
 	os.#Container & {
@@ -36,6 +40,7 @@ import (
 	}
 }
 
+// Re-usable component for the Go compiler
 #Go: {
 	// Go version to use
 	version: *"1.16" | string @dagger(input)
@@ -70,6 +75,7 @@ import (
 	]
 }
 
+// Go application builder
 #Build: {
 	// Go version to use
 	version: *#Go.version | string @dagger(input)
@@ -95,6 +101,7 @@ import (
 	// Specify the targeted binary name
 	output: string @dagger(output)
 
+	// Environment variables
 	env: {
 		[string]: string @dagger(input)
 	}

stdlib/io/io.cue

@@ -1,3 +1,4 @@
+// IO operations
 package io
 
 // Standard interface for directory operations in cue
@@ -13,8 +14,10 @@ package io
 	...
 }
 
+// Standard ReadWriter interface
 #ReadWriter: #Reader & #Writer
 
+// Standard Reader interface
 #Reader: {
 	read: {
 		// FIXME: support different data schemas for different formats
@@ -26,6 +29,7 @@ package io
 	...
 }
 
+// Standard Writer interface
 #Writer: {
 	write: *null | {
 		// FIXME: support writing in multiple formats

stdlib/js/yarn/yarn.cue

@@ -9,7 +9,7 @@ import (
 	"dagger.io/os"
 )
 
-// A Yarn package.
+// A Yarn package
 #Package: {
 	// Application source code
 	source: dagger.#Artifact @dagger(input)
@@ -28,11 +28,11 @@ import (
 	} @dagger(input)
 
 	// Write the contents of `environment` to this file,
-	// in the "envfile" format.
+	// in the "envfile" format
 	writeEnvFile: string | *"" @dagger(input)
 
 	// Read build output from this directory
-	// (path must be relative to working directory).
+	// (path must be relative to working directory)
 	buildDir: string | *"build" @dagger(input)
 
 	// Run this yarn script
@@ -41,6 +41,7 @@ import (
 	// Optional arguments for the script
 	args: [...string] | *[] @dagger(input)
 
+	// Build output directory
 	build: os.#Dir & {
 		from: ctr
 		path: "/build"

stdlib/kubernetes/kubernetes.cue

@@ -1,3 +1,4 @@
+// Kubernetes client operations
 package kubernetes
 
 import (
@@ -6,8 +7,10 @@ import (
 	"dagger.io/alpine"
 )
 
+// Kubectl client
 #Kubectl: {
 
+	// Kubectl version
 	version: *"v1.19.9" | string
 
 	#code: #"""

stdlib/kubernetes/kustomize/kustomization.cue

@@ -1,3 +1,4 @@
+// Kustomize config management
 package kustomize
 
 import (

stdlib/netlify/netlify.cue

@@ -1,3 +1,4 @@
+// Netlify client operations
 package netlify
 
 import (
@@ -6,7 +7,7 @@ import (
 	"dagger.io/os"
 )
 
-// A Netlify account
+// Netlify account credentials
 #Account: {
 	// Use this Netlify account name
 	// (also referred to as "team" in the Netlify docs)
@@ -16,7 +17,7 @@ import (
 	token: dagger.#Secret @dagger(input)
 }
 
-// A Netlify site
+// Netlify site
 #Site: {
 	// Netlify account this site is attached to
 	account: #Account

stdlib/random/string.cue

@@ -1,16 +1,4 @@
-// Random generation utilities.
-//
-// Example:
-//
-// ```cue
-// str: random.#String & {
-//   seed: "str"
-//   length: 10
-// }
-// ```
-//
-//
-//
+// Random generation utilities
 package random
 
 import (

stdlib/terraform/terraform.cue

@@ -1,3 +1,4 @@
+// Terraform operations
 package terraform
 
 import (
@@ -7,15 +8,20 @@ import (
 	"dagger.io/dagger/op"
 )
 
+// Terraform configuration
 #Configuration: {
+
+	// Terraform version
 	version: string | *"latest" @dagger(input)
 
+	// Source configuration
 	source: dagger.#Artifact @dagger(input)
 
 	tfvars?: {
 		...
 	}
 
+	// Environment variables
 	env: {
 		[string]: string @dagger(input)
 	}