docs: Updates quickstart examples #7172

vikram-dagger · 2024-04-24T08:47:03Z

This is the first in a series of commits to improve the Dagger quickstart. In response to user feedback that some of the examples are too simplistic and "hello world"-y, this commit tightens up the current quickstart to remove or update those examples. Larger structural changes will follow in separate PRs.

Signed-off-by: Vikram Vaswani <[email protected]>

levlaz

This is a big improvement, I love the new examples, I added a bit of feedback.

levlaz · 2024-04-25T03:55:16Z

docs/current_docs/quickstart/562821-hello.mdx

+```
+
+:::tip
+All of Dagger's core types - `Directory`, `File`, `Container`, `Service`, `Secret` and others - can be used as arguments by Dagger Functions. It's important to know that these core types are not merely strings referencing local or remote resources; they are actual representations of the corresponding resource states, managed by the Dagger Engine, and passed to and between Dagger Functions like other variables. This feature, as far as we know, is unique to Dagger, and opens endless possibilities for assembling complex pipelines where container state flows from function to function - in just a few lines of code.


and others

We said this in a few places, are there other core types? If so, why not list them all here?

It's important to know that

This feels excessive, its already important since we put it in this callout block.

This feature, as far as we know, is unique to Dagger, and opens endless possibilities for assembling complex pipelines where container state flows from function to function - in just a few lines of code.

This one feels a bit too "markety" for me.

levlaz · 2024-04-25T03:58:31Z

docs/current_docs/quickstart/853930-directories.mdx

@@ -21,7 +20,7 @@ Try calling this Go builder function:
 dagger -m github.com/kpenfound/dagger-modules/[email protected] call build --project https://github.com/dagger/dagger --args ./cmd/dagger
 ```

-This function takes a `proj` argument of type `Directory`. Similar to how the CLI can pass a `Container` from a remote OCI address, it can also pass a `Directory` from a local path or remote Git address. Here, you're passing the address of Dagger's open-source repository.
+This function takes a `project` argument of type `Directory`. Here, you're passing the address of Dagger's open-source repository.


I think we should also describe what the --args ./cmd/dagger argument does.

levlaz · 2024-04-25T04:07:14Z

docs/current_docs/quickstart/853930-directories.mdx

The final export example only works with linux, I think we should make a note of that somehow or update the function to accept an OS argument.

http://localhost:3000/quickstart/853930/directories#export-the-build-directory

This is done in a previous commit using uname

levlaz · 2024-04-25T04:14:02Z

