wip: more docs

docs/mkdocs.yml

@@ -5,6 +5,16 @@ copyright: © 2024 Input Output Global Ltd.
 
 docs_dir: src
 
+nav:
+  - Overview: index.md
+  - Installation: installation.md
+  - Tutorials:
+    - Getting Started: tutorials/getting_started.md
+  - Concepts:
+    - CI: concepts/ci.md
+  - Reference:
+    - Targets: reference/targets.md
+
 theme:
   name: material
   icon:

docs/src/reference/targets.md

@@ -60,4 +60,140 @@ build:
 
     # Save the resulting binary as an artifact
     SAVE ARTIFACT bin/program program
+```
+
+## Package
+
+The `package` target is used for packaging dependent projects together.
+In some cases, a larger piece of software may be broken up into multiple projects inside of a repository.
+The `package` target should be used to create the final artifact for the projects.
+
+For example, there may be one project reponsible for building static assets and another project building the server binary that
+depends on those assets.
+The server binary should utilize the `package` target to pull in the static assets and package them with the binary into a final
+artifact.
+
+### Example
+
+```earthly
+package:
+    FROM scratch
+
+    RUN mkdir dist
+    COPY +build/program dist/program
+    COPY ../assets+build dist/assets
+
+    SAVE ARTIFACT dist
+```
+
+## Test
+
+The `test` target is used for running both unit and integration tests.
+The target is often run in privileged mode to make use of docker-in-docker for running complex integration tests.
+This target is intentionally run after both the `build` and `package` targets in order to allow using the resulting artifacts and
+maximize caching.
+
+The `test` target is the final validation step in the CI pipeline.
+The targets that follow assume that if the `test` target passes, the project is ready to be released, published, or deployed.
+It is therefore recommended that all necessary validation logic is included between the `check` and `test` targets.
+
+### Example
+
+```earthly
+test:
+    # Assume we've copied the source code in a previous target
+    FROM +src
+
+    # Run our unit tests
+    RUN go test ./...
+```
+
+## Publish
+
+The `publish` target is used to generate the container for a project.
+It is an error to define the target and not generate an image and the CI system expects only a single image.
+The contents of the image are project-specific, but it's often the artifacts generated by the project in a deployable form.
+For example, an API server may copy the server binary into a vanilla image and automatically set it as the default entrypoint.
+
+The `publish` target must expose two arguments: `container` and `image`.
+These arguments are given values at runtime by the CI system.
+The arguments should be used when saving the final image name and tag (see the example below).
+Omitting these arguments will cause the CI system to fail to find the saved image.
+
+After the `publish` target is ran for a project, the CI system automatically publishes the resulting container image to all
+configured container registries.
+In the case where multiple platforms are specified for a project, the CI system will first upload each platform-specific image to
+all registries and then create a single multi-platform manifest that points to the images.
+Each image is tagged based on the tagging strategy defined in the blueprint global settings.
+
+### Example
+
+```earthly
+publish:
+    FROM debian:bookworm-slim
+
+    ARG container
+    ARG tag
+
+    COPY +build/program program
+
+    ENTRYPOINT ["/program"]
+    SAVE IMAGE ${container}:${tag}
+```
+
+## Release
+
+The `release` target is used for creating
+[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) for a project.
+The target must produce at least one artifact.
+The contents of the artifact are specific to the project.
+For example, the artifact may be the binary file for a compiled project or a directory of assets for a frontend project.
+
+After the `release` target is ran for a project, the CI system will check if there's a git tag present in the current run context.
+If a tag is found it will be compared against the current project to ensure it matches.
+In the case of a match, the CI system will then create a new GitHub release using the git tag as the name.
+Finally, the CI system will archive and compress the artifact produced by the `release` target and attach it as an asset to the
+release.
+
+In the case where multiple platforms are specified for a project, the system will archive and compress each artifact separately.
+The generated archive name will have the associated platform added as a suffix in the file name.
+All archives will then be attached to the generated release as assets.
+
+### Example
+
+```earthly
+release:
+    FROM scratch
+
+    COPY +build/program program
+
+    SAVE ARTIFACT program
+```
+
+## Docs
+
+!!! warning
+
+    Only one `docs` target should be specified per repository.
+    Defining more than one of these targets leads to undefined behavior.
+    In the case where documentation is contained within a project, it should be copied from that project and included in the final
+    artifact created by the target.
+
+The `docs` target is a special target used for uploading documentation to [GitHub Pages](https://pages.github.com/).
+The target should produce a single directory that contains all of the static assets for the documentation.
+The CI system will automatically publish the generated documentation to the default `gh-pages` branch.
+
+In the case where the target is running outside of the default branch (i.e., `main` or `master`) the generated documentation will be
+published to a subfolder within the `gh-pages` branch.
+The subfolder will be named after the branch name.
+This allows previewing documentation generated by a branch by appending the branch name to the URL configured within GitHub Pages.
+
+
+### Example
+
+```earthly
+docs:
+    FROM +build
+
+    SAVE ARTIFACT dist
 ```