Merge pull request #707 from samalba/fix-links

Adds support for stdlib Index

cmd/dagger/cmd/doc.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"sort"
 	"strings"
 	"text/tabwriter"
 	"unicode/utf8"
@@ -365,13 +366,28 @@ func walkStdlib(ctx context.Context, output, format string) {
 		return false
 	}
 
-	for p, pkg := range packages {
+	// 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 {
+		lg.Fatal().Err(err).Msg("cannot generate stdlib doc index")
+	}
+	defer index.Close()
+	fmt.Fprintf(index, "# Index\n\n")
+	indexKeys := []string{}
+
+	for p, pkg := range packages {
+		filename := getFileName(p)
 		filepath := path.Join(output, filename)
 
 		if err := os.MkdirAll(path.Dir(filepath), 0755); err != nil {
@@ -384,6 +400,14 @@ func walkStdlib(ctx context.Context, output, format string) {
 		}
 		defer f.Close()
 
+		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 {
+		description := mdEscape(packages[p].Description)
+		fmt.Fprintf(index, "- [%s](./%s) - %s\n", p, getFileName(p), description)
+	}
 }

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
+- Development tools: source control, CI, build systems, testing systems
-* Hosting infrastructure: compute, storage, networking, databases, CDNs
+- Hosting infrastructure: compute, storage, networking, databases, CDNs
-* Software dependencies: operating systems, languages, libraries, frameworks, etc.
+- 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
+- source code flows from a git repository to a build system
-* system dependencies are combined in a docker image, then uploaded to a registry
+- 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
+- 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.
+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.
+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
+- `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).
+- `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`
+- `app: yarn.#Package`: apply the `#Package` definition at the key `app`
-* `&`: also merge the following values at the same key...
+- `&`: 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.
+- `{ 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 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).
+- 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.
+- `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...
+- `&`: 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.
+- `{ 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.md).
 
 ```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.md) reference in the documentation.
 
 ## Setup the environment
 

docs/reference/universe/README.md

@@ -0,0 +1,28 @@
+# Index
+
+- [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

docs/reference/universe/dagger/README.md

@@ -4,6 +4,8 @@ sidebar_label: dagger
 
 # dagger.io/dagger
 
+Dagger core types
+
 ```cue
 import "dagger.io/dagger"
 ```

docs/reference/universe/os.md

@@ -4,6 +4,8 @@ sidebar_label: os
 
 # dagger.io/os
 
+OS operations
+
 ```cue
 import "dagger.io/os"
 ```

stdlib/dagger/dagger.cue

@@ -1,3 +1,4 @@
+// Dagger core types
 package dagger
 
 import (

stdlib/os/file.cue

@@ -1,3 +1,4 @@
+// OS operations
 package os
 
 import (