kjuulh/dagger
Archived
1
0
Fork 0
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

Merge pull request #707 from samalba/fix-links

Browse Source 
Adds support for stdlib Index
This commit is contained in:
Andrea Luzzardi 2021-06-23 11:24:17 +02:00 committed by GitHub
commit 9984edad09
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 86 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
cmd/dagger/cmd/doc.go
View File

@ -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)
}
}

54
docs/learn/102-dev.md
View File

@ -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.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.
### 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.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.
### 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

28
docs/reference/universe/README.md Normal file
View File

@ -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

2
docs/reference/universe/dagger/README.md
View File

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

2
docs/reference/universe/os.md
View File

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

1
stdlib/dagger/dagger.cue
View File

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

1
stdlib/os/file.cue
View File

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