docs: ♻️ merge API Reference and Universe menu entries
Signed-off-by: jffarge <jf@dagger.io>
This commit is contained in:
parent
a0d133c998
commit
a2088a09ac
4
Makefile
4
Makefile
@ -59,11 +59,11 @@ install: dagger
|
|||||||
|
|
||||||
.PHONY: docs
|
.PHONY: docs
|
||||||
docs: dagger
|
docs: dagger
|
||||||
./cmd/dagger/dagger doc --output ./docs/reference/universe --format md
|
./cmd/dagger/dagger doc --output ./docs/reference --format md
|
||||||
|
|
||||||
.PHONY: docslint
|
.PHONY: docslint
|
||||||
docslint: docs
|
docslint: docs
|
||||||
@test -z "$$(git status -s . | grep -e "^ M" | grep docs/reference/universe | cut -d ' ' -f3 | tee /dev/stderr)"
|
@test -z "$$(git status -s . | grep -e "^ M" | grep docs/reference | cut -d ' ' -f3 | tee /dev/stderr)"
|
||||||
|
|
||||||
.PHONY: web
|
.PHONY: web
|
||||||
web:
|
web:
|
||||||
|
@ -131,6 +131,7 @@ In Dagger terms, this component has two essential properties:
|
|||||||
Let's write the corresponding Cue code to a new file in our package:
|
Let's write the corresponding Cue code to a new file in our package:
|
||||||
|
|
||||||
```cue file=./tests/multibucket/source.cue title="todoapp/cue.mod/multibucket/source.cue"
|
```cue file=./tests/multibucket/source.cue title="todoapp/cue.mod/multibucket/source.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This code defines a component at the key `src` and specifies that it is both an artifact and an input.
|
This code defines a component at the key `src` and specifies that it is both an artifact and an input.
|
||||||
@ -140,12 +141,13 @@ This code defines a component at the key `src` and specifies that it is both an
|
|||||||
The second component of our plan is the Yarn package built from the app source code:
|
The second component of our plan is the Yarn package built from the app source code:
|
||||||
|
|
||||||
```cue file=./tests/multibucket/yarn.cue title="todoapp/cue.mod/multibucket/yarn.cue"
|
```cue file=./tests/multibucket/yarn.cue title="todoapp/cue.mod/multibucket/yarn.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Let's break it down:
|
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 ( "alpha.dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/universe/README.md).
|
- `import ( "alpha.dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/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 snippet of code connects our two components, forming the first link in our DAG
|
- `{ source: src }`: set the key `app.source` to the value of `src`. This snippet of code connects our two components, forming the first link in our DAG
|
||||||
@ -159,12 +161,13 @@ _FIXME_: this section is not yet available because the [Amazon S3 package](https
|
|||||||
The third component of our plan is the Netlify site to which the app will be deployed:
|
The third component of our plan is the Netlify site to which the app will be deployed:
|
||||||
|
|
||||||
```cue file=./tests/multibucket/netlify.cue title="todoapp/cue.mod/multibucket/netlify.cue"
|
```cue file=./tests/multibucket/netlify.cue title="todoapp/cue.mod/multibucket/netlify.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This component is very similar to the previous one:
|
This component is very similar to the previous one:
|
||||||
|
|
||||||
- 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](../reference/universe/README.md).
|
- We import another package from the [Dagger Universe](../reference/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 line 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 line connects our components 2 and 3, forming the second link in our DAG.
|
||||||
@ -172,14 +175,14 @@ This component is very similar to the previous one:
|
|||||||
### Exploring a package documentation
|
### Exploring a package documentation
|
||||||
|
|
||||||
But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`?
|
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.md).
|
Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](../reference/README.md).
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
dagger doc alpha.dagger.io/netlify
|
dagger doc alpha.dagger.io/netlify
|
||||||
dagger doc alpha.dagger.io/js/yarn
|
dagger doc alpha.dagger.io/js/yarn
|
||||||
```
|
```
|
||||||
|
|
||||||
You can also browse the [Dagger Universe](../reference/universe/README.md) reference in the documentation.
|
You can also browse the [Dagger Universe](../reference/README.md) reference in the documentation.
|
||||||
|
|
||||||
## Setup the environment
|
## Setup the environment
|
||||||
|
|
||||||
|
@ -18,7 +18,7 @@ The provisioning strategy detailed below follows S3 best practices. However, to
|
|||||||
|
|
||||||
#### Relays
|
#### Relays
|
||||||
|
|
||||||
The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](../reference/universe/aws/cloudformation.md) is the Cloudformation one.
|
The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](../reference/aws/cloudformation.md) is the Cloudformation one.
|
||||||
|
|
||||||
## Initialize a Dagger Workspace and Environment
|
## Initialize a Dagger Workspace and Environment
|
||||||
|
|
||||||
@ -67,11 +67,12 @@ The idea here is to follow best practices in [S3 buckets](https://docs.aws.amazo
|
|||||||
Create a file named `template.cue` and add the following configuration to it.
|
Create a file named `template.cue` and add the following configuration to it.
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/template.cue title="todoapp/cloudformation/template.cue"
|
```cue file=./tests/cloudformation/template.cue title="todoapp/cloudformation/template.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
##### 2. Cloudformation relay
|
##### 2. Cloudformation relay
|
||||||
|
|
||||||
As our plan relies on [Cloudformation's relay](../reference/universe/aws/cloudformation.md), let's dissect the expected inputs by gradually incorporating them into our plan.
|
As our plan relies on [Cloudformation's relay](../reference/aws/cloudformation.md), let's dissect the expected inputs by gradually incorporating them into our plan.
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
dagger doc alpha.dagger.io/aws/cloudformation
|
dagger doc alpha.dagger.io/aws/cloudformation
|
||||||
@ -104,6 +105,7 @@ The config values are all part of the `aws` relay. Regarding this package, as yo
|
|||||||
Let's implement the first step, use the `aws.#Config` relay, and request its first inputs: the region to deploy and the AWS credentials.
|
Let's implement the first step, use the `aws.#Config` relay, and request its first inputs: the region to deploy and the AWS credentials.
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/source-begin.cue title="todoapp/cloudformation/source.cue"
|
```cue file=./tests/cloudformation/source-begin.cue title="todoapp/cloudformation/source.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This defines:
|
This defines:
|
||||||
@ -146,6 +148,7 @@ dagger up -e cloudformation # Try to run the plan. As expected, we encounter a f
|
|||||||
Now that we have the `config` definition properly configured, let's modify the Cloudformation one:
|
Now that we have the `config` definition properly configured, let's modify the Cloudformation one:
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This defines:
|
This defines:
|
||||||
@ -265,6 +268,7 @@ import Tabs from "@theme/Tabs";
|
|||||||
import TabItem from "@theme/TabItem";
|
import TabItem from "@theme/TabItem";
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/template/convert.cue title="todoapp/cloudformation/convert.cue"
|
```cue file=./tests/cloudformation/template/convert.cue title="todoapp/cloudformation/convert.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This defines:
|
This defines:
|
||||||
@ -308,6 +312,7 @@ rm cloudformation/convert.cue
|
|||||||
Open `cloudformation/template.cue` and append below elements with copied Cue definition of the JSON:
|
Open `cloudformation/template.cue` and append below elements with copied Cue definition of the JSON:
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/template/template-begin.cue title="todoapp/cloudformation/template.cue"
|
```cue file=./tests/cloudformation/template/template-begin.cue title="todoapp/cloudformation/template.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
We're using the built-in `json.Marshal` function to convert CUE back to JSON, so Cloudformation still receives the same template.
|
We're using the built-in `json.Marshal` function to convert CUE back to JSON, so Cloudformation still receives the same template.
|
||||||
@ -323,11 +328,13 @@ Now that the template is defined in CUE, we can use the language to add more fle
|
|||||||
Let's define a re-usable `#Deployment` definition in `todoapp/cloudformation/deployment.cue`:
|
Let's define a re-usable `#Deployment` definition in `todoapp/cloudformation/deployment.cue`:
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/template/deployment.cue title="todoapp/cloudformation/deployment.cue"
|
```cue file=./tests/cloudformation/template/deployment.cue title="todoapp/cloudformation/deployment.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`template.cue` can be rewritten as follows:
|
`template.cue` can be rewritten as follows:
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/template/template-end.cue title="todoapp/cloudformation/template.cue"
|
```cue file=./tests/cloudformation/template/template-end.cue title="todoapp/cloudformation/template.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Verify template
|
Verify template
|
||||||
@ -360,6 +367,7 @@ dagger query template -f text -e cloudformation
|
|||||||
Reimplement `source.cue`:
|
Reimplement `source.cue`:
|
||||||
|
|
||||||
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
And we can now deploy it:
|
And we can now deploy it:
|
||||||
|
@ -1,5 +1,5 @@
|
|||||||
{
|
{
|
||||||
"label": "API Reference",
|
"label": "Universe - API Reference",
|
||||||
"position": 5,
|
"position": 5,
|
||||||
"collapsed": false
|
"collapsed": false
|
||||||
}
|
}
|
||||||
|
@ -1,3 +0,0 @@
|
|||||||
{
|
|
||||||
"label": "Universe"
|
|
||||||
}
|
|
@ -22,7 +22,7 @@ Dagger is the perfect tool for CI workflows.
|
|||||||
frontend? The backend won't be built again.
|
frontend? The backend won't be built again.
|
||||||
- **Composable & Reusable**. Define re-usable steps and [share](../learn/1010-dev-cue-package.md) them across all
|
- **Composable & Reusable**. Define re-usable steps and [share](../learn/1010-dev-cue-package.md) them across all
|
||||||
your projects. Or with the world. Dagger
|
your projects. Or with the world. Dagger
|
||||||
ships with [dozens of re-usable components](../reference/universe/README.md)
|
ships with [dozens of re-usable components](../reference/README.md)
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
@ -71,9 +71,9 @@ lint: os.#Container & {
|
|||||||
The configuration above defines:
|
The configuration above defines:
|
||||||
|
|
||||||
- **source** code of the project. More on this later.
|
- **source** code of the project. More on this later.
|
||||||
- **test** *task* which executes `go test` inside the source artifact
|
- **test** _task_ which executes `go test` inside the source artifact
|
||||||
using the `golang` Docker image
|
using the `golang` Docker image
|
||||||
- **lint** *task* which executes `golangci-lint` inside the source artifact
|
- **lint** _task_ which executes `golangci-lint` inside the source artifact
|
||||||
using the `golangci-lint` Docker image.
|
using the `golangci-lint` Docker image.
|
||||||
|
|
||||||
Before we can execute the configuration, we need to set up the Dagger workspace and environment.
|
Before we can execute the configuration, we need to set up the Dagger workspace and environment.
|
||||||
@ -118,7 +118,7 @@ integration with GitHub easier.
|
|||||||
Dagger workflows scale really well with CI complexity.
|
Dagger workflows scale really well with CI complexity.
|
||||||
|
|
||||||
The following example illustrates how to test two different projects in the same
|
The following example illustrates how to test two different projects in the same
|
||||||
repository: a *Node* frontend (located in *./frontend*) along with a *Go* backend (located in *./backend*).
|
repository: a _Node_ frontend (located in _./frontend_) along with a _Go_ backend (located in _./backend_).
|
||||||
|
|
||||||
From the project repository, update the file named `ci/main.cue` with the
|
From the project repository, update the file named `ci/main.cue` with the
|
||||||
following configuration.
|
following configuration.
|
||||||
@ -180,7 +180,7 @@ frontend: {
|
|||||||
Larger configurations can be split into multiple files, for example `backend.cue` and `frontend.cue`
|
Larger configurations can be split into multiple files, for example `backend.cue` and `frontend.cue`
|
||||||
:::
|
:::
|
||||||
|
|
||||||
The configuration above defines a *frontend* and *backend* structure, each
|
The configuration above defines a _frontend_ and _backend_ structure, each
|
||||||
containing:
|
containing:
|
||||||
|
|
||||||
- A **code** directory, defined as a subdirectory of **source**
|
- A **code** directory, defined as a subdirectory of **source**
|
||||||
@ -199,5 +199,5 @@ $ dagger up
|
|||||||
`frontend.test` and `backend.test` are running in parallel since there are no
|
`frontend.test` and `backend.test` are running in parallel since there are no
|
||||||
dependencies between each other.
|
dependencies between each other.
|
||||||
|
|
||||||
If you were to make changes to the *./frontend* directory, only
|
If you were to make changes to the _./frontend_ directory, only
|
||||||
`frontend.test` will be executed.
|
`frontend.test` will be executed.
|
||||||
|
@ -47,5 +47,5 @@ status = 200
|
|||||||
|
|
||||||
[[redirects]]
|
[[redirects]]
|
||||||
from = "/reference"
|
from = "/reference"
|
||||||
to = "/reference/universe/alpine"
|
to = "/reference/alpine"
|
||||||
status = 302
|
status = 302
|
||||||
|
Reference in New Issue
Block a user