From 6ff2fed9601ba73f43e7d6650d3f0f5ce2c5f180 Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Tue, 22 Jun 2021 17:43:46 +0200 Subject: [PATCH 1/6] cmd/doc: add support for generating package index Signed-off-by: Sam Alba --- cmd/dagger/cmd/doc.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cmd/dagger/cmd/doc.go b/cmd/dagger/cmd/doc.go index ee8b21ef..453ecb9b 100644 --- a/cmd/dagger/cmd/doc.go +++ b/cmd/dagger/cmd/doc.go @@ -365,6 +365,14 @@ func walkStdlib(ctx context.Context, output, format string) { return false } + // Create main index + index, err := os.Create(path.Join(output, "README.md")) + if err != nil { + lg.Fatal().Err(err).Msg("cannot generate stdlib doc index") + } + defer index.Close() + fmt.Fprintf(index, "# Index\n\n") + for p, pkg := range packages { filename := fmt.Sprintf("%s.%s", p, format) // If this package has sub-packages (e.g. `aws`), create @@ -384,6 +392,8 @@ func walkStdlib(ctx context.Context, output, format string) { } defer f.Close() + // FIXME: sort packages by name + fmt.Fprintf(index, "- [%s](./%s)\n", p, filename) fmt.Fprintf(f, "%s", pkg.Format(format)) } } From 171cd47413f290ede261d1be7dce9478d4222e6a Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Tue, 22 Jun 2021 17:44:46 +0200 Subject: [PATCH 2/6] docs: added stdlib Index Signed-off-by: Sam Alba --- docs/reference/universe/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/reference/universe/README.md diff --git a/docs/reference/universe/README.md b/docs/reference/universe/README.md new file mode 100644 index 00000000..97837fff --- /dev/null +++ b/docs/reference/universe/README.md @@ -0,0 +1,28 @@ +# Index + +- [aws](./aws/README.md) +- [aws/ecr](./aws/ecr.md) +- [aws/rds](./aws/rds.md) +- [git](./git.md) +- [kubernetes](./kubernetes/README.md) +- [terraform](./terraform.md) +- [random](./random.md) +- [aws/ecs](./aws/ecs.md) +- [aws/s3](./aws/s3.md) +- [dagger/op](./dagger/op.md) +- [gcp](./gcp/README.md) +- [go](./go.md) +- [js/yarn](./js/yarn.md) +- [kubernetes/helm](./kubernetes/helm.md) +- [docker](./docker.md) +- [gcp/gcr](./gcp/gcr.md) +- [gcp/gke](./gcp/gke.md) +- [io](./io.md) +- [kubernetes/kustomize](./kubernetes/kustomize.md) +- [os](./os.md) +- [alpine](./alpine.md) +- [aws/cloudformation](./aws/cloudformation.md) +- [aws/eks](./aws/eks.md) +- [aws/elb](./aws/elb.md) +- [dagger](./dagger/README.md) +- [netlify](./netlify.md) From b5550d0766cb29f6e1bd461fef3a5783cd43865b Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Tue, 22 Jun 2021 17:45:08 +0200 Subject: [PATCH 3/6] docs: fix broken links (fixes #681) Signed-off-by: Sam Alba --- docs/learn/102-dev.md | 54 +++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/learn/102-dev.md b/docs/learn/102-dev.md index 42fc10f3..91edcea5 100644 --- a/docs/learn/102-dev.md +++ b/docs/learn/102-dev.md @@ -19,13 +19,13 @@ configuration. An environment is made of 3 parts: -* A *plan*, authored by the environment's *developer*, using the [Cue](https://cuelang.org) language. +- A _plan_, authored by the environment's _developer_, using the [Cue](https://cuelang.org) language. -* *Inputs*, supplied by the environment's *user* via the `dagger input` command, and written to a special file. Inputs may be configuration values, artifacts, or encrypted secrets. +- _Inputs_, supplied by the environment's _user_ via the `dagger input` command, and written to a special file. Inputs may be configuration values, artifacts, or encrypted secrets. -* *Outputs*, computed by the Dagger engine via the `dagger up` command, and recorded to a special directory. +- _Outputs_, computed by the Dagger engine via the `dagger up` command, and recorded to a special directory. -We will first develop our environment's *plan*, then configure its initial inputs, then finally run it to verify that it works. +We will first develop our environment's _plan_, then configure its initial inputs, then finally run it to verify that it works. ### Anatomy of a plan @@ -38,15 +38,15 @@ of interconnected nodes. Each node in the graph represents a component of the supply chain, for example: -* Development tools: source control, CI, build systems, testing systems -* Hosting infrastructure: compute, storage, networking, databases, CDNs -* Software dependencies: operating systems, languages, libraries, frameworks, etc. +- Development tools: source control, CI, build systems, testing systems +- Hosting infrastructure: compute, storage, networking, databases, CDNs +- Software dependencies: operating systems, languages, libraries, frameworks, etc. Each link in the graph represents a flow of data between nodes. For example: -* source code flows from a git repository to a build system -* system dependencies are combined in a docker image, then uploaded to a registry -* configuration files are generated then sent to a compute cluster or load balancer +- source code flows from a git repository to a build system +- system dependencies are combined in a docker image, then uploaded to a registry +- configuration files are generated then sent to a compute cluster or load balancer ### Introduction to Cue development @@ -69,9 +69,9 @@ Although not strictly necessary, for an optimal development experience we recomm If you are new to Cue, we recommend keeping the following resources in browser tabs: -* The unofficial but excellent [Cuetorials](https://cuetorials.com/overview/foundations/) in a browser tab, to look up Cue concepts as they appear. +- The unofficial but excellent [Cuetorials](https://cuetorials.com/overview/foundations/) in a browser tab, to look up Cue concepts as they appear. -* The official [Cue interactive sandbox](https://cuelang.org/play) for easy experimentation. +- The official [Cue interactive sandbox](https://cuelang.org/play) for easy experimentation. ### Setup example app @@ -127,8 +127,8 @@ The first component of our plan is the source code of our React application. In Dagger terms, this component has 2 important properties: -1. It is an *artifact*: something that can be represented as a directory. -2. It is an *input*: something that is provided by the end user. +1. It is an _artifact_: something that can be represented as a directory. +2. It is an _input_: something that is provided by the end user. Let's write the corresponding Cue code to a new file in our package: @@ -164,15 +164,15 @@ app: yarn.#Package & { Let's break it down: -* `package multibucket`: this file is part of the multibucket package -* `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). -* `app: yarn.#Package`: apply the `#Package` definition at the key `app` -* `&`: also merge the following values at the same key... -* `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG. +- `package multibucket`: this file is part of the multibucket package +- `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](/reference/universe/README). +- `app: yarn.#Package`: apply the `#Package` definition at the key `app` +- `&`: also merge the following values at the same key... +- `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG. ### Component 3: dedicated S3 bucket -*FIXME*: this section is not yet available, because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :) +_FIXME_: this section is not yet available, because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :) ### Component 4: deploy to Netlify @@ -193,23 +193,23 @@ site: "netlify": netlify.#Site & { This is very similar to the previous component: -* We use the same package name as the other files -* We import another package from the [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). -* `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict. -* `&`: also merge the following values at the same key... -* `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG. +- We use the same package name as the other files +- We import another package from the [Dagger Universe](/reference/universe/README). +- `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict. +- `&`: also merge the following values at the same key... +- `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG. ### Exploring a package documentation But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`? -Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). +Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](/reference/universe/README). ```shell dagger doc dagger.io/netlify dagger doc dagger.io/js/yarn ``` -You can also browse the [Dagger Universe](/reference/universe) reference in the documentation. +You can also browse the [Dagger Universe](/reference/universe/README) reference in the documentation. ## Setup the environment From b03e695970902273c15804fefc2aa6f2603c01cf Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Wed, 23 Jun 2021 10:49:19 +0200 Subject: [PATCH 4/6] docs: stdlib index sorted alphabetically Signed-off-by: Sam Alba --- cmd/dagger/cmd/doc.go | 29 +++++++++++++++------- docs/reference/universe/README.md | 40 +++++++++++++++---------------- 2 files changed, 41 insertions(+), 28 deletions(-) diff --git a/cmd/dagger/cmd/doc.go b/cmd/dagger/cmd/doc.go index 453ecb9b..0e91fc6e 100644 --- a/cmd/dagger/cmd/doc.go +++ b/cmd/dagger/cmd/doc.go @@ -8,6 +8,7 @@ import ( "os" "path" "path/filepath" + "sort" "strings" "text/tabwriter" "unicode/utf8" @@ -365,6 +366,17 @@ func walkStdlib(ctx context.Context, output, format string) { return false } + // get filename from a package name + getFileName := func(p string) string { + filename := fmt.Sprintf("%s.%s", p, format) + // If this package has sub-packages (e.g. `aws`), create + // `aws/README.md` instead of `aws.md`. + if hasSubPackages(p) { + filename = fmt.Sprintf("%s/README.%s", p, format) + } + return filename + } + // Create main index index, err := os.Create(path.Join(output, "README.md")) if err != nil { @@ -372,14 +384,10 @@ func walkStdlib(ctx context.Context, output, format string) { } defer index.Close() fmt.Fprintf(index, "# Index\n\n") + indexKeys := []string{} for p, pkg := range packages { - filename := fmt.Sprintf("%s.%s", p, format) - // If this package has sub-packages (e.g. `aws`), create - // `aws/README.md` instead of `aws.md`. - if hasSubPackages(p) { - filename = fmt.Sprintf("%s/README.%s", p, format) - } + filename := getFileName(p) filepath := path.Join(output, filename) if err := os.MkdirAll(path.Dir(filepath), 0755); err != nil { @@ -392,8 +400,13 @@ func walkStdlib(ctx context.Context, output, format string) { } defer f.Close() - // FIXME: sort packages by name - fmt.Fprintf(index, "- [%s](./%s)\n", p, filename) + indexKeys = append(indexKeys, p) fmt.Fprintf(f, "%s", pkg.Format(format)) } + + // Generate index from sorted list of packages + sort.Strings(indexKeys) + for _, p := range indexKeys { + fmt.Fprintf(index, "- [%s](./%s)\n", p, getFileName(p)) + } } diff --git a/docs/reference/universe/README.md b/docs/reference/universe/README.md index 97837fff..3ce061f4 100644 --- a/docs/reference/universe/README.md +++ b/docs/reference/universe/README.md @@ -1,28 +1,28 @@ # Index -- [aws](./aws/README.md) -- [aws/ecr](./aws/ecr.md) -- [aws/rds](./aws/rds.md) -- [git](./git.md) -- [kubernetes](./kubernetes/README.md) -- [terraform](./terraform.md) -- [random](./random.md) -- [aws/ecs](./aws/ecs.md) -- [aws/s3](./aws/s3.md) -- [dagger/op](./dagger/op.md) -- [gcp](./gcp/README.md) -- [go](./go.md) -- [js/yarn](./js/yarn.md) -- [kubernetes/helm](./kubernetes/helm.md) -- [docker](./docker.md) -- [gcp/gcr](./gcp/gcr.md) -- [gcp/gke](./gcp/gke.md) -- [io](./io.md) -- [kubernetes/kustomize](./kubernetes/kustomize.md) -- [os](./os.md) - [alpine](./alpine.md) +- [aws](./aws/README.md) - [aws/cloudformation](./aws/cloudformation.md) +- [aws/ecr](./aws/ecr.md) +- [aws/ecs](./aws/ecs.md) - [aws/eks](./aws/eks.md) - [aws/elb](./aws/elb.md) +- [aws/rds](./aws/rds.md) +- [aws/s3](./aws/s3.md) - [dagger](./dagger/README.md) +- [dagger/op](./dagger/op.md) +- [docker](./docker.md) +- [gcp](./gcp/README.md) +- [gcp/gcr](./gcp/gcr.md) +- [gcp/gke](./gcp/gke.md) +- [git](./git.md) +- [go](./go.md) +- [io](./io.md) +- [js/yarn](./js/yarn.md) +- [kubernetes](./kubernetes/README.md) +- [kubernetes/helm](./kubernetes/helm.md) +- [kubernetes/kustomize](./kubernetes/kustomize.md) - [netlify](./netlify.md) +- [os](./os.md) +- [random](./random.md) +- [terraform](./terraform.md) From 29ace62b722bbebf20f0ed2d3fef0910e0973a5a Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Wed, 23 Jun 2021 10:53:03 +0200 Subject: [PATCH 5/6] docs: 102: use source link instead Signed-off-by: Sam Alba --- docs/learn/102-dev.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/learn/102-dev.md b/docs/learn/102-dev.md index 91edcea5..8936fa8f 100644 --- a/docs/learn/102-dev.md +++ b/docs/learn/102-dev.md @@ -165,7 +165,7 @@ app: yarn.#Package & { Let's break it down: - `package multibucket`: this file is part of the multibucket package -- `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](/reference/universe/README). +- `import ( "dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/universe/README.md). - `app: yarn.#Package`: apply the `#Package` definition at the key `app` - `&`: also merge the following values at the same key... - `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG. @@ -194,7 +194,7 @@ site: "netlify": netlify.#Site & { This is very similar to the previous component: - We use the same package name as the other files -- We import another package from the [Dagger Universe](/reference/universe/README). +- We import another package from the [Dagger Universe](../reference/universe/README.md). - `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict. - `&`: also merge the following values at the same key... - `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG. @@ -202,14 +202,14 @@ This is very similar to the previous component: ### Exploring a package documentation But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`? -Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](/reference/universe/README). +Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](../reference/universe/README.md). ```shell dagger doc dagger.io/netlify dagger doc dagger.io/js/yarn ``` -You can also browse the [Dagger Universe](/reference/universe/README) reference in the documentation. +You can also browse the [Dagger Universe](../reference/universe/README.md) reference in the documentation. ## Setup the environment From af82c2c910c9b5d3dd68de30c59a9e169a8934a5 Mon Sep 17 00:00:00 2001 From: Sam Alba Date: Wed, 23 Jun 2021 11:05:58 +0200 Subject: [PATCH 6/6] docs: adds package description to the stdlib Index Signed-off-by: Sam Alba --- cmd/dagger/cmd/doc.go | 3 +- docs/reference/universe/README.md | 52 ++++++++++++------------ docs/reference/universe/dagger/README.md | 2 + docs/reference/universe/os.md | 2 + stdlib/dagger/dagger.cue | 1 + stdlib/os/file.cue | 1 + 6 files changed, 34 insertions(+), 27 deletions(-) diff --git a/cmd/dagger/cmd/doc.go b/cmd/dagger/cmd/doc.go index 0e91fc6e..6174e4cf 100644 --- a/cmd/dagger/cmd/doc.go +++ b/cmd/dagger/cmd/doc.go @@ -407,6 +407,7 @@ func walkStdlib(ctx context.Context, output, format string) { // Generate index from sorted list of packages sort.Strings(indexKeys) for _, p := range indexKeys { - fmt.Fprintf(index, "- [%s](./%s)\n", p, getFileName(p)) + description := mdEscape(packages[p].Description) + fmt.Fprintf(index, "- [%s](./%s) - %s\n", p, getFileName(p), description) } } diff --git a/docs/reference/universe/README.md b/docs/reference/universe/README.md index 3ce061f4..baff9870 100644 --- a/docs/reference/universe/README.md +++ b/docs/reference/universe/README.md @@ -1,28 +1,28 @@ # Index -- [alpine](./alpine.md) -- [aws](./aws/README.md) -- [aws/cloudformation](./aws/cloudformation.md) -- [aws/ecr](./aws/ecr.md) -- [aws/ecs](./aws/ecs.md) -- [aws/eks](./aws/eks.md) -- [aws/elb](./aws/elb.md) -- [aws/rds](./aws/rds.md) -- [aws/s3](./aws/s3.md) -- [dagger](./dagger/README.md) -- [dagger/op](./dagger/op.md) -- [docker](./docker.md) -- [gcp](./gcp/README.md) -- [gcp/gcr](./gcp/gcr.md) -- [gcp/gke](./gcp/gke.md) -- [git](./git.md) -- [go](./go.md) -- [io](./io.md) -- [js/yarn](./js/yarn.md) -- [kubernetes](./kubernetes/README.md) -- [kubernetes/helm](./kubernetes/helm.md) -- [kubernetes/kustomize](./kubernetes/kustomize.md) -- [netlify](./netlify.md) -- [os](./os.md) -- [random](./random.md) -- [terraform](./terraform.md) +- [alpine](./alpine.md) - Base package for Alpine Linux +- [aws](./aws/README.md) - AWS base package +- [aws/cloudformation](./aws/cloudformation.md) - AWS CloudFormation +- [aws/ecr](./aws/ecr.md) - Amazon Elastic Container Registry (ECR) +- [aws/ecs](./aws/ecs.md) - AWS Elastic Container Service (ECS) +- [aws/eks](./aws/eks.md) - AWS Elastic Kubernetes Service (EKS) +- [aws/elb](./aws/elb.md) - AWS Elastic Load Balancer (ELBv2) +- [aws/rds](./aws/rds.md) - AWS Relational Database Service (RDS) +- [aws/s3](./aws/s3.md) - AWS Simple Storage Service +- [dagger](./dagger/README.md) - Dagger core types +- [dagger/op](./dagger/op.md) - op: low-level operations for Dagger processing pipelines +- [docker](./docker.md) - Docker container operations +- [gcp](./gcp/README.md) - Google Cloud Platform +- [gcp/gcr](./gcp/gcr.md) - Google Container Registry +- [gcp/gke](./gcp/gke.md) - Google Kubernetes Engine +- [git](./git.md) - Git operations +- [go](./go.md) - Go build operations +- [io](./io.md) - IO operations +- [js/yarn](./js/yarn.md) - Yarn is a package manager for Javascript applications +- [kubernetes](./kubernetes/README.md) - Kubernetes client operations +- [kubernetes/helm](./kubernetes/helm.md) - Helm package manager +- [kubernetes/kustomize](./kubernetes/kustomize.md) - Kustomize config management +- [netlify](./netlify.md) - Netlify client operations +- [os](./os.md) - OS operations +- [random](./random.md) - Random generation utilities +- [terraform](./terraform.md) - Terraform operations diff --git a/docs/reference/universe/dagger/README.md b/docs/reference/universe/dagger/README.md index 83e7c398..b25bc93c 100644 --- a/docs/reference/universe/dagger/README.md +++ b/docs/reference/universe/dagger/README.md @@ -4,6 +4,8 @@ sidebar_label: dagger # dagger.io/dagger +Dagger core types + ```cue import "dagger.io/dagger" ``` diff --git a/docs/reference/universe/os.md b/docs/reference/universe/os.md index 48309e3d..73de74c9 100644 --- a/docs/reference/universe/os.md +++ b/docs/reference/universe/os.md @@ -4,6 +4,8 @@ sidebar_label: os # dagger.io/os +OS operations + ```cue import "dagger.io/os" ``` diff --git a/stdlib/dagger/dagger.cue b/stdlib/dagger/dagger.cue index f0463135..28b67351 100644 --- a/stdlib/dagger/dagger.cue +++ b/stdlib/dagger/dagger.cue @@ -1,3 +1,4 @@ +// Dagger core types package dagger import ( diff --git a/stdlib/os/file.cue b/stdlib/os/file.cue index b484374f..5714c010 100644 --- a/stdlib/os/file.cue +++ b/stdlib/os/file.cue @@ -1,3 +1,4 @@ +// OS operations package os import (