From da8e8fbaac4b3b81e4dfc02ad2a4c15e178b409c Mon Sep 17 00:00:00 2001 From: Gerhard Lazu Date: Thu, 10 Mar 2022 16:27:52 +0000 Subject: [PATCH] Extract snippets from docs into separate files So that we get auto-formatting and syntax checking in our code editor. The only snippets which have not been extracted are either terminal output, or file fragments (e.g. CUE) which are not valid standalone files. Resolves https://github.com/dagger/dagger/issues/1715 While at it, do a few fly-by improvements: - beta.1 -> beta.2 - add CUE & BuildKit links - up -> do Signed-off-by: Gerhard Lazu --- docs/core-concepts/1202-plan.md | 28 +------------- docs/getting-started/1200-local-dev.md | 4 +- docs/getting-started/1201-ci-environment.md | 37 ++----------------- docs/learn/1213-api.md | 2 +- .../core-concepts/plan/structure.cue.fragment | 26 +++++++++++++ docs/tests/getting-started/github-actions.yml | 30 +++++++++++++++ 6 files changed, 63 insertions(+), 64 deletions(-) create mode 100644 docs/tests/core-concepts/plan/structure.cue.fragment create mode 100644 docs/tests/getting-started/github-actions.yml diff --git a/docs/core-concepts/1202-plan.md b/docs/core-concepts/1202-plan.md index 43fda49b..47831c5d 100644 --- a/docs/core-concepts/1202-plan.md +++ b/docs/core-concepts/1202-plan.md @@ -15,33 +15,7 @@ This plan is the entrypoint for everything that runs within a pipeline. The simp This is our **Getting Started** example app plan structure: -```cue -dagger.#Plan & { - client: { - filesystem: { - // ... - } - env: { - // ... - } - } - actions: { - deps: docker.#Build & { - // ... - } - test: bash.#Run & { - // ... - } - build: { - run: bash.#Run & { - // ... - } - contents: dagger.#Subdir & { - // ... - } - } - } -} +```cue file=../tests/core-concepts/plan/structure.cue.fragment ``` When the above plan gets executed via `dagger do build`, it produces the following output: diff --git a/docs/getting-started/1200-local-dev.md b/docs/getting-started/1200-local-dev.md index 13401697..9a05e801 100644 --- a/docs/getting-started/1200-local-dev.md +++ b/docs/getting-started/1200-local-dev.md @@ -42,7 +42,7 @@ With Docker running, we are ready to download our example app and run its CI/CD ```shell git clone https://github.com/dagger/dagger cd dagger -git checkout v0.2.0-beta.1 +git checkout v0.2.0-beta.2 cd pkg/universe.dagger.io/examples/todoapp ``` @@ -123,7 +123,7 @@ With Docker Engine running, we are ready to download our example app and run its ```shell git clone https://github.com/dagger/dagger cd dagger -git checkout v0.2.0-beta.1 +git checkout v0.2.0-beta.2 cd pkg/universe.dagger.io/examples/todoapp ``` diff --git a/docs/getting-started/1201-ci-environment.md b/docs/getting-started/1201-ci-environment.md index 81bf1804..d8d2b470 100644 --- a/docs/getting-started/1201-ci-environment.md +++ b/docs/getting-started/1201-ci-environment.md @@ -7,8 +7,8 @@ displayed_sidebar: europa Dagger can be used with any CI environment (no migration required) and has two important advantages which make the overall experience less error-prone and more efficient: -1. Instead of YAML you write CUE: typed configuration with built-in formatting -2. Configuration is executed in buildkit, the execution engine at the heart of Docker +1. Instead of YAML, you write [CUE](https://cuelang.org/) - typed configuration with built-in formatting +2. Configuration is executed in [BuildKit](https://github.com/moby/buildkit), the execution engine at the heart of Docker This makes any CI environment with Docker pre-installed work with Dagger out of the box. We started with [CI environments that you told us you are using](https://github.com/dagger/dagger/discussions/1677). @@ -32,38 +32,7 @@ values={[ -`.github/workflows/todoapp.yml` - -```yaml -name: todoapp - -push: - # Trigger this workflow only on commits pushed to the main branch - branches: - - main - -# Dagger plan gets configured via client environment variables -env: - # This needs to be unique across all of netlify.app - APP_NAME: todoapp-dagger-europa - NETLIFY_TEAM: dagger - # https://app.netlify.com/user/applications/personal - NETLIFY_TOKEN: ${{ secrets.NETLIFY_TOKEN }} - DAGGER_LOG_FORMAT: plain - -jobs: - dagger: - runs-on: ubuntu-latest - steps: - - name: Clone repository - uses: actions/checkout@v2 - - - name: Deploy to Netlify - # https://github.com/dagger/dagger-for-github - uses: dagger/dagger-for-github@v2 - with: - workdir: pkg/universe.dagger.io/examples/todoapp - args: do deploy +```yaml file=../tests/getting-started/github-actions.yml title=".github/workflows/todoapp.yml" ``` diff --git a/docs/learn/1213-api.md b/docs/learn/1213-api.md index f93a5a74..0cd19c9d 100644 --- a/docs/learn/1213-api.md +++ b/docs/learn/1213-api.md @@ -11,7 +11,7 @@ The Dagger CUE API is the set of CUE packages released alongside the Dagger engi ### Plan definition -`#Plan` defines the structure of a Dagger plan - a complete configuration executable by `dagger up`. +`#Plan` defines the structure of a Dagger plan - a complete configuration executable by `dagger do`. ### Core types diff --git a/docs/tests/core-concepts/plan/structure.cue.fragment b/docs/tests/core-concepts/plan/structure.cue.fragment new file mode 100644 index 00000000..df0cceaa --- /dev/null +++ b/docs/tests/core-concepts/plan/structure.cue.fragment @@ -0,0 +1,26 @@ +dagger.#Plan & { + client: { + filesystem: { + // ... + } + env: { + // ... + } + } + actions: { + deps: docker.#Build & { + // ... + } + test: bash.#Run & { + // ... + } + build: { + run: bash.#Run & { + // ... + } + contents: dagger.#Subdir & { + // ... + } + } + } +} diff --git a/docs/tests/getting-started/github-actions.yml b/docs/tests/getting-started/github-actions.yml new file mode 100644 index 00000000..17c18367 --- /dev/null +++ b/docs/tests/getting-started/github-actions.yml @@ -0,0 +1,30 @@ +name: todoapp + +push: + # Trigger this workflow only on commits pushed to the main branch + branches: + - main + +# Dagger plan gets configured via client environment variables +env: + # This needs to be unique across all of netlify.app + APP_NAME: todoapp-dagger-europa + NETLIFY_TEAM: dagger + # Get one from https://app.netlify.com/user/applications/personal + NETLIFY_TOKEN: ${{ secrets.NETLIFY_TOKEN }} + # GitHub Actions friendly logs + DAGGER_LOG_FORMAT: plain + +jobs: + dagger: + runs-on: ubuntu-latest + steps: + - name: Clone repository + uses: actions/checkout@v2 + + - name: Deploy to Netlify + uses: dagger/dagger-for-github@v2 + # See all options at https://github.com/dagger/dagger-for-github + with: + workdir: pkg/universe.dagger.io/examples/todoapp + args: do deploy