docs/current_docs/quickstart/883939-containers.mdx

 ```

 ### Publish the container image to a registry

-The `Container` type also has a `Publish()` function, which publishes the container to a registry. To see this in action, call the previous function again, this time chaining an additional function call to `Publish()` on the returned `Container`:
+The `Container` type also makes a number of other functions available. To see some of these in action, call the previous function again, chaining additional function calls to `WithEntrypoint()` and `Publish()` on the returned `Container` to, respectively, set the container entrypoint command and publish it to a registry:


, respectively, feels excessive, I think removing it makes it easier to read this sentence.

docs/current_docs/quickstart/883939-containers.mdx

levlaz · 2024-04-25T04:16:34Z

docs/current_docs/quickstart/822194-daggerize.mdx

-1. Initialize a new Dagger Module with `dagger init`
-2. Install other useful Dagger Modules as dependencies with `dagger install`
+1. Initialize a new Dagger module with `dagger init`
+2. Install other useful Dagger modules as dependencies with `dagger install`


Perhaps this is a good place to link to the daggerverse, otherwise what would someone be installing?

docs/current_docs/quickstart/822194-daggerize.mdx

levlaz · 2024-04-25T04:22:57Z

docs/current_docs/quickstart/428201-custom-function.mdx

@@ -14,14 +14,14 @@ So far, you've been calling individual Dagger Functions using the Dagger CLI. Bu

 One option is, of course, to stitch together calls using the CLI and a shell script or a Makefile However, this approach is not recommended, because you will typically end up with long and unwieldy CLI commands and shell scripting "glue" that is hard to debug and maintain.


, of course,

I think this style makes sense in conversation but feels cumbersome to read.

levlaz · 2024-04-25T04:24:39Z

docs/current_docs/quickstart/428201-custom-function.mdx


-By creating your own Dagger Module and installing other modules into it, you can express more complex workflows and operations by reusing modules created by others and connecting them together using the programming language you're most comfortable with.
+By creating your own Dagger Function, you can express more complex workflows and operations by reusing Dagger Functions created by others and connecting them together using the programming language you're most comfortable with.


Creating your own Dagger Function(s) enables you to transform your workflows into structured, discrete and composable units with clear inputs and outputs, with all the benefits of using a native programming language.

By creating your own Dagger Function, you can express more complex workflows and operations by reusing Dagger Functions created by others and connecting them together using the programming language you're most comfortable with.

It feels like this repeats the previous sentence.

levlaz · 2024-04-25T04:32:27Z

docs/current_docs/quickstart/428201-custom-function.mdx

Can we update the main sample formatting to be a bit easier to read and write?

func (m *Example) BuildAndPublish( ctx context.Context, buildSrc *Directory, buildArgs []string, ) (string, error) { ctr := dag.Wolfi().Container() return dag. Golang(). BuildContainer( GolangBuildContainerOpts{ Source: buildSrc, Args: buildArgs, Base: ctr, }). Publish( ctx, fmt.Sprintf( "ttl.sh/my-hello-container-%.0f", math.Floor(rand.Float64()*10000000), ), ) }

Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger

Added feedback

vikram-dagger · 2024-04-25T14:48:14Z

docs/current_docs/quickstart/562821-hello.mdx

+```
+
+:::tip
+All of Dagger's core types - `Directory`, `File`, `Container`, `Service`, `Secret` and others - can be used as arguments by Dagger Functions. It's important to know that these core types are not merely strings referencing local or remote resources; they are actual representations of the corresponding resource states, managed by the Dagger Engine, and passed to and between Dagger Functions like other variables. This feature, as far as we know, is unique to Dagger, and opens endless possibilities for assembling complex pipelines where container state flows from function to function - in just a few lines of code.


vikram-dagger · 2024-04-25T14:49:33Z

docs/current_docs/quickstart/822194-daggerize.mdx

-1. Initialize a new Dagger Module with `dagger init`
-2. Install other useful Dagger Modules as dependencies with `dagger install`
+1. Initialize a new Dagger module with `dagger init`
+2. Install other useful Dagger modules as dependencies with `dagger install`


vikram-dagger · 2024-04-25T14:50:12Z

docs/current_docs/quickstart/853930-directories.mdx

This is done in a previous commit using uname

vikram-dagger · 2024-04-25T14:52:04Z

docs/current_docs/quickstart/853930-directories.mdx

@@ -21,7 +20,7 @@ Try calling this Go builder function:
 dagger -m github.com/kpenfound/dagger-modules/[email protected] call build --project https://github.com/dagger/dagger --args ./cmd/dagger
 ```

-This function takes a `proj` argument of type `Directory`. Similar to how the CLI can pass a `Container` from a remote OCI address, it can also pass a `Directory` from a local path or remote Git address. Here, you're passing the address of Dagger's open-source repository.
+This function takes a `project` argument of type `Directory`. Here, you're passing the address of Dagger's open-source repository.


vikram-dagger · 2024-04-25T14:52:33Z

docs/current_docs/quickstart/883939-containers.mdx

 ```

 ### Publish the container image to a registry

-The `Container` type also has a `Publish()` function, which publishes the container to a registry. To see this in action, call the previous function again, this time chaining an additional function call to `Publish()` on the returned `Container`:
+The `Container` type also makes a number of other functions available. To see some of these in action, call the previous function again, chaining additional function calls to `WithEntrypoint()` and `Publish()` on the returned `Container` to, respectively, set the container entrypoint command and publish it to a registry:


vikram-dagger · 2024-04-25T14:54:13Z

docs/current_docs/quickstart/428201-custom-function.mdx

vikram-dagger · 2024-04-25T14:54:33Z

