docs: adds onboarding documentation (#50)

.config/dictionaries/project.dic

@@ -1,13 +1,16 @@
 aarch
 buildkit
 camelcase
+cowsay
 cytopia
 devenv
 dind
 Earthfile
 Earthfiles
 errchkjson
+extldflags
 ginkgolinter
+gitops
 glightbox
 gofmt
 golangci
@@ -22,17 +25,31 @@ gosec
 graphviz
 Kroki
 kubeconfig
+ldflags
 markdownlint
+mattn
 mdlint
 mkdocs
 modcache
+mozallowfullscreen
 multirepo
 nilnil
 nixos
 nixpkgs
 onsi
 pkgs
+projectcatalyst
+pymdownx
 PYTHONDONTWRITEBYTECODE
+rivo
+runewidth
+subproject
+subprojects
+superfences
 testpackage
+transpiling
 UDCs
+uniseg
+webkitallowfullscreen
 WORKDIR
+xerrors

.github/workflows/deploy.yml

@@ -1,3 +1,5 @@
+# WARNING: If you modify this workflow, please update the documentation
+
 on:
   workflow_call:
     inputs:

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Docs
+
+on:
+  push:
+    paths:
+      - "docs/**"
+
+permissions:
+  id-token: write
+  contents: write
+  packages: write
+
+jobs:
+  ci:
+    uses: ./.github/workflows/pages.yml
+    with:
+      aws_role_arn: arn:aws:iam::332405224602:role/ci
+      aws_region: eu-central-1
+      ci_cli_version: 1.3.1
+      earthfile: ./docs
+      target: docs
+    secrets:
+      earthly_runner_address: ${{ secrets.EARTHLY_SATELLITE_ADDRESS }}
+      earthly_runner_secret: ${{ secrets.EARTHLY_RUNNER_SECRET }}

.github/workflows/check.yml → .github/workflows/pages.yml

@@ -1,15 +1,22 @@
+# WARNING: If you modify this workflow, please update the documentation
+
 on:
   workflow_call:
     inputs:
+      earthfile:
+        description: |
+          The path to the folder containing the Earthfile that will be built.
+          This path should be relative to the repository root.
+        required: true
+        type: string
       target:
         description: |
-          The target used to mark check builds. This target should be unique
-          across all Earthly files in the repository. The target should perform
-          all required checks to validate an artifact: linting, formatting, and
-          unit tests are common examples.
+          The target that will be used to build docs. The target should always
+          produce one artifact which is the static site that will be deployed to
+          GitHub Pages.
         required: false
         type: string
-        default: check
+        default: docs
       aws_role_arn:
         description: |
           The ARN of the AWS role that will be assumed by the workflow. Only
@@ -37,7 +44,7 @@ on:
       earthly_runner_address:
         description: |
           The address of the Earthly runner that will be used to build the
-          Earthly files.
+          Earthfile.
         required: false
       earthly_runner_secret:
         description: |
@@ -48,40 +55,8 @@ on:
         required: false
 
 jobs:
-  discover:
+  run:
     runs-on: ubuntu-latest
-    outputs:
-      json: ${{ steps.check.outputs.json }}
-    steps:
-      - uses: actions/checkout@v3
-      - name: Setup CI
-        uses: input-output-hk/catalyst-ci/actions/setup@master
-        with:
-          cli_version: ${{ inputs.ci_cli_version }}
-          earthly_skip_install: "true"
-      - name: Discover Earthly files
-        uses: input-output-hk/catalyst-ci/actions/discover@master
-        id: discover
-        with:
-          targets: ${{ inputs.target }}
-      - name: Check for empty output
-        id: check
-        run: |
-          output=$(echo '${{ steps.discover.outputs.json }}' | jq -rc)
-          if [ "$output" == "null" ]; then
-            echo "json=[]" >> $GITHUB_OUTPUT
-          else
-            echo "json=$output" >> $GITHUB_OUTPUT
-          fi
-
-  build:
-    runs-on: ubuntu-latest
-    needs: [discover]
-    if: needs.discover.outputs.json != '[]'
-    strategy:
-      fail-fast: false
-      matrix:
-        earthfile: ${{ fromJson(needs.discover.outputs.json) }}
     steps:
       - uses: actions/checkout@v3
       - name: Setup CI
@@ -92,10 +67,17 @@ jobs:
           cli_version: ${{ inputs.ci_cli_version }}
           earthly_version: ${{ inputs.earthly_version }}
           earthly_runner_secret: ${{ secrets.earthly_runner_secret }}
-      - name: Check
+      - name: Build docs
         uses: input-output-hk/catalyst-ci/actions/run@master
         id: build
         with:
-          earthfile: ${{ matrix.earthfile }}
+          earthfile: ${{ inputs.earthfile }}
           target: ${{ inputs.target }}
-          runner_address: ${{ secrets.earthly_runner_address }}
+          runner_address: ${{ secrets.earthly_runner_address }}
+          artifact: "true"
+      - name: Publish docs
+        uses: JamesIves/[email protected]
+        if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        with:
+          branch: gh-pages
+          folder: ${{ steps.build.outputs.artifact }}

.github/workflows/publish.yml

@@ -1,3 +1,5 @@
+# WARNING: If you modify this workflow, please update the documentation
+
 on:
   workflow_call:
     inputs:

.github/workflows/release.yml

@@ -1,3 +1,5 @@
+# WARNING: If you modify this workflow, please update the documentation
+
 on:
   workflow_call:
     inputs:

docs/Earthfile

@@ -0,0 +1,16 @@
+VERSION 0.7
+
+deps:
+    FROM python:3.11-bullseye
+    DO ../earthly/python+POETRY_SETUP
+
+src:
+    FROM +deps
+
+    COPY --dir src mkdocs.yml .
+
+docs:
+    FROM +src
+
+    RUN poetry run mkdocs build --strict
+    SAVE ARTIFACT site/*

docs/mkdocs.yml

@@ -0,0 +1,29 @@
+site_name: Catalyst CI Documentation
+docs_dir: src
+theme:
+  name: material
+  features:
+    - navigation.indexes
+    - navigation.tracking
+nav:
+  - Introduction: index.md
+  - Onboarding: onboarding/index.md
+  - Style Guide: style.md
+  - Reference:
+      - reference/index.md
+      - Actions: reference/actions.md
+      - Targets: reference/targets.md
+      - Workflows: reference/workflows.md
+      - UDCs: reference/udc.md
+  - Appendix:
+      - Earthly: appendix/earthly.md
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true