docs/current_docs/quickstart/428201-custom-function.mdx

@@ -14,14 +14,14 @@ So far, you've been calling individual Dagger Functions using the Dagger CLI. Bu

 One option is, of course, to stitch together calls using the CLI and a shell script or a Makefile However, this approach is not recommended, because you will typically end up with long and unwieldy CLI commands and shell scripting "glue" that is hard to debug and maintain.


vikram-dagger · 2024-04-25T14:54:51Z

docs/current_docs/quickstart/428201-custom-function.mdx


-By creating your own Dagger Module and installing other modules into it, you can express more complex workflows and operations by reusing modules created by others and connecting them together using the programming language you're most comfortable with.
+By creating your own Dagger Function, you can express more complex workflows and operations by reusing Dagger Functions created by others and connecting them together using the programming language you're most comfortable with.


Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger · 2024-04-29T19:55:25Z

Ping @levlaz for second review and @kpenfound for first review

* docs: Updates quickstart examples Signed-off-by: Vikram Vaswani <[email protected]> * Fixed capitalization according to new style guide Signed-off-by: Vikram Vaswani <[email protected]> * Updates examples Signed-off-by: Vikram Vaswani <[email protected]> * Copy fix Signed-off-by: Vikram Vaswani <[email protected]> * Added feedback Signed-off-by: Vikram Vaswani <[email protected]> --------- Signed-off-by: Vikram Vaswani <[email protected]> Signed-off-by: kpenfound <[email protected]>

* docs: Updates quickstart examples Signed-off-by: Vikram Vaswani <[email protected]> * Fixed capitalization according to new style guide Signed-off-by: Vikram Vaswani <[email protected]> * Updates examples Signed-off-by: Vikram Vaswani <[email protected]> * Copy fix Signed-off-by: Vikram Vaswani <[email protected]> * Added feedback Signed-off-by: Vikram Vaswani <[email protected]> --------- Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger added 3 commits April 24, 2024 12:39

docs: Updates quickstart examples

5dd81ff

Signed-off-by: Vikram Vaswani <[email protected]>

Fixed capitalization according to new style guide

1b25b74

Signed-off-by: Vikram Vaswani <[email protected]>

Updates examples

1f4c88a

Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger requested review from shykes and levlaz April 24, 2024 08:47

Copy fix

de8c4e4

Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger requested review from marcosnils and kpenfound April 24, 2024 08:50

levlaz reviewed Apr 25, 2024

View reviewed changes

Merge branch 'main' into improve-qs-2

9e88087

Signed-off-by: Vikram Vaswani <[email protected]>

vikram-dagger commented Apr 25, 2024

View reviewed changes

Added feedback

7e1c14e

Signed-off-by: Vikram Vaswani <[email protected]>

kpenfound approved these changes Apr 30, 2024

View reviewed changes

vikram-dagger merged commit 82c832e into dagger:main Apr 30, 2024
31 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Updates quickstart examples #7172

docs: Updates quickstart examples #7172

vikram-dagger commented Apr 24, 2024 •

edited

levlaz left a comment

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

levlaz Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger left a comment

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger Apr 25, 2024

vikram-dagger commented Apr 29, 2024

		@@ -14,14 +14,14 @@ So far, you've been calling individual Dagger Functions using the Dagger CLI. Bu

		One option is, of course, to stitch together calls using the CLI and a shell script or a Makefile However, this approach is not recommended, because you will typically end up with long and unwieldy CLI commands and shell scripting "glue" that is hard to debug and maintain.


		By creating your own Dagger Module and installing other modules into it, you can express more complex workflows and operations by reusing modules created by others and connecting them together using the programming language you're most comfortable with.
		By creating your own Dagger Function, you can express more complex workflows and operations by reusing Dagger Functions created by others and connecting them together using the programming language you're most comfortable with.

docs: Updates quickstart examples #7172

docs: Updates quickstart examples #7172

Conversation

vikram-dagger commented Apr 24, 2024 • edited

levlaz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vikram-dagger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vikram-dagger commented Apr 29, 2024

vikram-dagger commented Apr 24, 2024 •

edited